Environments, approvals, and rollback

An environment is a named gate, not a server

In GitHub Actions, an environment — staging, production — is not a machine. It is a named object on the repo that carries two things: protection rules that decide when a job targeting it may run, and environment-scoped secrets and variables that only resolve inside a job that names that environment. A job opts in with one line:

jobs:
  deploy-prod:
    runs-on: ubuntu-latest
    environment: production        # ← binds this job to the prod gate
    steps:
      - run: ./deploy.sh
        env:
          API_KEY: ${{ secrets.API_KEY }}   # resolves to the *production* secret

The instant a job declares environment: production, three things become true. It will not start until the environment’s protection rules pass. Its secrets.* references resolve to the environment’s secrets, shadowing repo-level secrets of the same name. And if a reviewer is required, the job sits in a Waiting state — visibly paused in the run UI — until someone with access approves it. Crucially, a job that is waiting on approval cannot read the environment’s secrets yet: the production API key is unreachable until the gate clears. That is the property you are buying. A leaked workflow that never reaches an approved prod job never sees prod credentials.

Protection rules: reviewers, timers, and who may deploy

When you configure a production environment, the question is not “how do we add a gate?” but “what does this gate actually stop?” GitHub gives an environment a small, blunt set of protection rules, and a senior reads them as blast-radius controls.

On Free/Pro/Team plans these rules apply to public repos only; private repos need GitHub Team or Enterprise. And one design wrinkle bites: protection rules attach to the job, not the workflow. If three jobs each target production, a reviewer approves three times — the fastest road to approval fatigue there is.

The promotion model: staging auto, production paused

The standard shape is a single pipeline that flows build → staging → production, where staging is automatic and production is a gated promotion of the same artifact. You build once, deploy that exact build to staging with no gate, and the production job — depending on staging via needs: — pauses at its environment gate until a reviewer promotes it. Add concurrency: so two pushes can’t race into the same environment.

concurrency:
  group: deploy-${{ github.ref }}   # one prod deploy at a time per ref
  cancel-in-progress: false         # let the in-flight deploy finish, queue the next

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging            # no required reviewer -> runs automatically
    steps:
      - run: ./deploy.sh staging

  deploy-production:
    needs: deploy-staging           # promote the same build
    runs-on: ubuntu-latest
    environment:
      name: production              # required reviewers configured in repo settings
      url: https://app.example.com
    steps:
      - run: ./deploy.sh production

concurrency is the quiet hero here. Without it, two merges to main minutes apart launch two prod deploys that interleave — the older artifact can land after the newer one and silently win. The group key is any string; setting cancel-in-progress: false gives you the safe default of “finish the current deploy, then run the next,” at most one in progress and one pending.

When it breaks: rollback vs roll-forward

The bad deploy ships. Now what? Two moves. Rollback: redeploy the previous known-good artifact — fast, and trivial when your pipeline can re-run a prior build’s deploy job. Roll-forward (a.k.a. fix-forward): write the fix, push it through the same gated pipeline, ship a new version on top.

Rollback is the instinct, but it has a sharp edge: once a deploy has run a database migration, redeploying old code does not roll the schema back. The old binary now meets a schema it was never written for — a dropped column, a renamed table, a backfilled enum. GitLab’s own guidance is blunt: there is no guarantee app and database roll back together, so the safest strategy is usually to roll forward. Roll back code, roll forward data. If migrations are additive and backward-compatible (the expand/contract discipline), a code rollback is safe because the old code still works against the new schema. If they’re destructive, rollback can corrupt or lose data, and a forward fix — a compensating migration plus the corrected code — is the only honest move.