Documentació

Tot el que necessites per començar amb Envilder.

Què és Envilder?

Envilder és una eina CLI i GitHub Action que descarrega variables d'entorn d'un magatzem de secrets al núvol (AWS SSM Parameter Store o Azure Key Vault) i les escriu en un fitxer .env local — o les puja de tornada. Definiu un simple mapeig JSON entre noms de variables i rutes de secrets, i Envilder fa la resta.

⚠️

Sense Envilder, els equips copien secrets a mà, els guarden en fitxers .env en text pla al repositori, o mantenen scripts de shell fràgils per cada entorn. Això porta a credencials filtrades, configuracions inconsistents i incorporacions lentes.

✅

Amb Envilder, un fitxer param-map.json és la font única de veritat. Els secrets no surten del magatzem fins al moment d'execució, cada entorn utilitza el mateix mapeig, i un nou desenvolupador està operatiu amb una sola comanda.

Requisits

Node.js v20+ — Descarregar
AWS CLI (per AWS SSM) — Guia d'instal·lació
Azure CLI (per Azure Key Vault) — Guia d'instal·lació

Instal·lació

pnpm

pnpm add -g envilder

npm

npm install -g envilder

npx

npx envilder --help

Credencials del núvol

AWS (per defecte)

Envilder utilitza les teves credencials AWS CLI. Configura el perfil per defecte:

aws configure

O utilitza un perfil amb nom:

aws configure --profile dev-account

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

Azure Key Vault

Envilder utilitza Azure Default Credentials. Inicia sessió amb:

az login

Proporciona l'URL del vault via $config al fitxer de mapeig o el flag --vault-url.

Permisos IAM

AWS

El teu usuari o rol IAM necessita:

Operació	Permís
Pull	`ssm:GetParameter`
Push	`ssm:PutParameter`

Exemple 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ó	Permís
Pull	Get
Push	Set

Recomanat — assigna Key Vault Secrets Officer via RBAC:

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

Per accés només de lectura, Key Vault Secrets User és suficient.

Fitxer de mapeig

El fitxer de mapeig (param-map.json) és el nucli d'Envilder. És un fitxer JSON que mapeja noms de variables d'entorn (claus) a rutes de secrets (valors) al teu proveïdor al núvol.

📄

Estructura: Cada clau es converteix en un nom de variable d'entorn al teu fitxer .env. Cada valor és la ruta on viu el secret al teu proveïdor al núvol.

Format bàsic (AWS SSM — per defecte)

Quan no hi ha secció $config, Envilder utilitza AWS SSM Parameter Store per defecte. Els valors han de ser rutes de paràmetres SSM vàlides (normalment començant amb /):

param-map.json json

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

Això 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ó $config

Afegeix una clau $config al teu fitxer de mapeig per declarar quin proveïdor al núvol utilitzar i la seva configuració. Envilder llegeix $config per la configuració i tracta totes les altres claus com a mapeigs de secrets.

Opcions de $config

Clau	Tipus	Per defecte	Descripció
`provider`	`"aws"` \| `"azure"`	`"aws"`	Proveïdor al núvol a utilitzar
`vaultUrl`	`string`	—	URL d'Azure Key Vault (requerit quan el proveïdor és "azure")
`profile`	`string`	—	Perfil AWS CLI per a configuracions multi-compte (només AWS)

AWS SSM amb perfil

Per utilitzar un perfil AWS CLI específic (útil per a configuracions multi-compte), afegeix 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"
}

Això indica a Envilder que utilitzi el perfil prod-account del teu fitxer ~/.aws/credentials en lloc del perfil per defecte.

Azure Key Vault

Per Azure Key Vault, estableix provider a "azure" i 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ó de noms Azure: Els noms de secrets de Key Vault només permeten caràcters alfanumèrics i guions. Envilder normalitza automàticament els noms — barres i guions baixos es converteixen en guions (p. ex., /myapp/db/password → myapp-db-password).

Diferències clau per proveïdor

	AWS SSM	Azure Key Vault
Format de ruta de secret	Rutes de paràmetres amb barres `/myapp/prod/api-key`	Noms amb guions `myapp-prod-api-key`
$config requerit	Cap (AWS és per defecte)	`provider + vaultUrl`
$config opcional	`profile`	—
Autenticació	Credencials AWS CLI	Azure Default Credentials

Múltiples entorns

Un patró comú és tenir un fitxer de mapeig per entorn. L'estructura és la mateixa, només canvien les rutes dels secrets:

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

Després obté el correcte:

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

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

Sobreescriure $config amb flags CLI

Els flags CLI sempre tenen prioritat sobre els valors de $config. Això et permet establir valors per defecte al fitxer i sobreescriure'ls per invocació:

# 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

Ordre de prioritat: flags CLI / inputs GHA → $config al fitxer de mapeig → per defecte (AWS).

Comanda pull

Descarrega secrets del teu proveïdor al núvol i genera un fitxer .env local.

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

Opcions

Opció	Descripció
`--map`	Ruta al fitxer JSON de mapeig
`--envfile`	Ruta on escriure el .env
`--provider`	aws (per defecte) o azure
`--vault-url`	URL d'Azure Key Vault
`--profile`	Perfil AWS CLI a utilitzar

Exemples

# 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

Sortida

.env dotenv

# Generated by Envilder
API_KEY=abc123
DB_PASSWORD=secret456

Comanda push

Puja variables d'entorn d'un fitxer .env local al teu proveïdor al núvol utilitzant un fitxer de mapeig.

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

Opcions

Opció	Descripció
`--push`	Activa el mode push (requerit)
`--envfile`	Ruta al teu fitxer .env local
`--map`	Ruta al JSON de mapeig de paràmetres
`--provider`	aws (per defecte) o azure
`--vault-url`	URL d'Azure Key Vault
`--profile`	Perfil AWS CLI (només AWS)

Exemples

# 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

Pujar variable individual

Puja una variable d'entorn individual directament sense cap fitxer.

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

Opcions

Opció	Descripció
`--push`	Activa el mode push (requerit)
`--key`	Nom de la variable d'entorn
`--value`	Valor a emmagatzemar
`--secret-path`	Ruta completa del secret al teu proveïdor al núvol
`--provider`	aws (per defecte) o azure
`--vault-url`	URL d'Azure Key Vault
`--profile`	Perfil AWS CLI (només AWS)

Configuració de GitHub Action

La GitHub Action d'Envilder obté secrets d'AWS SSM o Azure Key Vault en fitxers .env durant el teu workflow CI/CD. No cal compilar — l'action està pre-construïda i llesta per utilitzar des de GitHub Marketplace.

Prerequisits

AWS: Configura credencials amb aws-actions/configure-aws-credentials
Azure: Configura credencials amb azure/login
Un param-map.json al teu repositori

La GitHub Action només suporta el mode pull (sense push).

Exemple bàsic 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-entorn

.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 d'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 i outputs de l'Action

Inputs

Input	Requerit	Per defecte	Descripció
`map-file`	Sí	—	Ruta al fitxer JSON de mapeig
`env-file`	Sí	—	Ruta al fitxer .env a generar
`provider`	No	`aws`	aws o azure
`vault-url`	No	—	URL d'Azure Key Vault

Outputs

Output	Descripció
`env-file-path`	Ruta al fitxer .env generat

Prioritat de configuració

Quan hi ha múltiples fonts de configuració, Envilder les resol en aquest ordre (el més alt guanya):

1. Flags CLI / inputs GHA

2. $config al fitxer de mapeig

3. Per defecte (AWS)

Això vol dir que --provider=azure a la CLI sobreescriurà "provider": "aws" a $config.

Configuració d'Azure Key Vault

Comprova quin model d'accés utilitza el teu vault:

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

true → true → Azure RBAC (recomanat)
false / null → false / null → Vault Access Policy (clàssic)

Opció A — Azure RBAC (recomanat)

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

Opció B — Vault Access Policy

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

Per accés només de lectura, get list és suficient. Afegeix set per push.