Environment Variables

Environment variables are the recommended way to manage secrets (database passwords, API keys) and per-environment settings in Acme.

How it works

Reference environment variables in acme.yml using ${VARIABLE_NAME}:

sources:
  - type: postgres
    connection: ${DATABASE_URL}

notifications:
  on_failure:
    - type: slack
      webhook: ${SLACK_WEBHOOK}

Acme resolves these at runtime from:

1. System environment variables
2. .env file in the project root
3. .env.{environment} file (when using --env)

The .env file

Create a .env file in your project root:

# Database
DATABASE_URL=postgresql://localhost:5432/mydb
ANALYTICS_DB_URL=postgresql://localhost:5432/analytics

# API Keys
SLACK_WEBHOOK=https://hooks.slack.com/services/T00/B00/xxx
CLEARBIT_KEY=sk_abc123...

# Acme settings
ACME_LOG_LEVEL=info
ACME_WORKERS=4

# .env.example
DATABASE_URL=postgresql://user:password@host:5432/dbname
SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Per-environment configuration

Use environment-specific files for different deployment targets:

.env                    # Shared defaults (not committed)
.env.development        # Local development
.env.staging            # Staging environment
.env.production         # Production environment

Activate an environment:

acme run --env production

This loads variables in order:

1. .env (base)
2. .env.production (overrides)
3. System environment (highest priority)

Example

# .env.development
DATABASE_URL=postgresql://localhost:5432/mydb_dev
ACME_LOG_LEVEL=debug
ACME_WORKERS=2

# .env.production
DATABASE_URL=postgresql://prod-db:5432/mydb
ACME_LOG_LEVEL=warning
ACME_WORKERS=8

Built-in variables

Acme recognizes these environment variables:

Runtime variables

Acme also provides runtime variables you can use in your pipeline configuration:

sources:
  - type: postgres
    query: "SELECT * FROM users WHERE updated_at > :last_run"

error_handling:
  dead_letter:
    path: ./errors/${pipeline_name}_${run_id}.json

Secrets in CI/CD

GitHub Actions

# .github/workflows/deploy.yml
jobs:
  deploy:
    env:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
      SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
    steps:
      - run: acme run --env production

Docker

docker run --env-file .env.production acme/acme:latest

Related

• Configuration File — full acme.yml reference
• Deployment — environment setup for production
• Authentication — API key management