Carga parámetros de AWS SSM como variables de entorno en GitHub Actions
¿Cómo inyecto parámetros de AWS SSM como variables de entorno en GitHub Actions? Inicia la sesión del job en AWS con OIDC de GitHub y ejecuta la Envilder Action después de ese paso con la ruta de tu archivo de mapa: lee cada parámetro de AWS SSM Parameter Store listado en envilder.json, registra cada valor para que se enmascare en los logs y los define como variables de entorno para todos los pasos siguientes del job. No hace falta guardar ninguna clave de acceso de AWS en GitHub, y Envilder no escribe ningún archivo .env en este modo.
Cómo funciona
- El job pide un token OIDC a GitHub. aws-actions/configure-aws-credentials lo cambia por credenciales de corta duración de un rol IAM que solo confía en tu repositorio y rama. No se guarda ninguna clave de acceso de AWS en GitHub.
- La Envilder Action lee envilder.json y llama a ssm:GetParameter, con descifrado, una vez por variable, con esas credenciales. No inicia sesión en AWS por sí misma.
- Cada valor se registra para el enmascarado de logs de GitHub y después se exporta al entorno de todos los pasos siguientes del mismo job.
Requisitos previos
- Parámetros en SSM Parameter Store, en una sola cuenta y región. Los parámetros SecureString funcionan: la acción los lee con descifrado.
- Un proveedor de identidad OpenID Connect de IAM para token.actions.githubusercontent.com en esa cuenta, con audience sts.amazonaws.com. Se crea una sola vez por cuenta.
Un envilder.json en el repositorio, con una entrada por variable, cada una apuntando al nombre de un parámetro:
{
"DB_PASSWORD": "/my-app/prod/db-password",
"API_TOKEN": "/my-app/prod/api-token"
}Para crear los parámetros y este archivo desde cero, sigue la guía SSM a .env.
Crea el rol IAM
La política de confianza deja que GitHub asuma el rol para la audience sts.amazonaws.com y para un solo subject: la rama main de este repositorio. Sustituye el ID de la cuenta, la organización y el repositorio:
{
"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 entorno de GitHub, una etiqueta o una pull request envía un sub distinto, igual que los repositorios que usan subject claims inmutables. La referencia de GitHub Action lista cada forma. Referencia de GitHub Action: entornos y subjects OIDC
Adjunta una política de permisos que permita solo lo que llama Envilder: ssm:GetParameter, una vez por variable, sobre los parámetros de esta aplicación. Nunca lista, escribe ni elimina parámetros.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ssm:GetParameter",
"Resource": "arn:aws:ssm:eu-west-1:123456789012:parameter/my-app/prod/*"
}]
}Los parámetros cifrados con la clave por defecto aws/ssm no necesitan nada más. Añade kms:Decrypt sobre la clave solo si usan una clave KMS gestionada por el cliente. El ARN debe llevar la región de los parámetros.
Añade Envilder al workflow
Inicia sesión primero con configure-aws-credentials y después ejecuta la acción. El job necesita id-token: write para pedir el token OIDC. Todos los pasos siguientes leen DB_PASSWORD y API_TOKEN como variables de entorno normales:
name: Deploy
on:
push:
branches: [main]
permissions:
id-token: write # Permite que el job pida 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 y API_TOKEN están definidas en este pasoEl log del paso lista cada variable con el valor enmascarado y termina con esta línea:
envilder: 2 secrets exported to the job environment (DB_PASSWORD, API_TOKEN)provider: aws se escribe a propósito. Sin eso, el proveedor sale de $config.provider en el archivo de mapa y por defecto es aws. El input prevalece sobre el archivo de mapa, así que este job lee SSM aunque el archivo nombre otro proveedor.
La región viene de aws-region en el paso de credenciales, que exporta AWS_REGION y AWS_DEFAULT_REGION. Envilder lee primero AWS_REGION, luego AWS_DEFAULT_REGION, y termina en us-east-1 si no encuentra ninguna. Un parámetro guardado en otra región se reporta como no encontrado.
Los valores llegan a los pasos siguientes a través del archivo GITHUB_ENV del runner, así que todos los pasos siguientes de este job pueden leerlos, incluidas las acciones de terceros. Los otros jobs no reciben nada: ejecuta la acción en cada job que necesite los valores.
Este workflow solo define map-file y provider. Los demás inputs y la salida están descritos en la referencia de GitHub Action.
Cuando solo un paso necesita los secretos
El modo por defecto comparte los valores con el resto del job. Dos inputs lo reducen.
Ejecuta un solo comando
Con command, la acción lo ejecuta con bash, y los secretos solo existen para ese comando y los procesos que inicia. Los pasos siguientes no los ven, y el paso termina con el código de salida del comando. Si falta un parámetro o está vacío, el comando no se inicia.
- uses: macalbert/envilder/github-action@v0
with:
map-file: envilder.json
provider: aws
command: ./deploy.sh --prodLo mismo con la CLI en un paso run necesita Node.js 22.12 o superior, así que configúralo antes:
- uses: actions/setup-node@v7
with:
node-version: 22.x
- run: npx envilder exec --map=envilder.json --provider=aws -- ./deploy.sh --prodLa CLI resuelve el mismo archivo de mapa y sale con 125, sin iniciar tu comando, cuando no se puede leer un parámetro. Deja su stderr en el log del paso: lleva los registros de máscaras. La Action no necesita ningún paso previo y ejecuta la versión empaquetada con su etiqueta, mientras que npx envilder descarga la última CLI publicada salvo que fijes una con npx envilder@<version>.
Escribe un archivo para una herramienta que lo necesita
Algunas herramientas leen un archivo en lugar del entorno, por ejemplo docker compose --env-file. Usa env-file y ponlo bajo runner.temp, fuera del espacio de trabajo. La salida env-file-path devuelve la ruta que has pasado:
- 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 -dQué se enmascara en los logs
GitHub oculta un valor en el log solo después de que algo lo registre. Esto es lo que hacen la acción y la CLI:
- La Action registra cada valor que lee con una orden de workflow ::add-mask::, en los tres modos. En los modos por defecto y command espera a que los registros se hayan escrito antes de exportar los valores o iniciar el comando, y se detiene sin exportar nada si un registro falla.
- Envilder imprime cada variable con el valor con asteriscos: un valor de más de 10 caracteres conserva los tres últimos, uno más corto va todo con asteriscos. Las rutas de parámetro también conservan los tres últimos caracteres.
- El enmascarado compara el texto exacto. Una copia transformada de un valor, por ejemplo codificada en base64, no se reconoce y se imprime en claro. El enmascarado solo afecta al log: no protege un archivo, un artifact ni una caché.
- Los errores que vienen de AWS se imprimen tal como los devuelve AWS y pueden contener el ARN completo del parámetro.
Si ejecutas la CLI tú mismo en lugar de la Action, envilder exec registra las máscaras cuando GITHUB_ACTIONS es true. Envilder sin subcomando, que escribe un archivo .env, no registra ninguna máscara en un workflow e imprime los tres últimos caracteres de los valores largos. En CI, prefiere la Action o envilder exec.
Errores habituales
| Mensaje | Solución |
|---|---|
Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity | Lo muestra configure-aws-credentials, antes de que se ejecute Envilder. El sub o el aud de la política de confianza no coincide con el token, o falta el proveedor de identidad en esta cuenta. El sub cambia con la rama, etiqueta, pull request o entorno de la ejecución. |
| El paso de credenciales falla al obtener un ID token | Al job le falta id-token: write, así que GitHub no le da ningún token OIDC. Añádelo a nivel de workflow o de job, junto con contents: read. El texto exacto depende de la versión de la acción, así que busca un mensaje sobre el ID token. |
Input required and not supplied: aws-region | configure-aws-credentials siempre requiere aws-region. Defínela en ese paso: también fija la región que usa Envilder. |
Could not load credentials from any providers | Se muestra bajo WHY? en el log de Envilder. Ninguna credencial ha llegado a Envilder: falta el paso de credenciales, va después del paso de Envilder o está en otro job. Las credenciales no pasan de un job a otro. |
is not authorized to perform: ssm:GetParameter on resource | El rol se ha asumido pero su política no cubre ese parámetro. Compara el ARN de Resource, región incluida, con el parámetro del mensaje. Un mensaje parecido sobre kms:Decrypt significa que al rol o a la política de la clave le falta ese permiso. |
not found | El motivo que se muestra bajo WHY? cuando GetParameter no encuentra el parámetro. Revisa el nombre y compara la región de la línea de identidad con la región del parámetro. El paso falla en los modos por defecto y command, y solo avisa con env-file. |
Use either env-file or command, not both. | Define solo uno de los 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 es uno de los nombres que el runner no deja definir en GITHUB_ENV. Cámbiale el nombre, o usa command o env-file. |
Hay más casos, como credenciales caducadas y Azure, en la referencia de GitHub Action.
Comparado con otras formas de leer SSM en un workflow
La alternativa simple es un paso run con la AWS CLI, que viene preinstalada en los runners Ubuntu alojados por GitHub, después del paso de credenciales. Para uno o dos parámetros funciona:
- run: |
value=$(aws ssm get-parameter --name /my-app/prod/db-password \
--with-decryption --query Parameter.Value --output text)
# Enmascara cada línea del valor antes de que nada pueda imprimirla
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ámetro necesita su comando, y los nombres viven en el workflow en lugar de en un archivo de mapa que los desarrolladores también usan en local con la CLI.
- Tienes que enmascarar el valor antes de escribirlo, y un valor con salto de línea no puede usar la forma NAME=value: GITHUB_ENV necesita su sintaxis de delimitador multilínea.
- --with-decryption es fácil de olvidar: sin eso un SecureString vuelve como texto cifrado.
Para uno o dos parámetros el script es más corto y no necesita ninguna acción adicional. Envilder empieza a compensar con varias variables, un archivo de mapa compartido con el desarrollo local y un paso que falla si falta cualquier parámetro.
Otras acciones del GitHub Marketplace también leen parámetros SSM. Antes de elegir una, comprueba qué enmascara, qué acciones IAM necesita (GetParameter o GetParametersByPath), si un parámetro que falta hace fallar el paso, y cómo se versiona y se mantiene. Para Envilder las respuestas son cada valor, solo ssm:GetParameter, y sí en los modos por defecto y command. Esta guía no compara otras acciones una por una.