Documentación

Todo lo que necesitas para empezar con Envilder.

¿Qué es Envilder?

Envilder es una herramienta CLI y GitHub Action que descarga variables de entorno de un almacén de secretos en la nube (AWS SSM Parameter Store o Azure Key Vault) y las escribe en un archivo .env local — o las sube de vuelta. Defines un simple mapeo JSON entre nombres de variables y rutas de secretos, y Envilder hace el resto.

⚠️

Sin Envilder, los equipos copian secretos a mano, los guardan en archivos .env en texto plano en el repositorio, o mantienen scripts de shell frágiles por cada entorno. Esto lleva a credenciales filtradas, configuraciones inconsistentes e incorporaciones lentas.

✅

Con Envilder, un archivo param-map.json es la fuente única de verdad. Los secretos no salen del almacén hasta el momento de ejecución, cada entorno usa el mismo mapeo, y un nuevo desarrollador está operativo con un solo comando.

Requisitos

Node.js v20+ — Descargar
AWS CLI (para AWS SSM) — Guía de instalación
Azure CLI (para Azure Key Vault) — Guía de instalación

Instalación

pnpm

pnpm add -g envilder

npm

npm install -g envilder

npx

npx envilder --help

Credenciales de nube

AWS (por defecto)

Envilder usa tus credenciales AWS CLI. Configura el perfil por defecto:

aws configure

O usa un perfil con nombre:

aws configure --profile dev-account

# Then pass it to envilder
envilder --map=param-map.json --envfile=.env --profile=dev-account

Azure Key Vault

Envilder usa Azure Default Credentials. Inicia sesión con:

az login

Proporciona la URL del vault vía $config en tu archivo de mapeo o el flag --vault-url.

Permisos IAM

AWS

Tu usuario o rol IAM necesita:

Operación	Permiso
Pull	`ssm:GetParameter`
Push	`ssm:PutParameter`

Ejemplo de política IAM:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["ssm:GetParameter", "ssm:PutParameter"],
    "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/myapp/*"
  }]
}

Azure

Operación	Permiso
Pull	Get
Push	Set

Recomendado — asigna Key Vault Secrets Officer vía RBAC:

az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee <YOUR_OBJECT_ID> \
  --scope /subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.KeyVault/vaults/<VAULT>

Para acceso solo de lectura, Key Vault Secrets User es suficiente.

Archivo de mapeo

El archivo de mapeo (param-map.json) es el núcleo de Envilder. Es un archivo JSON que mapea nombres de variables de entorno (claves) a rutas de secretos (valores) en tu proveedor en la nube.

📄

Estructura: Cada clave se convierte en un nombre de variable de entorno en tu archivo .env. Cada valor es la ruta donde vive el secreto en tu proveedor en la nube.

Formato básico (AWS SSM — por defecto)

Cuando no hay sección $config, Envilder usa AWS SSM Parameter Store por defecto. Los valores deben ser rutas de parámetros SSM válidas (normalmente comenzando con /):

param-map.json json

{
  "API_KEY": "/myapp/prod/api-key",
  "DB_PASSWORD": "/myapp/prod/db-password",
  "SECRET_TOKEN": "/myapp/prod/secret-token"
}

Esto genera:

.env dotenv

API_KEY=<value from /myapp/prod/api-key>
DB_PASSWORD=<value from /myapp/prod/db-password>
SECRET_TOKEN=<value from /myapp/prod/secret-token>

La sección $config

Añade una clave $config a tu archivo de mapeo para declarar qué proveedor en la nube usar y su configuración. Envilder lee $config para la configuración y trata todas las demás claves como mapeos de secretos.

Opciones de $config

Clave	Tipo	Por defecto	Descripción
`provider`	`"aws"` \| `"azure"`	`"aws"`	Proveedor en la nube a usar
`vaultUrl`	`string`	—	URL de Azure Key Vault (requerido cuando el proveedor es "azure")
`profile`	`string`	—	Perfil AWS CLI para configuraciones multi-cuenta (solo AWS)

AWS SSM con perfil

Para usar un perfil AWS CLI específico (útil para configuraciones multi-cuenta), añade profile a $config:

param-map.json json

{
  "$config": {
    "provider": "aws",
    "profile": "prod-account"
  },
  "API_KEY": "/myapp/prod/api-key",
  "DB_PASSWORD": "/myapp/prod/db-password"
}

Esto indica a Envilder que use el perfil prod-account de tu archivo ~/.aws/credentials en lugar del perfil por defecto.

Azure Key Vault

Para Azure Key Vault, establece provider a "azure" y proporciona el vaultUrl:

param-map.json json

{
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "API_KEY": "myapp-prod-api-key",
  "DB_PASSWORD": "myapp-prod-db-password"
}

⚠️

Convención de nombres Azure: Los nombres de secretos de Key Vault solo permiten caracteres alfanuméricos y guiones. Envilder normaliza automáticamente los nombres — barras y guiones bajos se convierten en guiones (ej., /myapp/db/password → myapp-db-password).

Diferencias clave por proveedor

	AWS SSM	Azure Key Vault
Formato de ruta de secreto	Rutas de parámetros con barras `/myapp/prod/api-key`	Nombres con guiones `myapp-prod-api-key`
$config requerido	Ninguno (AWS es por defecto)	`provider + vaultUrl`
$config opcional	`profile`	—
Autenticación	Credenciales AWS CLI	Azure Default Credentials

Múltiples entornos

Un patrón común es tener un archivo de mapeo por entorno. La estructura es la misma, solo cambian las rutas de los secretos:

config/dev/param-map.json json

{
  "$config": {
    "provider": "aws",
    "profile": "dev-account"
  },
  "API_KEY": "/myapp/dev/api-key",
  "DB_PASSWORD": "/myapp/dev/db-password"
}

config/prod/param-map.json json

{
  "$config": {
    "provider": "aws",
    "profile": "prod-account"
  },
  "API_KEY": "/myapp/prod/api-key",
  "DB_PASSWORD": "/myapp/prod/db-password"
}

Luego obtén el correcto:

# Development
envilder --map=config/dev/param-map.json --envfile=.env.dev

# Production
envilder --map=config/prod/param-map.json --envfile=.env.prod

Sobreescribir $config con flags CLI

Los flags CLI siempre tienen prioridad sobre los valores de $config. Esto te permite establecer valores por defecto en el archivo y sobreescribirlos por invocación:

# Uses $config from the map file as-is
envilder --map=param-map.json --envfile=.env

# Overrides provider and vault URL, ignoring $config
envilder --provider=azure \
  --vault-url=https://other-vault.vault.azure.net \
  --map=param-map.json --envfile=.env

# Overrides just the AWS profile
envilder --map=param-map.json --envfile=.env --profile=staging-account

Orden de prioridad: flags CLI / inputs GHA → $config en archivo de mapeo → por defecto (AWS).

Comando pull

Descarga secretos de tu proveedor en la nube y genera un archivo .env local.

envilder --map=param-map.json --envfile=.env

Opciones

Opción	Descripción
`--map`	Ruta al archivo JSON de mapeo
`--envfile`	Ruta donde escribir el .env
`--provider`	aws (por defecto) o azure
`--vault-url`	URL de Azure Key Vault
`--profile`	Perfil AWS CLI a usar

Ejemplos

# Default (AWS SSM)
envilder --map=param-map.json --envfile=.env

# With AWS profile
envilder --map=param-map.json --envfile=.env --profile=prod-account

# Azure via $config in map file
envilder --map=azure-param-map.json --envfile=.env

# Azure via CLI flags
envilder --provider=azure \
  --vault-url=https://my-vault.vault.azure.net \
  --map=param-map.json --envfile=.env

Salida

.env dotenv

# Generated by Envilder
API_KEY=abc123
DB_PASSWORD=secret456

Comando push

Sube variables de entorno de un archivo .env local a tu proveedor en la nube usando un archivo de mapeo.

envilder --push --envfile=.env --map=param-map.json

Opciones

Opción	Descripción
`--push`	Activa el modo push (requerido)
`--envfile`	Ruta a tu archivo .env local
`--map`	Ruta al JSON de mapeo de parámetros
`--provider`	aws (por defecto) o azure
`--vault-url`	URL de Azure Key Vault
`--profile`	Perfil AWS CLI (solo AWS)

Ejemplos

# Push to AWS SSM
envilder --push --envfile=.env --map=param-map.json

# With AWS profile
envilder --push --envfile=.env.prod --map=param-map.json --profile=prod-account

# Azure via $config in map file
envilder --push --envfile=.env --map=azure-param-map.json

# Azure via CLI flags
envilder --push --provider=azure \
  --vault-url=https://my-vault.vault.azure.net \
  --envfile=.env --map=param-map.json

Subir variable individual

Sube una variable de entorno individual directamente sin ningún archivo.

envilder --push --key=API_KEY --value=<SECRET> --secret-path=/myapp/api/key

Opciones

Opción	Descripción
`--push`	Activa el modo push (requerido)
`--key`	Nombre de la variable de entorno
`--value`	Valor a almacenar
`--secret-path`	Ruta completa del secreto en tu proveedor en la nube
`--provider`	aws (por defecto) o azure
`--vault-url`	URL de Azure Key Vault
`--profile`	Perfil AWS CLI (solo AWS)

Configuración de GitHub Action

La GitHub Action de Envilder obtiene secretos de AWS SSM o Azure Key Vault en archivos .env durante tu workflow CI/CD. No hace falta compilar — la action está pre-construida y lista para usar desde GitHub Marketplace.

Prerrequisitos

AWS: Configura credenciales con aws-actions/configure-aws-credentials
Azure: Configura credenciales con azure/login
Un param-map.json en tu repositorio

La GitHub Action solo soporta el modo pull (sin push).

Ejemplo básico de workflow

.github/workflows/deploy.yml yaml

name: Deploy Application

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

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

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-east-1

      - name: Pull Secrets from AWS SSM
        uses: macalbert/envilder/github-action@v0
        with:
          map-file: config/param-map.json
          env-file: .env

      - uses: actions/setup-node@v6
        with:
          node-version: "20.x"

      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm deploy

Workflow multi-entorno

.github/workflows/deploy-env.yml yaml

name: Deploy to Environment

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options: [dev, staging, production]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-24.04
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v5

      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-east-1

      - name: Pull ${{ inputs.environment }} secrets
        uses: macalbert/envilder/github-action@v0
        with:
          map-file: config/${{ inputs.environment }}/param-map.json
          env-file: .env

      - uses: actions/setup-node@v6
        with:
          node-version: "20.x"
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm deploy

Workflow de Azure Key Vault

.github/workflows/deploy-azure.yml yaml

name: Deploy with Azure Key Vault

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

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

      - name: Azure Login
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Pull Secrets from Azure Key Vault
        uses: macalbert/envilder/github-action@v0
        with:
          map-file: config/param-map.json
          env-file: .env
          provider: azure
          vault-url: https://my-vault.vault.azure.net

      - uses: actions/setup-node@v6
        with:
          node-version: "20.x"
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm deploy

Inputs y outputs de la Action

Inputs

Input	Requerido	Por defecto	Descripción
`map-file`	Sí	—	Ruta al archivo JSON de mapeo
`env-file`	Sí	—	Ruta al archivo .env a generar
`provider`	No	`aws`	aws o azure
`vault-url`	No	—	URL de Azure Key Vault

Outputs

Output	Descripción
`env-file-path`	Ruta al archivo .env generado

Prioridad de configuración

Cuando hay múltiples fuentes de configuración, Envilder las resuelve en este orden (el más alto gana):

1. Flags CLI / inputs GHA

2. $config en el archivo de mapeo

3. Por defecto (AWS)

Esto significa que --provider=azure en la CLI sobreescribirá "provider": "aws" en $config.

Configuración de Azure Key Vault

Comprueba qué modelo de acceso usa tu vault:

az keyvault show --name <VAULT_NAME> \
  --query properties.enableRbacAuthorization

true → true → Azure RBAC (recomendado)
false / null → false / null → Vault Access Policy (clásico)

Opción A — Azure RBAC (recomendado)

az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee <YOUR_OBJECT_ID> \
  --scope /subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.KeyVault/vaults/<VAULT>

Opción B — Vault Access Policy

az keyvault set-policy \
  --name <VAULT_NAME> \
  --object-id <YOUR_OBJECT_ID> \
  --secret-permissions get set list

Para acceso solo de lectura, get list es suficiente. Añade set para push.