Skip to content

Commit 8275ad2

Browse files
laxa1986laxa1986
committed
fix: update documentation
1 parent 187481d commit 8275ad2

File tree

1 file changed

+97
-20
lines changed

1 file changed

+97
-20
lines changed

‎README.md‎

Lines changed: 97 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,17 @@
11
# About
22

3-
Allows to use Maven backed by AWS CodeArtifact repository in GitHub Actions:
3+
A GitHub action to build maven projects while pulling dependencies from AWS CodeArtifact
4+
5+
What it does:
46
1. Setup Java + Maven
57
2. Authorize in AWS Account with a provided role
68
3. Generate CodeArtifact token and URL and put in env variables
79
4. Compose `settings.xml` and put in a place where Maven can find it
810

9-
Designed to be used in your build workflow when you need to access packages from CodeArtifact.
10-
It is also used in publish workflow to upload packages in CodeArtifact.
11-
For release workflow you likely want to bump a version in `pom.xml` file and add some git tags,
12-
so please check the [agilecustoms/release](https://github.com/agilecustoms/release) action —
13-
it represents a holistic release action (uses `setup-maven-codeartifact` under the hood).
11+
## Usage
1412

15-
For build and publish workflows it is recommended to use different IAM roles: `/ci/builder` and `/ci/publisher`.
16-
Below there are two terraform modules that have all necessary permissions to work with CodeArtifact:
17-
- [ci-builder](https://github.com/agilecustoms/terraform-aws-ci-builder)
18-
- [ci-publisher](https://github.com/agilecustoms/terraform-aws-ci-publisher)
19-
20-
And this is [example](https://github.com/agilecustoms/terraform-aws-ci-publisher?tab=readme-ov-file#how-to-create-a-role-with-this-policy)
21-
how to create AWS IAM role based of these policies with password-less trust policy
22-
23-
This action is a combination of few other actions mainly `actions/setup-java` and `aws-actions/configure-aws-credentials`,
24-
hence all parameters have prefix either `java-` (for java-specific settings) or `aws-` (for authorization in aws)
25-
26-
## Usage in build workflow
13+
Below is an example of how to use this action in the **build** workflow.
14+
For release/publish workflows use [agilecustoms/release](https://github.com/agilecustoms/release)
2715

2816
```yaml
2917
jobs:
@@ -45,15 +33,63 @@ jobs:
4533
aws-codeartifact-domain: mycompany
4634
java-version: 21 # default
4735

36+
# now you can run maven while pulling dependencies from AWS CodeArtifact
4837
- name: Maven build
4938
run: mvn verify --no-transfer-progress
5039
```
5140
41+
This action is designed for use in a **build** workflow when you need to access packages from CodeArtifact.
42+
In **release** workflow you need to bump a version in `pom.xml` file and add some git tags,
43+
so please check the [agilecustoms/release](https://github.com/agilecustoms/release) action —
44+
it represents a holistic release action (uses `setup-maven-codeartifact` under the hood)
45+
46+
For build and release workflows it is recommended to use different IAM roles: `/ci/builder` and `/ci/publisher`.
47+
Builder has read-only access to CodeArtifact, while publisher has write access.
48+
Below there are two terraform modules that have all necessary permissions to work with CodeArtifact:
49+
- [ci-builder](https://github.com/agilecustoms/terraform-aws-ci-builder)
50+
- [ci-publisher](https://github.com/agilecustoms/terraform-aws-ci-publisher)
51+
52+
And this is [example](https://github.com/agilecustoms/terraform-aws-ci-publisher?tab=readme-ov-file#how-to-create-a-role-with-this-policy)
53+
how to create an AWS IAM role based on these policies with a password-less trust policy,
54+
so you do not need to store `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in your repository secrets
55+
56+
Read more about software distribution in AWS in my [LinkedIn article](https://www.linkedin.com/pulse/software-distribution-aws-alexey-chekulaev-ubl0e)
57+
58+
## Inputs
59+
60+
This action is a combination of few other actions mainly `actions/setup-java` and `aws-actions/configure-aws-credentials`,
61+
hence all parameters have prefix either `java-` (for java-specific settings) or `aws-` (for authorization in aws)
62+
63+
| Name | Required | Default | Description |
64+
|-------------------------------|----------|-----------------------|------------------------------------------------------------------------------------|
65+
| `aws-account` | **Yes** | | AWS account number where the CodeArtifact domain is located |
66+
| `aws-region` | **Yes** | | AWS region where the CodeArtifact domain is located |
67+
| `aws-role` | **Yes** | `ci/builder` | IAM role to assume for CodeArtifact access |
68+
| `aws-codeartifact-domain` | **Yes** | | CodeArtifact domain name |
69+
| `aws-codeartifact-repository` | **Yes** | `maven` | CodeArtifact repository name |
70+
| `aws-login` | No | `true` | Whether to login to AWS. Set to `false` if you handle AWS login separately |
71+
| `java-version` | No | `21` | Java version to use. Default is latest LTS (21 as of June 2025) |
72+
| `java-distribution` | No | `temurin` | Java distribution. Temurin is recommended as it's pre-cached in ubuntu-latest |
73+
| `java-cache` | No | `maven` | Enable Maven dependency caching. Use empty string `""` to disable |
74+
| `settings-mirrors` | No | | Maven settings.xml mirrors section (XML format) |
75+
| `settings-pluginGroups` | No | | Maven settings.xml pluginGroups section (XML format) |
76+
| `settings-pluginRepositories` | No | Maven Central + repo1 | Additional plugin repositories in XML format to be placed in front of CodeArtifact |
77+
| `settings-profile-properties` | No | | Maven settings.xml profile properties section (XML format) |
78+
| `settings-proxies` | No | | Maven settings.xml proxies section (XML format) |
79+
| `settings-repositories` | No | Maven Central + repo1 | Additional Maven repositories in XML format to be placed before CodeArtifact |
80+
81+
Notes:
82+
1. for `aws-account` it is recommended to have a dedicated AWS account (not dev, not prod) to store artifacts (S3 binaries, CodeArtifact, Docker images)
83+
2. default settings for `settings-pluginRepositories` and `settings-repositories` are good for projects
84+
that take 95% of dependencies from Maven Central and left 5% from corporate CodeArtifact.
85+
Come companies opt in to store all dependencies in CodeArtifact with Maven Central as an _upstream_.
86+
In this configuration you would want to set `settings-pluginRepositories` and `settings-repositories` to empty string `""`
87+
5288
## settings.xml for local development
5389

54-
Under the hood, this action generates [settings.xml](./ci.settings.xml) file with CodeArtifact repository and credentials.
90+
Under the hood, this action generates a [settings.xml](./ci.settings.xml) file with CodeArtifact repository and credentials.
5591
Note:
56-
- maven central and its mirror are used as primary repositories for dependencies and plugins, your company CodeArtifact is in 3rd place
92+
- maven central and its mirror are used as primary and secondary repositories for dependencies and plugins, your company CodeArtifact is in 3rd place
5793
- your company repository id has format `{aws-codeartifact-domain}-{aws-codeartifact-repository}`
5894

5995
With this knowledge, you can place a local version of [settings.xml](./local.settings.xml) on developers' machines
@@ -69,3 +105,44 @@ For `ARTIFACT_STORE_TOKEN` you'd need to generate it (at most) once a day with c
69105
TOKEN=$(aws codeartifact get-authorization-token --domain mycompany --query authorizationToken --output text)
70106
export ARTIFACT_STORE_TOKEN=$TOKEN
71107
```
108+
109+
## Security
110+
111+
If you ever find yourself generating and passing a secret in any of the `settings-*` inputs, please mask it first:
112+
113+
```yaml
114+
jobs:
115+
Build:
116+
runs-on: ubuntu-latest
117+
permissions:
118+
id-token: write # to request JWT from GitHub OIDC provider
119+
contents: read # required for actions/checkout
120+
steps:
121+
- name: Checkout
122+
uses: actions/checkout@v4
123+
124+
- name: Proxy with a secret
125+
id: proxy
126+
run: |
127+
# generate a SECRET
128+
PROXY_CONFIG="<config><username>abc</username><password>$SECRET</password></config>"
129+
echo "::add-mask::$PROXY_CONFIG"
130+
echo "CONFIG=$PROXY_CONFIG" >> $GITHUB_OUTPUT
131+
132+
- name: Setup Java
133+
uses: agilecustoms/setup-maven-codeartifact@v1
134+
with:
135+
aws-account: ${{ vars.AWS_ACCOUNT_DIST }}
136+
aws-region: us-east-1
137+
aws-codeartifact-domain: mycompany
138+
settings-proxies: ${{ steps.proxy.outputs.CONFIG }}
139+
```
140+
141+
## License
142+
143+
This project is released under the [MIT License](./LICENSE)
144+
145+
## Acknowledgements
146+
147+
- https://github.com/s4u/maven-settings-action — first action I tried, but it doesn't support pluginRepositories
148+
- https://github.com/whelk-io/maven-settings-xml-action — used this during 2024, then wrote my own action

0 commit comments

Comments
 (0)