Environments and Approval Gates in GitHub Actions

Environments turn a raw deploy job into a controlled, auditable release gate.

GitHub Actions environments let you attach protection rules, scoped secrets, and reviewers to a deployment target. This lesson shows how to require approval before production, add a wait timer, and keep production secrets isolated.

What an environment gives you

Required reviewers: named people or teams must approve before the job runs.
Wait timer: a forced delay before deployment, useful as a cancel window.
Deployment branch rules: only specific branches may deploy to it.
Scoped secrets and variables: production credentials live only in the production environment.

Adding a gated production job

Set environment: on the job. When the job needs to run, GitHub pauses it and requests approval from the configured reviewers:

.github/workflows/deploy.yml

jobs:
  deploy-prod:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://app.example.com
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

Configuring protection rules

Reviewers and wait timers are set in the repository under Settings, Environments, not in YAML. The workflow references the environment by name; the rules are enforced server-side, so they cannot be bypassed by editing the workflow file alone.

Promote staging then production

Chain two environment jobs so staging deploys automatically and production waits for approval:

.github/workflows/promote.yml

jobs:
  staging:
    environment: staging
    runs-on: ubuntu-latest
    steps: [{ run: ./deploy.sh staging }]
  production:
    needs: staging
    environment: production   # required reviewers configured in repo settings
    runs-on: ubuntu-latest
    steps: [{ run: ./deploy.sh production }]

Key takeaways

Environments attach reviewers, wait timers, and scoped secrets to a deploy target.
Protection rules are enforced server-side and cannot be bypassed in YAML alone.
Chain staging then production environments to auto-deploy staging and gate production.