A GitHub Actions environment is a named deployment context attached to a job. It maps a target such as staging or production to the process required to reach it, including protection rules, wait timers, approvals, and protected secrets. This preserves necessary controls while automating deployment flow and making release progress visible. section 1.2 section 9.2
Declare an environment in the job definition. Referencing a name that does not already exist creates the environment automatically. A job is tied to one environment; deploying through several environments therefore requires separate jobs. An optional URL appears in workflow reports and visualizations, and can be populated from a deployment step output. section 9.2.1
Attach a staging deployment job
Use an environment name to place the deployment under staging controls. Set its URL from the deployment step so operators can open the deployed application directly from workflow reporting. section 9.2.1
Listing 9.5 Referencing an environment
deploy:
runs-on: ubuntu-latest
needs: build
environment:
name: 'staging'
url: ${{ steps.deploy-to-webapp.outputs.webapp-url }}
This job definition shows the environment name and a URL sourced from the deploy-to-webapp step output. section 9.2.1
Use environments to make delivery controlled and repeatable:
- Require one or more manual approvers before a deployment job starts. Approval is recorded, providing deployment traceability for governed delivery processes. section 9.2.2
- Configure a wait period before a job starts when a staged or gradually ramped release needs a delay. section 9.2.2
- Override variables by environment so one deployment workflow can target different locations with the same variable names and procedure. section 9.2.3
- Use the same controls for on-premises deployments running on self-hosted runners when hosted runners cannot reach private machines. section 9.3.1
Environment-specific variables reduce drift: deploy staging and production through the same workflow while changing only target values. Combine environment gates with versioned release artifacts and deployment validation so each transition remains traceable and promotion proceeds only after checks succeed. section 9.2.3 section 9.4
