Environment Variable Interpolation

Use ${VAR_NAME} syntax inside string values of deployless.yaml to inject values from environment variables at build time. This keeps sensitive or environment-specific values out of the YAML, so you can safely commit it to public repositories.

Syntax

Syntax	Behavior
${VAR}	Replaced with the value of VAR. Error if not defined.
${VAR:-default}	Replaced with VAR if defined, otherwise uses default.

Variables are resolved in string values only — integers, booleans, lists, and dict keys are never interpolated. A single string can contain multiple references: "https://${HOST}:${PORT}/v1".

Source

Variables are resolved exclusively from os.environ — the shell environment where deployless runs. The .env file configured via env_file: is not used for interpolation; that file is reserved for Lambda runtime environment variables and SSM secrets.

Local development

Set variables in your shell before running deployless:

# Option 1: export (persists in current shell session)
export API_DOMAIN=api.myapp.com
export COGNITO_POOL_ARN=arn:aws:cognito-idp:us-east-1:123456789:userpool/us-east-1_ABC
deployless deploy

# Option 2: inline (one-off, does not persist)
API_DOMAIN=api.myapp.com COGNITO_POOL_ARN=arn:aws:... deployless deploy

# Option 3: direnv (.envrc file, auto-loaded per directory)
# echo 'export API_DOMAIN=api.myapp.com' >> .envrc && direnv allow

GitHub Actions

Store sensitive values as repository secrets, then pass them via the env: block:

deployless.yaml

name: my-app
stage: ${DEPLOY_STAGE:-dev}
api:
  domain:
    domain_name: ${API_DOMAIN}
  auth:
    type: cognito
    user_pool_arn: ${COGNITO_POOL_ARN}

.github/workflows/deploy.yml

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install deployless
      - run: deployless deploy
        env:
          API_DOMAIN: ${{ secrets.API_DOMAIN }}
          COGNITO_POOL_ARN: ${{ secrets.COGNITO_POOL_ARN }}
          DEPLOY_STAGE: production

If any ${VAR} reference cannot be resolved (not in the environment and no default), the build fails with error E32 before any resources are created.