Load AWS SSM parameters as environment variables in GitHub Actions

How do I inject AWS SSM parameters as environment variables in GitHub Actions? Sign the job in to AWS with GitHub OIDC, then run the Envilder Action after that step with the path of your map file: it reads each AWS SSM Parameter Store parameter listed in envilder.json, registers every value for log masking and sets them as environment variables for every later step of the job. No AWS access key is stored in GitHub, and Envilder writes no .env file in this mode.

How it works

  1. The job asks GitHub for an OIDC token. aws-actions/configure-aws-credentials exchanges it for short-lived credentials of an IAM role that trusts only your repository and branch. No AWS access key is stored in GitHub.
  2. The Envilder Action reads envilder.json and calls ssm:GetParameter, with decryption, once per variable, using those credentials. It does not sign in to AWS itself.
  3. Each value is registered with GitHub log masking and then exported to the environment of every later step of the same job.

Prerequisites

  • Parameters in SSM Parameter Store, in one account and region. SecureString parameters work: the action reads them with decryption.
  • An IAM OpenID Connect identity provider for token.actions.githubusercontent.com in that account, with audience sts.amazonaws.com. It is created once per account.

An envilder.json committed to the repository, with one entry per variable, each pointing to a parameter name:

envilder.jsonjson
{
  "DB_PASSWORD": "/my-app/prod/db-password",
  "API_TOKEN": "/my-app/prod/api-token"
}

To create the parameters and this file from scratch, follow the SSM to .env guide.

Create the IAM role

The trust policy lets GitHub assume the role for the audience sts.amazonaws.com and for one subject only: the main branch of this repository. Replace the account ID, the organization and the repository:

trust-policy.jsonjson
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
        "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:ref:refs/heads/main"
      }
    }
  }]
}

A job that targets a GitHub environment, a tag or a pull request sends a different sub, and so do repositories that use immutable subject claims. The GitHub Action reference lists each form. GitHub Action reference: environments and OIDC subjects

Attach a permissions policy that allows only what Envilder calls: ssm:GetParameter, once per variable, on the parameters of this application. It never lists, writes or deletes parameters.

envilder-read.jsonjson
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "ssm:GetParameter",
    "Resource": "arn:aws:ssm:eu-west-1:123456789012:parameter/my-app/prod/*"
  }]
}

Parameters encrypted with the default aws/ssm key need nothing more. Add kms:Decrypt on the key only if they use a customer managed KMS key. The ARN must carry the region of the parameters.

Add Envilder to the workflow

Sign in with configure-aws-credentials first, then run the action. The job needs id-token: write to request the OIDC token. Every later step reads DB_PASSWORD and API_TOKEN as ordinary environment variables:

.github/workflows/deploy.ymlyaml
name: Deploy

on:
  push:
    branches: [main]

permissions:
  id-token: write   # Lets the job request an OIDC token
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-envilder
          aws-region: eu-west-1

      - uses: macalbert/envilder/github-action@v0
        with:
          map-file: envilder.json
          provider: aws

      - run: ./deploy.sh   # DB_PASSWORD and API_TOKEN are set in this step

The step log lists each variable with a masked value and ends with this line:

envilder: 2 secrets exported to the job environment (DB_PASSWORD, API_TOKEN)

provider: aws is written out on purpose. Without it, the provider comes from $config.provider in the map file and defaults to aws. The input overrides the map file, so this job reads SSM even if the file also names another provider.

The region comes from aws-region on the credentials step, which exports AWS_REGION and AWS_DEFAULT_REGION. Envilder reads AWS_REGION first, then AWS_DEFAULT_REGION, and ends at us-east-1 when it finds none. A parameter stored in another region is reported as not found.

The values reach later steps through the GITHUB_ENV file of the runner, so every later step of this job can read them, including third-party actions. Other jobs get nothing: run the action in each job that needs the values.

This workflow sets only map-file and provider. The other inputs and the output are described in the GitHub Action reference.

When only one step needs the secrets

The default shares the values with the rest of the job. Two inputs narrow that.

Run one command

With command, the action runs it with bash, and the secrets exist only for that command and the processes it starts. Later steps do not see them, and the step ends with the exit code of the command. If a parameter is missing or empty, the command does not start.

- uses: macalbert/envilder/github-action@v0
  with:
    map-file: envilder.json
    provider: aws
    command: ./deploy.sh --prod

The same with the CLI in a run step needs Node.js 22.12 or later, so set it up first:

- uses: actions/setup-node@v7
  with:
    node-version: 22.x

- run: npx envilder exec --map=envilder.json --provider=aws -- ./deploy.sh --prod

The CLI resolves the same map file and exits with 125, without starting your command, when a parameter cannot be read. Keep its stderr in the step log: it carries the mask registrations. The Action needs no setup step and runs the version bundled with its tag, while npx envilder downloads the latest published CLI unless you pin one with npx envilder@<version>.

Write a file for a tool that needs one

Some tools read a file instead of the environment, for example docker compose --env-file. Use env-file and put it under runner.temp, outside the workspace. The env-file-path output returns the path you passed:

- id: envilder
  uses: macalbert/envilder/github-action@v0
  with:
    map-file: envilder.json
    provider: aws
    env-file: ${{ runner.temp }}/app.env

- run: docker compose --env-file "${{ steps.envilder.outputs.env-file-path }}" up -d
⚠️
This mode writes the values in plain text on the runner: never upload that file as an artifact or cache it. A missing parameter is only a warning here, so check that the summary counts every variable. env-file and command cannot be combined.

GitHub Action reference: choosing a mode

What is masked in the logs

GitHub hides a value in the log only after something registers it. This is what the action and the CLI do:

  • The Action registers every value it reads with an ::add-mask:: workflow command, in all three modes. In the default and command modes it waits until the registrations are written before it exports the values or starts your command, and it stops without exporting anything if one registration fails.
  • Envilder prints each variable with a starred value: a value longer than 10 characters keeps its last three characters, a shorter one is fully starred. Parameter paths keep their last three characters too.
  • Masking compares the exact text. A transformed copy of a value, for example base64 encoded, is not recognized and is printed in clear. Masking only affects the log: it does not protect a file, an artifact or a cache.
  • Errors that come from AWS are printed as AWS returned them and can contain the full parameter ARN.

If you run the CLI yourself instead of the Action, envilder exec registers the masks when GITHUB_ACTIONS is true. Plain envilder, which writes a .env file, registers no mask in a workflow and prints the last three characters of long values. In CI, prefer the Action or envilder exec.

Common errors

MessageFix
Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentityPrinted by configure-aws-credentials, before Envilder runs. The sub or aud in the trust policy does not match the token, or the identity provider is missing in this account. The sub changes with the branch, tag, pull request or environment of the run.
The credentials step fails while getting an ID tokenThe job lacks id-token: write, so GitHub gives it no OIDC token. Add it at the workflow or job level, together with contents: read. The exact wording depends on the version of the action, so look for a message about the ID token.
Input required and not supplied: aws-regionconfigure-aws-credentials always requires aws-region. Set it on that step: it also sets the region Envilder uses.
Could not load credentials from any providersShown under WHY? in the Envilder log. No credentials reached Envilder: the credentials step is missing, comes after the Envilder step or is in another job. Credentials do not carry over between jobs.
is not authorized to perform: ssm:GetParameter on resourceThe role was assumed but its policy does not cover that parameter. Compare the Resource ARN, region included, with the parameter in the message. A similar message about kms:Decrypt means the role or the key policy lacks that permission.
not foundThe reason shown under WHY? when GetParameter finds no such parameter. Check the name, and compare the region on the identity line with the region of the parameter. The step fails in the default and command modes, and only warns with env-file.
Use either env-file or command, not both.Set only one of the two inputs.
NODE_OPTIONS cannot be exported to the job environment: GitHub Actions does not let GITHUB_ENV set NODE_OPTIONS or its default GITHUB_* and RUNNER_* variables. Use the command or env-file input instead.A mapped variable is one of the names the runner does not let GITHUB_ENV set. Rename the variable, or use command or env-file.

More cases, including expired credentials and Azure, are in the GitHub Action reference.

Compared with other ways to read SSM in a workflow

The plain alternative is a run step with the AWS CLI, which is preinstalled on GitHub-hosted Ubuntu runners, after the credentials step. For one or two parameters it works:

- run: |
    value=$(aws ssm get-parameter --name /my-app/prod/db-password \
      --with-decryption --query Parameter.Value --output text)
    # Mask every line of the value before anything can print it
    while IFS= read -r line; do
      line="${line//%/%25}"
      line="${line//$'\r'/%0D}"
      [ -n "$line" ] && echo "::add-mask::$line"
    done <<< "$value"
    delim="EOF_$(openssl rand -hex 8)"
    { echo "DB_PASSWORD<<$delim"; echo "$value"; echo "$delim"; } >> "$GITHUB_ENV"
  • Each parameter needs its own command, and the names live in the workflow instead of in a map file that developers also use locally with the CLI.
  • You must mask the value before you write it, and a value with a newline cannot use the NAME=value form: GITHUB_ENV needs its multiline delimiter syntax.
  • --with-decryption is easy to forget: without it a SecureString comes back as ciphertext.

For one or two parameters the script is shorter and needs no extra action. Envilder starts to pay off with several variables, a map file shared with local development, and a step that fails when any parameter is missing.

Other actions on the GitHub Marketplace also read SSM parameters. Before choosing one, check what it masks, which IAM actions it needs (GetParameter or GetParametersByPath), whether a missing parameter fails the step, and how it is versioned and maintained. For Envilder the answers are every value, ssm:GetParameter only, and yes in the default and command modes. This guide does not compare other actions one by one.