Carrega paràmetres d'AWS SSM com a variables d'entorn a GitHub Actions

Com injecto paràmetres d'AWS SSM com a variables d'entorn a GitHub Actions? Inicia la sessió del job a AWS amb OIDC de GitHub i executa l'Envilder Action després d'aquest pas amb la ruta del teu fitxer de mapa: llegeix cada paràmetre d'AWS SSM Parameter Store llistat a envilder.json, registra cada valor perquè s'emmascari als logs i els defineix com a variables d'entorn per a tots els passos següents del job. No cal desar cap clau d'accés d'AWS a GitHub, i Envilder no escriu cap fitxer .env en aquest mode.

Com funciona

  1. El job demana un token OIDC a GitHub. aws-actions/configure-aws-credentials l'intercanvia per credencials de curta durada d'un rol IAM que només confia en el teu repositori i branca. No es desa cap clau d'accés d'AWS a GitHub.
  2. L'Envilder Action llegeix envilder.json i crida ssm:GetParameter, amb desxifrat, un cop per variable, amb aquestes credencials. No inicia sessió a AWS per si mateixa.
  3. Cada valor es registra per a l'emmascarament de logs de GitHub i després s'exporta a l'entorn de tots els passos següents del mateix job.

Requisits previs

  • Paràmetres a SSM Parameter Store, en un sol compte i regió. Els paràmetres SecureString funcionen: l'acció els llegeix amb desxifrat.
  • Un proveïdor d'identitat OpenID Connect d'IAM per a token.actions.githubusercontent.com en aquest compte, amb audience sts.amazonaws.com. Es crea un sol cop per compte.

Un envilder.json al repositori, amb una entrada per variable, cadascuna apuntant al nom d’un paràmetre:

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

Per crear els paràmetres i aquest fitxer des de zero, segueix la guia SSM a .env.

Crea el rol IAM

La política de confiança deixa que GitHub assumeixi el rol per a l'audience sts.amazonaws.com i per a un sol subject: la branca main d'aquest repositori. Substitueix l'ID del compte, l'organització i el repositori:

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"
      }
    }
  }]
}

Un job que apunta a un entorn de GitHub, una etiqueta o una pull request envia un sub diferent, igual que els repositoris que usen subject claims immutables. La referència de GitHub Action llista cada forma. Referència de GitHub Action: entorns i subjects OIDC

Adjunta una política de permisos que permeti només el que crida Envilder: ssm:GetParameter, un cop per variable, sobre els paràmetres d'aquesta aplicació. Mai llista, escriu ni elimina paràmetres.

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/*"
  }]
}

Els paràmetres xifrats amb la clau per defecte aws/ssm no necessiten res més. Afegeix kms:Decrypt sobre la clau només si usen una clau KMS gestionada pel client. L'ARN ha de dur la regió dels paràmetres.

Afegeix Envilder al workflow

Inicia sessió primer amb configure-aws-credentials i després executa l'acció. El job necessita id-token: write per demanar el token OIDC. Tots els passos següents llegeixen DB_PASSWORD i API_TOKEN com a variables d'entorn normals:

.github/workflows/deploy.ymlyaml
name: Deploy

on:
  push:
    branches: [main]

permissions:
  id-token: write   # Permet que el job demani un token OIDC
  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 i API_TOKEN estan definides en aquest pas

El log del pas llista cada variable amb el valor emmascarat i acaba amb aquesta línia:

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

provider: aws s'escriu expressament. Sense això, el proveïdor surt de $config.provider al fitxer de mapa i per defecte és aws. L'input preval sobre el fitxer de mapa, així que aquest job llegeix SSM encara que el fitxer nomeni un altre proveïdor.

La regió ve d'aws-region al pas de credencials, que exporta AWS_REGION i AWS_DEFAULT_REGION. Envilder llegeix primer AWS_REGION, després AWS_DEFAULT_REGION, i acaba a us-east-1 si no en troba cap. Un paràmetre desat en una altra regió es reporta com a no trobat.

Els valors arriben als passos següents a través del fitxer GITHUB_ENV del runner, així que tots els passos següents d'aquest job els poden llegir, incloses les accions de tercers. Els altres jobs no reben res: executa l'acció a cada job que necessiti els valors.

Aquest workflow només defineix map-file i provider. Els altres inputs i la sortida estan descrits a la referència de GitHub Action.

Quan només un pas necessita els secrets

El mode per defecte comparteix els valors amb la resta del job. Dos inputs ho redueixen.

Executa una sola ordre

Amb command, l'acció l'executa amb bash, i els secrets només existeixen per a aquesta ordre i els processos que inicia. Els passos següents no els veuen, i el pas acaba amb el codi de sortida de l'ordre. Si falta un paràmetre o és buit, l'ordre no s'inicia.

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

El mateix amb la CLI en un pas run necessita Node.js 22.12 o superior, així que primer configura’l:

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

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

La CLI resol el mateix fitxer de mapa i surt amb 125, sense iniciar l'ordre, quan no es pot llegir un paràmetre. Deixa el seu stderr al log del pas: porta els registres de màscares. L'Action no necessita cap pas previ i executa la versió empaquetada amb la seva etiqueta, mentre que npx envilder baixa l'última CLI publicada tret que n'ancoris una amb npx envilder@<version>.

Escriu un fitxer per a una eina que el necessita

Algunes eines llegeixen un fitxer en lloc de l'entorn, per exemple docker compose --env-file. Usa env-file i posa'l sota runner.temp, fora de l'espai de treball. La sortida env-file-path retorna la ruta que has passat:

- 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
⚠️
Aquest mode escriu els valors en text pla al runner: no pugis mai aquest fitxer com a artifact ni el posis a la memòria cau. Un paràmetre que falta només és un avís aquí, així que comprova que el resum compti totes les variables. env-file i command no es poden combinar.

Referència de GitHub Action: triar un mode

Què s’emmascara als logs

GitHub amaga un valor al log només després que alguna cosa el registri. Això és el que fan l'acció i la CLI:

  • L'Action registra cada valor que llegeix amb una ordre de workflow ::add-mask::, en els tres modes. En els modes per defecte i command espera que els registres s'hagin escrit abans d'exportar els valors o iniciar l'ordre, i s'atura sense exportar res si un registre falla.
  • Envilder imprimeix cada variable amb el valor amb asteriscs: un valor de més de 10 caràcters conserva els tres últims, un de més curt va tot amb asteriscs. Les rutes de paràmetre també conserven els tres últims caràcters.
  • L'emmascarament compara el text exacte. Una còpia transformada d'un valor, per exemple codificada en base64, no es reconeix i s'imprimeix en clar. L'emmascarament només afecta el log: no protegeix un fitxer, un artifact ni una memòria cau.
  • Els errors que vénen d'AWS s'imprimeixen tal com els retorna AWS i poden contenir l'ARN complet del paràmetre.

Si executes la CLI tu mateix en lloc de l'Action, envilder exec registra les màscares quan GITHUB_ACTIONS és true. Envilder sense subordre, que escriu un fitxer .env, no registra cap màscara en un workflow i imprimeix els tres últims caràcters dels valors llargs. A CI, prefereix l'Action o envilder exec.

Errors habituals

MissatgeSolució
Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentityEl mostra configure-aws-credentials, abans que s'executi Envilder. El sub o l'aud de la política de confiança no coincideix amb el token, o falta el proveïdor d'identitat en aquest compte. El sub canvia amb la branca, etiqueta, pull request o entorn de l'execució.
El pas de credencials falla en obtenir un ID tokenAl job li falta id-token: write, així que GitHub no li dona cap token OIDC. Afegeix-lo a nivell de workflow o de job, juntament amb contents: read. El text exacte depèn de la versió de l'acció, així que busca un missatge sobre l'ID token.
Input required and not supplied: aws-regionconfigure-aws-credentials sempre requereix aws-region. Defineix-la en aquest pas: també fixa la regió que usa Envilder.
Could not load credentials from any providersEs mostra sota WHY? al log d'Envilder. Cap credencial ha arribat a Envilder: falta el pas de credencials, va després del pas d'Envilder o és en un altre job. Les credencials no passen d'un job a un altre.
is not authorized to perform: ssm:GetParameter on resourceEl rol s'ha assumit però la seva política no cobreix aquest paràmetre. Compara l'ARN de Resource, regió inclosa, amb el paràmetre del missatge. Un missatge semblant sobre kms:Decrypt vol dir que al rol o a la política de la clau li falta aquest permís.
not foundEl motiu que es mostra sota WHY? quan GetParameter no troba el paràmetre. Revisa el nom i compara la regió de la línia d'identitat amb la regió del paràmetre. El pas falla en els modes per defecte i command, i només avisa amb env-file.
Use either env-file or command, not both.Defineix només un dels dos 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.Una variable del mapa és un dels noms que el runner no deixa definir a GITHUB_ENV. Canvia-li el nom, o usa command o env-file.

Hi ha més casos, com credencials caducades i Azure, a la referència de GitHub Action.

Comparat amb altres maneres de llegir SSM en un workflow

L'alternativa simple és un pas run amb l'AWS CLI, que ve preinstal·lada als runners Ubuntu allotjats per GitHub, després del pas de credencials. Per a un o dos paràmetres funciona:

- run: |
    value=$(aws ssm get-parameter --name /my-app/prod/db-password \
      --with-decryption --query Parameter.Value --output text)
    # Emmascara cada línia del valor abans que res la pugui imprimir
    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"
  • Cada paràmetre necessita la seva ordre, i els noms viuen al workflow en lloc d'un fitxer de mapa que els desenvolupadors també usen en local amb la CLI.
  • Has d'emmascarar el valor abans d'escriure'l, i un valor amb salt de línia no pot usar la forma NAME=value: GITHUB_ENV necessita la seva sintaxi de delimitador multilínia.
  • --with-decryption és fàcil d'oblidar: sense això un SecureString torna com a text xifrat.

Per a un o dos paràmetres l'script és més curt i no necessita cap acció addicional. Envilder comença a compensar amb diverses variables, un fitxer de mapa compartit amb el desenvolupament local i un pas que falla si falta qualsevol paràmetre.

Altres accions del GitHub Marketplace també llegeixen paràmetres SSM. Abans d'escollir-ne una, comprova què emmascara, quines accions IAM necessita (GetParameter o GetParametersByPath), si un paràmetre que falta fa fallar el pas, i com es versiona i es manté. Per a Envilder les respostes són cada valor, només ssm:GetParameter, i sí en els modes per defecte i command. Aquesta guia no compara altres accions una per una.