View a markdown version of this page

Use AWS Secrets Manager secrets in GitHub jobs - AWS Secrets Manager

Use AWS Secrets Manager secrets in GitHub jobs

To use a secret in a GitHub job, you can use a GitHub action to retrieve secrets from AWS Secrets Manager and add them as masked Environment variables in your GitHub workflow. The action's source code and release notes are in the aws-actions/aws-secretsmanager-get-secrets repository on the GitHub website. For more information about GitHub Actions, see Understanding GitHub Actions in the GitHub Docs.

When you add a secret to your GitHub environment, it is available to all other steps in your GitHub job. Follow the guidance in Security hardening for GitHub Actions to help prevent secrets in your environment from being misused.

You can set the entire string in the secret value as the environment variable value, or if the string is JSON, you can parse the JSON to set individual environment variables for each JSON key-value pair. If the secret value is a binary, the action converts it to a string.

To view the environment variables created from your secrets, turn on debug logging. For more information, see Enabling debug logging in the GitHub Docs.

To use the environment variables created from your secrets, see Environment variables in the GitHub Docs.

Prerequisites

To use this action, you first need to configure AWS credentials and set the AWS Region in your GitHub environment by using the configure-aws-credentials step. Follow the instructions in Configure AWS Credentials Action For GitHub Actions to Assume role directly using GitHub OIDC provider. This allows you to use short-lived credentials and avoid storing additional access keys outside of Secrets Manager.

The IAM role the action assumes must have the following permissions:

  • GetSecretValue on the secrets you want to retrieve.

  • ListSecrets on all secrets.

  • (Optional) Decrypt on the KMS key if the secrets are encrypted with a customer managed key.

For more information, see Authentication and access control for AWS Secrets Manager.

Usage

To use the action, add a step to your workflow that uses the following syntax.

- name: Step name uses: aws-actions/aws-secretsmanager-get-secrets@v4 with: secret-ids: | secretId1 ENV_VAR_NAME, secretId2 name-transformation: (Optional) uppercase|lowercase|none parse-json-secrets: (Optional) true|false http-proxy: (Optional) proxy URL no-proxy: (Optional) comma-separated hosts
Parameters
secret-ids

Secret ARNS, names, and name prefixes.

To set the environment variable name, enter it before the secret ID, followed by a comma. For example ENV_VAR_1, secretId creates an environment variable named ENV_VAR_1 from the secret secretId. The environment variable name can consist of uppercase letters, numbers, and underscores.

To use a prefix, enter at least three characters followed by an asterisk. For example dev* matches all secrets with a name beginning in dev. The maximum number of matching secrets that can be retrieved is 100. If you set the variable name, and the prefix matches multiple secrets, then the action fails.

name-transformation

By default, the step creates each environment variable name from the secret name, transformed to include only uppercase letters, numbers, and underscores, and so that it doesn't begin with a number. For the letters in the name, you can configure the step to use lowercase letters with lowercase or to not change the case of the letters with none. The default value is uppercase.

parse-json-secrets

(Optional) By default, the action sets the environment variable value to the entire JSON string in the secret value. Set parse-json-secrets to true to create environment variables for each key-value pair in the JSON.

Note that if the JSON uses case-sensitive keys such as "name" and "Name", the action will have duplicate name conflicts. In this case, set parse-json-secrets to false and parse the JSON secret value separately.

http-proxy

(Optional) The URL of an HTTP or HTTPS proxy for the Secrets Manager API calls, for example http://proxy.example.com:3128. If you don't set http-proxy, the action uses the https_proxy or HTTPS_PROXY environment variable. For more information about proxy settings, see Use an HTTP proxy.

no-proxy

(Optional) A comma-separated list of hosts that the action connects to without the proxy, for example .amazonaws.com. Use * for all hosts. If you don't set no-proxy, the action uses the no_proxy or NO_PROXY environment variable, including when you set the proxy with http-proxy.

Use an HTTP proxy

To send the Secrets Manager API calls through a proxy, set the http-proxy parameter to the proxy URL, or set the https_proxy or HTTPS_PROXY environment variable. The action supports only http:// and https:// proxy URLs. If the URL doesn't include a scheme, the action uses http://.

If you configure your self-hosted runners to use a proxy, the runner passes the proxy environment variables to every step, so the action uses that proxy. To connect directly instead, set no-proxy: "*".

Entries in no-proxy aren't case sensitive. An entry can be a host name, which also matches its subdomains, such as amazonaws.com. It can also be a domain suffix that starts with . or *., such as .amazonaws.com, or * for all hosts. Any entry can end with a port, for example .amazonaws.com:443.

If the proxy requires credentials, include them in the URL, for example http://USERNAME:PASSWORD@proxy.example.com:3128. Percent-encode special characters in the user name and password, for example @ as %40 and % as %25. With an http:// proxy, your credentials go to the proxy unencrypted on every connection, so use an https:// proxy when the proxy requires credentials.

Important

Store a proxy URL that contains credentials in a GitHub secret, and set http-proxy or the proxy environment variable from that secret. If you write credentials in the workflow file, anyone who can read the repository can read them.

The action doesn't fall back to a direct connection. If the proxy URL is invalid, or the proxy can't be reached, times out, or refuses the request with HTTP 403 or 407, the step fails.

The following example gets a secret through the proxy whose URL is stored in the GitHub secret PROXY_URL, and excludes hosts that end in .internal.example.com from the proxy.

- name: Get secrets through a proxy uses: aws-actions/aws-secretsmanager-get-secrets@v4 with: secret-ids: exampleSecretName http-proxy: ${{ secrets.PROXY_URL }} no-proxy: .internal.example.com

To use a proxy that's set in the runner's environment, leave out the proxy parameters and set the environment variables, as in the following example.

HTTPS_PROXY=http://proxy.example.com:3128 NO_PROXY=.internal.example.com

Environment variable naming

The environment variables created by the action are named the same as the secrets that they come from. Environment variables have stricter naming requirements than secrets, so the action transforms secret names to meet those requirements. For example, the action transforms lowercase letters to uppercase letters. If you parse the JSON of the secret, then the environment variable name includes both the secret name and the JSON key name, for example MYSECRET_KEYNAME. You can configure the action to not transform lowercase letters.

If two environment variables would end up with the same name, the action fails. In this case, you must specify the names you want to use for the environment variables as aliases.

Examples of when the names might conflict:

  • A secret named "MySecret" and a secret named "mysecret" would both become environment variables named "MYSECRET".

  • A secret named "Secret_keyname" and a JSON-parsed secret named "Secret" with a key named "keyname" would both become environment variables named "SECRET_KEYNAME".

You can set the environment variable name by specifying an alias, as shown in the following example, which creates a variable named ENV_VAR_NAME.

secret-ids: | ENV_VAR_NAME, secretId2
Blank aliases
  • If you set parse-json-secrets: true and enter a blank alias, followed by a comma and then the secret ID, the action names the environment variable the same as the parsed JSON keys. The variable names do not include the secret name.

    If the secret doesn't contain valid JSON, then the action creates one environment variable and names it the same as the secret name.

  • If you set parse-json-secrets: false and enter a blank alias, followed by a comma and the secret ID, the action names the environment variables as if you did not specify an alias.

The following example shows a blank alias.

,secret2

Examples

Example 1 Get secrets by name and by ARN

The following example creates environment variables for secrets identified by name and by ARN.

- name: Get secrets by name and by ARN uses: aws-actions/aws-secretsmanager-get-secrets@v4 with: secret-ids: | exampleSecretName arn:aws:secretsmanager:us-east-2:123456789012:secret:test1-a1b2c3 0/test/secret /prod/example/secret SECRET_ALIAS_1,test/secret SECRET_ALIAS_2,arn:aws:secretsmanager:us-east-2:123456789012:secret:test2-a1b2c3 ,secret2

Environment variables created:

EXAMPLESECRETNAME: secretValue1 TEST1: secretValue2 _0_TEST_SECRET: secretValue3 _PROD_EXAMPLE_SECRET: secretValue4 SECRET_ALIAS_1: secretValue5 SECRET_ALIAS_2: secretValue6 SECRET2: secretValue7
Example 2 Get all secrets that begin with a prefix

The following example creates environment variables for all secrets with names that begin with beta.

- name: Get Secret Names by Prefix uses: aws-actions/aws-secretsmanager-get-secrets@v4 with: secret-ids: | beta* # Retrieves all secrets that start with 'beta'

Environment variables created:

BETASECRETNAME: secretValue1 BETATEST: secretValue2 BETA_NEWSECRET: secretValue3
Example 3 Parse JSON in secret

The following example creates environment variables by parsing the JSON in the secret.

- name: Get Secrets by Name and by ARN uses: aws-actions/aws-secretsmanager-get-secrets@v4 with: secret-ids: | test/secret ,secret2 parse-json-secrets: true

The secret test/secret has the following secret value.

{ "api_user": "user", "api_key": "key", "config": { "active": "true" } }

The secret secret2 has the following secret value.

{ "myusername": "alejandro_rosalez", "mypassword": "EXAMPLE_PASSWORD" }

Environment variables created:

TEST_SECRET_API_USER: "user" TEST_SECRET_API_KEY: "key" TEST_SECRET_CONFIG_ACTIVE: "true" MYUSERNAME: "alejandro_rosalez" MYPASSWORD: "EXAMPLE_PASSWORD"
Example 4 Use lowercase letters for environment variable names

The following example creates an environment variable with a lowercase name.

- name: Get secrets uses: aws-actions/aws-secretsmanager-get-secrets@v4 with: secret-ids: exampleSecretName name-transformation: lowercase

Environment variable created:

examplesecretname: secretValue