Documentación

Todo lo que necesitas para empezar con Envilder.

¿Qué es Envilder?

Envilder es un sistema de resolución de configuración basado en un modelo. Defines un mapeo JSON entre nombres de variables y rutas de secretos en la nube, y Envilder los resuelve de forma consistente: vía la CLI para desarrollo local, la GitHub Action para CI/CD o los SDKs de runtime para el inicio de la aplicación. Funciona con AWS SSM Parameter Store y Azure Key Vault.

⚠️

Sin Envilder, los equipos fragmentan la gestión de secretos entre herramientas y etapas. El entorno local usa archivos .env, CI/CD lee de integraciones con vaults, producción tiene su propio método. Esto provoca desfase de configuración, credenciales filtradas e incorporaciones lentas.

✅

Con Envilder, un modelo de mapeo es la fuente única de verdad. Los secretos se resuelven desde tu vault en la nube bajo demanda: mismo contrato, mismo comportamiento, ya sea ejecutando la CLI localmente, la GitHub Action en CI o un SDK al iniciar la app.

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=envilder.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 (envilder.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 /):

envilder.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:

envilder.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:

envilder.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/envilder.json json

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

config/prod/envilder.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/envilder.json --envfile=.env.dev

# Production
envilder --map=config/prod/envilder.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=envilder.json --envfile=.env

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

# Overrides just the AWS profile
envilder --map=envilder.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=envilder.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=envilder.json --envfile=.env

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

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

# Azure via CLI flags
envilder --provider=azure \
  --vault-url=https://my-vault.vault.azure.net \
  --map=envilder.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=envilder.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=envilder.json

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

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

# Azure via CLI flags
envilder --push --provider=azure \
  --vault-url=https://my-vault.vault.azure.net \
  --envfile=.env --map=envilder.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)

.NET SDK

Carga secretos directamente en tu aplicación .NET al inicio. Fachada de una línea, constructor fluido, integración con IConfiguration o control programático total.

📦 NuGet v0.4.0

Instalación

dotnet add package Envilder

Una línea: resolver + inyectar

Resuelve secretos del archivo de mapeo e inyéctalos en Environment en una sola llamada:

using Envilder;

// Resolve secrets and inject into Environment
Env.Load("envilder.json");

var dbPassword = Environment.GetEnvironmentVariable("DB_PASSWORD");

Resolver sin inyectar

Obtén secretos como un diccionario sin modificar el entorno:

using Envilder;

var secrets = Env.ResolveFile("envilder.json");
var dbPassword = secrets["DB_PASSWORD"];

Constructor fluido con sobreescrituras

Sobreescribe la configuración del proveedor de forma programática con la API fluida:

using Envilder;

var secrets = Env.FromMapFile("envilder.json")
    .WithProvider(SecretProviderType.Azure)
    .WithVaultUrl("https://my-vault.vault.azure.net")
    .Resolve();

// Or inject directly
Env.FromMapFile("envilder.json")
    .WithProfile("staging")
    .Inject();

Carga basada en entorno

Enruta la carga de secretos según tu entorno actual. Cada entorno mapea a su archivo de secretos:

using Envilder;

var env = Environment.GetEnvironmentVariable("APP_ENV") ?? "development";

Env.Load(env, new Dictionary<string, string?>
{
    ["production"] = "prod-secrets.json",
    ["development"] = "dev-secrets.json",
    ["test"] = null,  // no secrets loaded
});

Validación de secretos

Validación opcional que asegura que todos los secretos resueltos tienen valores no vacíos:

using Envilder;

var secrets = Env.ResolveFile("envilder.json");
secrets.ValidateSecrets(); // throws SecretValidationException if any value is empty

Vía IConfiguration (ASP.NET)

Añade Envilder como fuente de configuración en tu aplicación ASP.NET:

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddEnvilder("envilder.json");
var app = builder.Build();

Avanzado: control programático total

Analiza el archivo de mapeo, resuelve secretos e inyéctalos en las variables de entorno:

using Envilder;

var secrets = await Env.ResolveFileAsync("envilder.json");
EnvilderClient.InjectIntoEnvironment(secrets);

Documentación completa →

Python SDK

Carga secretos directamente en tu aplicación Python al inicio. Configuración en una línea o control detallado con el constructor fluido.

📦 PyPI v0.4.0

Instalación

uv add envilder
# or
pip install envilder

Inicio rápido: una línea

Carga secretos desde un archivo de mapeo e inyéctalos en el entorno:

from envilder import Envilder

Envilder.load('envilder.json')

Carga basada en entorno

Recomendado para aplicaciones multi-entorno. Mapea cada entorno a su archivo de secretos:

from envilder import Envilder
import os

env = os.getenv('APP_ENV', 'development')

Envilder.load(env, {
    'production': 'prod-secrets.json',
    'development': 'dev-secrets.json',
    'test': None,
})

Resolver sin inyectar

Obtén secretos como un diccionario sin modificar el entorno:

secrets = Envilder.resolve_file('envilder.json')

Constructor fluido con sobreescrituras

Sobreescribe la configuración del proveedor de forma programática con la API fluida:

from envilder import Envilder, SecretProviderType

secrets = (
    Envilder.from_map_file('envilder.json')
    .with_provider(SecretProviderType.AZURE)
    .with_vault_url('https://my-vault.vault.azure.net')
    .resolve()
)

Validación de secretos

Validación opcional que asegura que todos los secretos resueltos tienen valores no vacíos:

from envilder import Envilder, validate_secrets

secrets = Envilder.resolve_file('envilder.json')
validate_secrets(secrets)  # raises SecretValidationError if any value is empty

Documentación completa →

Node.js SDK

Carga secretos directamente en tu aplicación Node.js al inicio. API asíncrona con fachada de una línea o constructor fluido para control total.

📦 npm v0.2.0

Instalación

npm install @envilder/sdk

Inicio rápido: una línea

Carga secretos desde un archivo de mapeo e inyéctalos en process.env:

import { Envilder } from '@envilder/sdk';

// Resolve secrets and inject into process.env
await Envilder.load('envilder.json');

const dbPassword = process.env.DB_PASSWORD;

Resolver sin inyectar

Obtén secretos como un Map sin modificar el entorno:

import { Envilder } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
const dbPassword = secrets.get('DB_PASSWORD');

Constructor fluido con sobreescrituras

Sobreescribe la configuración del proveedor de forma programática con la API fluida:

import { Envilder, SecretProviderType } from '@envilder/sdk';

const secrets = await Envilder.fromMapFile('envilder.json')
  .withProvider(SecretProviderType.Azure)
  .withVaultUrl('https://my-vault.vault.azure.net')
  .resolve();

// Or inject directly
await Envilder.fromMapFile('envilder.json')
  .withProfile('staging')
  .inject();

Carga basada en entorno

Recomendado para aplicaciones multi-entorno. Mapea cada entorno a su archivo de secretos:

import { Envilder } from '@envilder/sdk';

const env = process.env.APP_ENV ?? 'development';

await Envilder.load(env, {
  production: 'prod-secrets.json',
  development: 'dev-secrets.json',
  test: null,  // no secrets loaded
});

Validación de secretos

Validación opcional que asegura que todos los secretos resueltos tienen valores no vacíos:

import { Envilder, validateSecrets } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
validateSecrets(secrets); // throws SecretValidationError if any value is empty

Documentación completa →

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 envilder.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/envilder.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 }}/envilder.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/envilder.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.