Environments

An environment is a named place your CI deploys to — production, staging, app-store — with its own secrets and its own rules about who can deploy, from which branches, and on which machines. It's how you keep a signing key or a deploy credential away from the rest of your CI.

CI secrets are available to every workflow on every branch, so anyone who can push can read them. An environment's secrets are much harder to reach. A job receives them only when all of these hold:

• the job declares the environment (environment: production),
• someone allowed to deploy approved that exact commit and workflow,
• the commit is the current head of a branch the environment allows,
• and the job runs on a runner dedicated to the environment, which runs nothing else.

Environment workflows never run on a push or a merge. They run when someone deploys them.

Set one up#

Environments are configured by the repository's managers (organization owners and admins) in the repo's Settings → Environments, or over the API.

1. Create it. A new environment is enabled, requires a reviewer, and allows deploying from main.

2. Add its secrets and variables. Secret values are encrypted and never shown again; variables are plain values anyone with write access can read.

3. Add reviewers — the people who may approve a deploy. They need read access to the repo. (Or turn off Required reviewers to let anyone with write access deploy.)

4. Dedicate a runner. Register a runner for it, ideally on a machine that holds nothing else, and bind it to the environment. A bound runner takes only that environment's jobs — never ordinary CI — so code from an arbitrary branch never runs where the secrets land.

5. Point a workflow at it. Give the job environment: and a manual trigger:

   # .oak/workflows/release.yml
   on: [workflow_dispatch]
   jobs:
     release:
       runs-on: release-mac
       environment: production
       steps:
         - uses: actions/checkout@v4
         - run: ./scripts/release.sh
           env:
             SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
   

   An environment workflow has exactly one job. environment: also takes GitHub's mapping form, {name: production, url: https://example.com}. The name must be written out: it can't come from an expression.

6. Deploy it (below).

Deploy#

oak ci deploy --environment production            # preview, confirm, deploy main's head
oak ci deploy -e production --workflow release --branch main --yes
oak ci deploy -e production --dry-run             # just show what would deploy

A deploy has two steps. First Oak shows what would run: the branch head, the workflow and its exact content hash, the environment's current policy version, its reviewers, and anything in the way. Then you approve exactly those values. If anything moves in between, the approval is refused: the branch gets a new commit, the workflow changes, or someone edits the environment. You re-review the new state; nothing runs that you didn't see.

An approval starts one run and is good for 30 minutes. The first runner bound to the environment that polls takes the job. Just before it hands the job over, Oak checks every rule again: environment enabled, same policy, head unchanged, approver still allowed, runner still bound. If anything failed, the run fails and nothing is sent.

The same deploy is available from Settings → Environments → Deploy, and over the API as a preview (GET …/release-preview) followed by an authorization (POST …/ci/release-authorizations) carrying the preview's values. An API key used to deploy must carry the explicit release scope.

Protection rules#

Every change to an environment moves its policy version, which cancels any approval made against the old settings.

Platform administrators of the Oak instance can also approve deploys.

What the job sees#

• Secrets: the environment's secrets, through ${{ secrets.NAME }} as usual, plus the job's own GITHUB_TOKEN. Your repo's ordinary CI secrets are not included, so an environment job only ever has what you put in the environment.
• Variables: as environment variables, and as ${{ vars.NAME }}.
• Who and what: besides the usual OAK_CI_RUN_ID, OAK_CI_COMMIT, and OAK_CI_BRANCH, the job gets OAK_CI_ENVIRONMENT_NAME, OAK_CI_POLICY_VERSION, OAK_CI_AUTHORIZATION_ID, OAK_CI_WORKFLOW_PATH, and OAK_CI_WORKFLOW_HASH, so a deploy script can record exactly what was approved.

Two rules keep secrets from leaking sideways. A secret and a variable in one environment can't share a name. And an ordinary repo secret with the same name as any environment secret is withheld from ordinary jobs, so deleting a key from your CI secrets and adding it to an environment really moves it. Delete the ordinary copy.

Each line of a secret must be at least 4 characters, so the runner can mask it in logs.

Who can do what#

An API key that changes an environment needs the admin scope. One that deploys needs release.

Differences from GitHub#

API#

All under /api/{owner}/{name}/ci/, authenticated like the rest of the API.