The goal of the utility is to make it as easy as possible, to access AWS from a Gitlab CI/CD pipeline using the gitlab pipeline id token. You only need to specify the AWS account number and add the Gitlab ID token: it will use the pipeline id and the gitlab project path slug to determine the IAM role- and session name.
For instance, if your project path is "binxio/aws-credential-helper-demo", the IAM role it wants to assume is "gitlab-binxio-aws-credential-helper-demo". The ID token is expected to be in the environment variable GITLAB_AWS_IDENTITY_TOKEN.
There are three ways to use this utility:
gitlab-aws-credential-helper process
gitlab-aws-credential-helper aws-profile [flags]
gitlab-aws-credential-helper env [flags]
- process - implements the AWS external credential process interface
- aws-profile - updates the credentials in shared credentials in ~/.aws/credentials
- env - prints the environment variables containing the AWS credentials
The following flags can be applied to override the sensible defaults:
-A, --aws-account string required - AWS account id to assume to role in (default $GITLAB_AWS_ACCOUNT_ID)
-r, --role-name string required - Name of the role to assume (default gitlab-$CI_PROJECT_PATH_SLUG)
-n, --role-session-name string required - the role session name to use (default <role name>-$CI_PIPELINE_ID)
-j, --web-identity-token-name string required - of the environment variable with the JWT id token (default "GITLAB_AWS_IDENTITY_TOKEN")
-d, --duration-seconds int of the session (default 3600)
The following environment variables effect the credential helper:
| Name | description |
|---|---|
| GITLAB_AWS_ACCOUNT_ID | The AWS account id in which the IAM role is to be assumed |
| GITLAB_AWS_PROFILE | The name of the profile aws-profile writes the credentials to, default "default" |
| GITLAB_AWS_IDENTITY_TOKEN_NAME | The name of the environment variable with the id token, default GITLAB_AWS_IDENTITY_TOKEN |
| GITLAB_AWS_DURATION_ SECONDS | The duration of the sts session token, default 3600 |
| CI_PIPELINE_ID | predefined Gitlab variable, containing the pipeline id, used as suffix for the session name |
| CI_PROJECT_PATH_SLUG | predefined Gitlab variable, used to create the role name by prefixing with gitlab- and truncating to 64 characters |
Returns the credentials on stdout as specified by the credential_process interface. The process is called by the AWS library whenever credentials are required for access.
aws configure set credential_process "gitlab-aws-credential-helper process"
Stores the credentials in the AWS shared credentials file under the profile name "default".
The profile name defaults to "default" but can be overridden through the environment variable GITLAB_AWS_PROFILE or the command line option --name/-p.
In addition to the global flags, the following flags can be applied to override the sensible defaults:
-p, --name string the name of AWS profile (default "default")
Returns the credentials as the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN. When you pass a command to execute on the command line, the command will be executed without writing the credentials.
The following gitlab-ci.yml snippets shows the usage of the env command:
In addition to the global flags, the following flags can be applied to override the sensible defaults:
-f, --filename string the name of the dotenv file (default stdout)
-e, --export prefix the environment variables with "export " (default false)
This section contains an example for credential process, aws profile and env usage of the credential helper.
The following gitlab-ci.yml snippets shows the usage of the process command:
# extract the binary as artifact into the workspace
get-credential-helper:
stage: .pre
image:
name: ghcr.io/binxio/gitlab-aws-credential-helper:0.0.0-6-gc168a6d
entrypoint: [""]
script:
- cp /usr/local/bin/gitlab-aws-credential-helper .
artifacts:
expire_in: 1 hour
paths:
- gitlab-aws-credential-helper
process-demo:
stage: build
image:
name: public.ecr.aws/aws-cli/aws-cli:2.13.17
entrypoint: [""]
id_tokens:
GITLAB_AWS_IDENTITY_TOKEN:
aud: https://gitlab.com
script:
# use the credential helper
- aws configure set credential_process "$PWD/gitlab-aws-credential-helper process"
- aws sts get-caller-identity
needs:
- get-credential-helperThe following gitlab-ci.yml snippets shows the usage of the aws-profile command:
# extract the binary as artifact into the workspace
get-credential-helper:
stage: .pre
image:
name: ghcr.io/binxio/gitlab-aws-credential-helper:0.0.0-6-gc168a6d
entrypoint: [""]
script:
- cp /usr/local/bin/gitlab-aws-credential-helper .
artifacts:
expire_in: 1 hour
paths:
- gitlab-aws-credential-helper
aws-profile-demo:
stage: build
image:
name: public.ecr.aws/aws-cli/aws-cli:2.13.17
entrypoint: [""]
id_tokens:
GITLAB_AWS_IDENTITY_TOKEN:
aud: https://gitlab.com
script:
# use the credential helper
- ./gitlab-aws-credential-helper aws-profile
- aws sts get-caller-identity
needs:
- get-credential-helperThe following gitlab-ci.yml snippets shows the usage of the dotenv command:
variables:
GITLAB_AWS_ACCOUNT_ID: 123456789012
get-aws-credentials:
stage: .pre
id_tokens:
GITLAB_AWS_IDENTITY_TOKEN:
aud: https://gitlab.com
image:
name: ghcr.io/binxio/gitlab-aws-credential-helper:0.1.0
entrypoint: [""]
script:
- gitlab-aws-credential-helper env > .gitlab-as-credentials.env
- gitlab-aws-credential-helper env -- aws sts get-caller-identity
artifacts:
expire_in: 10 min
reports:
env: .gitlab-aws-credentials.env
# Note that the env file with the credentials will be available for download from the
# pipeline artifacts by all roles associated with the project, including guest (!).
# See https://docs.gitlab.com/ee/user/permissions.html#gitlab-cicd-permissions
env:
stage: build
image:
name: public.ecr.aws/aws-cli/aws-cli:2.13.17
entrypoint: [""]
script:
- aws sts get-caller-identity
needs:
- get-aws-credentialsNote that the dotenv file with the credentials will be available for download from the pipeline artifacts by all roles associated with the project, including guest (!).