Manual Approval Gates: Controlling Production Deployments

Previously in this course, we covered Environment-Specific Secrets: Mastering Secure CI/CD Deployments to isolate our configuration data. Now that your secrets are locked down, it’s time to address a fundamental safety requirement: preventing accidental or premature code releases to your live environment.

In a fully automated CI/CD pipeline, the goal is often "push to deploy." However, shipping directly to production without a final sanity check can be risky. Manual approval gates provide a "human-in-the-loop" mechanism that pauses your deployment until an authorized person verifies the release.

Why Use Manual Approval Gates?

While we strive for high levels of automation, production environments are high-stakes. Manual gates serve as a final circuit breaker. They allow you to:

• Verify staging results: Ensure that smoke tests passed in Staging Environments: Mastering Deployment Targets in CI/CD before shipping to production.
• Coordinate releases: Sync software deployments with marketing launches or maintenance windows.
• Prevent "Fat Finger" deployments: Ensure that a rogue commit or a merged PR doesn't immediately roll out to your customers without oversight.

How GitHub Environments Work

GitHub Environments act as a logical grouping for your infrastructure. More importantly, they allow you to attach Protection Rules to specific targets (like production).

When a job references an environment with a "Required Reviewers" rule, GitHub Actions automatically pauses the workflow execution at the start of that job. It sends notifications to the designated users or teams, waiting for an explicit "Approve" or "Reject" action from the GitHub UI.

Worked Example: Adding a Production Gate

To set this up, we need to create the environment in GitHub and then reference it in our YAML workflow.

Step 1: Configure the Environment

1. Navigate to your repository on GitHub.
2. Go to Settings > Environments.
3. Click New environment and name it production.
4. Check the Required reviewers box.
5. Select yourself or your team as the reviewer.
6. Click Save protection rules.

Step 2: Reference the Environment in YAML

Now, update your .github/workflows/deploy.yml to use this environment for the production job.

YAML
jobs:
  deploy-to-prod:
    runs-on: ubuntu-latest
    environment: production  # This triggers the manual gate
    needs: [test, deploy-to-staging]
    steps:
      - name: Deploy to Production
        run: ./scripts/deploy.sh --target=production

When this job triggers, GitHub will hold the deploy-to-prod job in a "Waiting" state. You will see a button in your Actions run summary that says Review deployments. Only after you click "Approve" will the job proceed to run your deployment script.

Hands-on Exercise

1. Define your environment: Create a production environment in your repository settings as shown above.
2. Update your workflow: Add the environment: production line to your existing production deployment job.
3. Trigger a run: Push a change to your main branch.
4. Observe the gate: Navigate to the Actions tab. You will see the pipeline run, pause at the deployment job, and wait for your input. Click the "Review" button to approve the deployment and watch the final steps complete.

Common Pitfalls

• Forgetting to define the environment: If you reference an environment in your YAML that hasn't been created in GitHub settings, the pipeline will fail immediately with a "resource not found" error.
• Over-using gates: Don't put manual gates on every single job. This defeats the purpose of Continuous Delivery. Reserve them for environments that directly impact end-users.
• Reviewer lockout: If you assign a specific user (e.g., a former employee) as the only reviewer, your pipeline will be stuck indefinitely if they leave the team. Always assign a GitHub Team as a reviewer rather than an individual to prevent this.

Frequently Asked Questions

Does the manual gate stop the entire pipeline? No, it only halts the specific job referencing that environment. Upstream jobs (like tests) will finish, but the downstream deployment job remains pending.

Can I reject a deployment? Yes. If you click "Reject," the deployment job is cancelled, and the pipeline status will be marked as failed.

Is this feature available for free? Manual approval gates are available for public repositories and private repositories on GitHub Pro, Team, and Enterprise plans.

Recap

We’ve added a critical layer of control to our release process. By using GitHub Environments and "Required Reviewers," we’ve moved from blind automation to informed, manual oversight for our production deployments. You now have the power to decide exactly when code hits your live users, balancing speed with necessary caution.

Up next: Production Deployment — we will refine the deployment job to ensure it handles failures gracefully and integrates with our production infrastructure.