Required reviewers and the wait timer — the human gate that buys the team five minutes

Required reviewers and the wait timer are the human side of the protected environment’s gate. Branch restriction is the source side; reviewers and the timer are the judgement side. Together they answer two different questions: is the right code being deployed, and is the deploy being approved by a human who had time to think? This lesson covers both rules and the failure mode each one catches.

Required reviewers - users and teams

A protected environment on GitHub can require approval from named users, named teams, or both. The reviewer list lives in the platform configuration; the workflow declares only the target environment. The real command:

gh environment edit production \
  --required-reviewers user:alice,bob,team:platform-sre

The command adds three entries: two named users and one team. The team is expanded at approval time - any member of the team can satisfy the approval requirement, but the audit record shows which individual actually clicked Approve.

gh environment view production

The view subcommand lists the configured reviewer pool. The team entry shows the team’s slug; the platform expands it when an approval is requested.

The wait timer - the cheapest safety mechanism

The wait timer is a minimum delay between the last required-reviewer approval and the deploy job starting. The real command:

gh environment edit production --wait-timer 5

The argument is in minutes. The platform records three timestamps for every gated deploy: approval time, timer expiry, and deploy start. A typical production timer is five to fifteen minutes - long enough for a hasty approval to be noticed and revoked, short enough not to block the deploy during an incident.

The timer is the cheapest safety mechanism in the gate because it costs the team only the configured time and requires no extra reviewer pool. It catches the approval made in haste, the engineer who was not yet at their desk, the rotation about to change.

flowchart LR
    A["All reviewers approved"] --> B["Start wait timer"]
    B --> C["Timer expires"]
    C --> D["Job runs"]
    B -. "Revoke possible" .-> E["Reviewer revokes"]
    E --> X["Job cancelled"]

The cooling-off window is between approval and apply. During that window, the platform permits a reviewer to revoke the approval. Once the timer expires, the deploy proceeds.

What the timer catches that reviewers do not

Required reviewers catch the bad change: a reviewer who reads the diff, recognises a problem, and rejects. The wait timer catches the hasty approval: a reviewer who clicked Approve without reading, or who was asleep when they clicked. The two failure modes are different and require different mechanisms. A pool of attentive reviewers is no protection against a reviewer who approves in three seconds; a wait timer with inattentive reviewers is no protection against a bad change that everyone approved. The production discipline is to require both.

Production discipline

1. Name reviewers by team. The team is the source of truth for membership.
2. Set a non-zero wait timer for production. Five minutes is a typical starting point.
3. Audit the timer quarterly. A zero timer is a silent regression.
4. Read the audit trail after every gated deploy. Approval time, timer expiry, and deploy start should form a credible sequence.

Cross-course references

• This course, Part LVII-03 (Protected environments and required reviewers) introduces the three rules.
• This course, Part LVII-06 (Approval fatigue and bypass risks) covers the human-behaviour failure mode.
• This course, Part XCI-04 (Ephemeral per-job credentials) covers the deployment identity the reviewers are gating.

Quiz