GitHub Actions environment protection rules let you gate deployments to critical environments, forcing a manual approval step before code can proceed.
Let’s see it in action. Imagine we have a production environment that needs a human to sign off on any deployment.
name: Deploy to Production
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
environment: production # This is the key!
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Deploy to production
run: echo "Deploying to production..."
When this workflow runs, if the production environment has protection rules configured, the deployment won’t automatically proceed. Instead, it will pause at the deploy job, waiting for an approved user to click the "Approve" button in the GitHub UI.
The problem this solves is preventing accidental or unauthorized deployments to sensitive environments. By introducing a mandatory human checkpoint, you add a layer of safety, ensuring that only reviewed and accepted changes reach your production systems.
Internally, when a workflow attempts to deploy to an environment with protection rules, GitHub checks the configured rules. If a manual approval rule is present, the job is suspended. The designated approvers (users or teams) receive a notification and can then navigate to the specific workflow run in the GitHub UI to review the deployment and either approve or reject it.
The exact levers you control are within the environment’s settings in your GitHub repository. You can define:
- Deployment branches: Which branches are allowed to deploy to this environment.
- Wait timer: A grace period after which a deployment will fail if not approved.
- Required reviewers: Specific users or teams who must approve deployments.
- Custom branch protection rules: Integration with existing branch protection settings.
These rules are configured under your repository’s settings: Settings > Environments > [Your Environment Name]. You can create a new environment or modify an existing one. For instance, to set up manual approvals for the production environment, you would navigate to its settings and enable "Required reviewers," then add the specific users or teams responsible for approving production deployments.
The most surprising thing about these rules is that they don’t prevent the workflow run from starting; they only pause specific jobs that target protected environments. This means your CI steps (like building and testing) can still complete successfully, and you’ll only be blocked at the point of deployment, which is precisely what you want.
What most people don’t realize is that the environment keyword in your workflow file is what links the job to the protection rules defined in your repository settings. If you have rules set up for an environment, but the job doesn’t specify that environment using environment: environment-name, the rules will be bypassed for that specific job.
The next concept you’ll want to explore is using custom GitHub Actions for more complex deployment logic within these protected environments.