What do GitHub Actions environment protection rules gate, and how does the job behave?

## The construct An environment is a named target defined on the repository — `staging`, `production`, `preview` — that carries three things: its own secrets, its own variables, and a set of protection rules. A job joins it with a single key: jobs: deploy: runs-on: ubuntu-latest environment: name: production url: https://app.example.com steps: - run: ./deploy.sh env: TOKEN: ${{ secrets.DEPLOY_TOKEN }} # the production-scoped one The optional `url` is displayed on the deployment in the UI and on the pull request, which is why preview deployments set it dynamically from a step output. ## The rules and what each one stops **Required reviewers.** A list of users or teams; a named reviewer must approve before the job runs. GitHub allows up to six reviewers to be configured, any one of whom can approve, and there is a setting to prevent the person who triggered the run from self-approving. The run sits in `Waiting`; approvers are notified and can approve or reject with a comment. Rejection fails the job. **Wait timer.** A fixed delay before the job is dispatched, configurable up to 30 days. It buys a cancellation window — a canary that has been live for fifteen minutes and is alerting can be stopped before the wide rollout job starts. **Deployment branch and tag policies.** Restrict which refs may deploy to the environment: protected branches only, or a set of name patterns for branches and tags. A run from any other ref that targets the environment fails rather than deploying. This is what stops a contributor's branch from reaching production by copying the deploy job. **Custom protection rules.** GitHub Apps can register as gates, letting an external system — a change-management tool, an observability check — approve or reject the deployment programmatically. ## The behaviour that matters The rules are evaluated **before the job starts**. The job does not occupy a runner while waiting, so a week-long approval delay costs nothing in runner time, and — critically — the environment's secrets have not been decrypted onto any machine. Contrast that with a step-level `if:` gate, where the job is already running with the credentials in its environment and the check is just a branch in the script. That difference is the whole security argument for environments. Consequences worth stating explicitly: - Jobs downstream of the gated job via `needs:` also wait, because their dependency has not completed. - Approval is per run and per environment; the same environment reached twice in one workflow prompts again. - Approvals, rejections, timestamps, and the approver are recorded on the deployment, giving an audit trail without any extra tooling. - A job that names an environment that does not exist causes it to be created implicitly with no rules, which is a quiet way to lose the gate — a typo in the environment name yields an unprotected deploy. ## Where the boundary is drawn against branch policy Environment protection governs **deployments**: what may run, when, and with which credentials. It does not decide whether a commit may land on the default branch — that is repository branch policy, a separate control. A mature setup uses both: policy decides what merges, the environment decides what ships and who signed off. ## Common design A typical arrangement is `staging` with no reviewers and a branch policy limiting it to the default branch, and `production` with the same branch policy plus two required reviewers and a short wait timer. Production credentials live only on the `production` environment, so no build, test, or lint job in any workflow can resolve them — the credential and the approval move together. When people ask "how do you do manual approval in GitHub Actions?", environments with required reviewers is the whole answer; there is no separate approval step type.