Skip to main content

Env vars and secrets with catladder

Environment variables are declared per component in catladder.ts; secret values are never checked into the repo.

Declaring variables​

components: {
  app: {
    vars: {
      // names of secret vars — values are stored in the secrets vault, not in git
      secret: ["API_KEY"],
      public: {
        MY_VAR: "some value",
        // reference other vars, including from other components:
        GRAPHQL_ENDPOINT: "${api:ROOT_URL}/graphql",
      },
    },
  },
}

Predefined per component/env: ROOT_URL, HOSTNAME, PORT (plus deploy-type specific ones). All vars are available at build time and at runtime. After changing declarations, regenerate with yarn catenv and commit.

Setting secret values​

Secret values are managed through the catladder CLI — never by editing files in the repo. All secrets commands accept a scope: dev:web (one env of one component), dev: (one env, all components), :web (all envs of one component), or nothing (everything).

Check what is declared and what is still unset (never prints values unless --reveal is passed):

yarn catladder project secrets-list
yarn catladder project secrets-list --check   # non-zero exit when something is unset

Set a single secret (the usual case — also for rotating one value across all envs via the :component scope):

echo -n "the-value" | yarn catladder project secrets-set dev:web API_KEY
yarn catladder project secrets-set :web API_KEY --value-file /path/to/value

Prefer stdin or --value-file over --value so values stay out of shell history. Never pass a real secret value you found in the conversation without the user having provided it for this purpose.

Bulk-edit several secrets as a YAML document (component → env → key: value):

yarn catladder project secrets-pull dev: --out /tmp/secrets.yml   # unset ones appear as "🚨 FILL ME"
# edit the file, then:
yarn catladder project secrets-push dev: --file /tmp/secrets.yml  # partial docs are fine

secrets-push skips placeholder/empty values, rejects undeclared keys, and may be partial — only the provided keys are written. Both support --key KEY1,KEY2 to narrow further. Delete the temp file afterwards; never commit it.

Humans may instead use the interactive editor flow (project config-secrets, opens $EDITOR); as an agent, use the commands above.

All of these write to the secrets vault (the source of truth) and automatically mirror to the enabled CI backends — which vault is configured makes no difference to the commands.

GitHub pipelines​

GitHub Actions cannot read the vault at runtime; secrets are mirrored into GitHub environment secrets (one GitHub environment per catladder env). Sync them with:

yarn catladder project secrets-sync-github

Run this after adding/changing secrets when a github pipeline is enabled.

Local development​

catenv generates the local env (.env files / exported vars via direnv) for the local environment. If a var is missing locally, check its declaration in catladder.ts and re-run yarn catenv before suspecting anything else.

  • catladder-config — general catladder.ts structure and regeneration
  • catladder-builds — build-time vars (jobVars) and build config
  • catladder-deploys — runtime deploy config
  • catladder-pipelines — how the generated pipelines work
  • catladder-cli — non-interactive CLI usage and command reference
  • catladder-migrate-ci-backend — moving between CI backends (the vault is what blocks decommissioning the old one)