Working with Environments
1. Defining Environments
| Property | Description | Values |
|---|---|---|
| name | Name of the environment | production, staging |
| variables | Environment variables available to workflows | VAR1=value1 |
| secrets | Secrets available to workflows | SECRET1=secret_value |
| protection_rules | Rules to protect environment access | wait_timer, required_approvals |
Example: Environment Definition
name: production
variables:
API_URL: https://api.example.com
secrets:
API_KEY: ${{ secrets.API_KEY }}
protection_rules:
- wait_timer: 300
required_approvals: 2
2. Setting Environment Variables
| Variable | Value | Description |
|---|---|---|
| GITHUB_ENV | environment-file-path |
Path to the file where environment variables are written |
| GITHUB_OUTPUT | output-file-path |
Path to the file where outputs are written |
| GITHUB_STATE | state-file-path |
Path to the file where state variables are written |
Example: Setting Environment Variables in a Job
jobs:
example-job:
steps:
- name: Set environment variable
run: |
echo "MY_VAR=value" >> $GITHUB_ENV
Example: Using Environment Variables in a Workflow
jobs:
example-job:
steps:
- name: Use environment variable
run: echo "The value is $MY_VAR"
3. Configuring Protection Rules
| Rule Type | Description | Configuration | Notes |
|---|---|---|---|
| Wait for Approval | Requires manual approval before deployment | wait-for-review: true |
Can be configured per environment |
| Required Status Checks | Ensures specific checks pass before deployment | required-checks: [build, test] |
Supports GitHub Actions and external services |
| Deployment Branches | Limits deployment to specific branches | branches: [main, release] |
Can use regex patterns for branch matching |
| Tags | Restricts deployment to specific tags | tags: [v1.0.*, v2.*] |
Supports wildcard matching |
Example: Protection Rules Configuration
name: Deploy to Production
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: production
url: https://prod.example.com
protection_rules:
- wait_for_review: true
- required_checks:
- build
- test
- branches:
- main
Note: Protection rules are enforced at the environment level and can be overridden by job-level settings.
Warning: If a protection rule is not met, the deployment will be blocked and must be manually approved or corrected.
4. Setting Environment Secrets
| Property | Description | Values |
|---|---|---|
| name | Name of the secret | SECRET_NAME |
| value | Value of the secret (encrypted) | secret_value |
Example: Setting an Environment Secret
name: Set Environment Secret
on:
push:
branches:
- main
jobs:
set-secret:
runs-on: ubuntu-latest
steps:
- name: Set Secret
run: |
echo "SECRET_NAME=secret_value" >> $GITHUB_ENV
Note: Environment secrets are encrypted and can only be accessed within the scope of the environment.
Warning: Never store sensitive values directly in workflow files. Use GitHub's encrypted secrets instead.
5. Using Environment URLs
| Property | Description | Example |
|---|---|---|
| url | The URL of the environment | https://myapp.example.com |
| status | The status of the environment (e.g., available, unavailable) |
available |
Example: Accessing Environment URL in a Workflow
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: production
url: https://myapp.example.com
steps:
- name: Deploy to environment
run: |
echo "Deploying to URL: ${{ env.ENVIRONMENT_URL }}"
Note: The environment URL is only available when the environment has been configured with a URL in the GitHub UI or via API.
6. Configuring Branch Restrictions
| Setting | Description | Value |
|---|---|---|
| protected_branches | Branches that require protection rules | main, develop |
| required_status_checks | Checks that must pass before merging | ci/circleci, lint |
| required_pull_request_reviews | Reviews required before merging | true |
Example: Branch Protection Rule
name: Branch Protection
on:
push:
branches:
- main
jobs:
protect-branch:
runs-on: ubuntu-latest
steps:
- name: Setup GitHub CLI
uses: actions/setup-cli@v1
- name: Protect branch
run: |
gh api \
--method PUT \
-H "Accept: application/vnd.github+json" \
/repos/<owner>/<repo>/branches/<branch>/protection \
-f required_status_checks="ci/circleci,lint" \
-f required_pull_request_reviews=true
Note: Branch protection rules can be configured via the GitHub UI or API. The example above uses the
gh CLI to set protection rules.
7. Waiting for Deployment
GitHub Actions provides built-in support for waiting for deployments to complete before proceeding with subsequent workflow steps. This is particularly useful in deployment scenarios where you want to ensure that a deployment has successfully completed before running tests or other dependent actions.
| Option | Values | Description |
|---|---|---|
| environment | string |
Name of the environment to wait for. This must match an environment defined in your repository settings. |
| timeout-minutes | number |
Maximum time (in minutes) to wait for the deployment to complete. Defaults to 10 minutes. |
| wait-timeout | number |
Alternative parameter name for timeout in minutes. Same as timeout-minutes. |
Example: Waiting for a deployment to environment production
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy to production
uses: actions/deploy@v1
with:
environment: production
timeout-minutes: 15
Note: The
environment must be defined in your repository's settings under "Environments". If the environment does not exist, the workflow will fail.
Warning: If a deployment takes longer than the specified timeout, the workflow will fail. Ensure that your timeout value is sufficient for your deployment process.
8. Approving Deployments
Approving deployments in GitHub Actions allows you to control when and how workflows deploy to specific environments. This feature is particularly useful for production deployments where you want to ensure manual approval before any deployment occurs.
| Property | Description | Default |
|---|---|---|
| environment | Name of the environment to deploy to | None |
| approval | Configuration for deployment approval | None |
Example: Approving Deployments to Production
name: Deploy to Production
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: production
url: https://prod.example.com
steps:
- name: Deploy to Production
run: |
echo "Deploying to production environment"
Note: When an environment is configured with approval, any workflow that references it will pause until a user with appropriate permissions approves the deployment.
Example: Configuring Approval with Conditions
name: Deploy with Approval
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: staging
approval:
required: true
wait_interval: 300
steps:
- name: Deploy to Staging
run: |
echo "Deploying to staging environment"
Warning: If the environment does not exist, GitHub will create it automatically. Ensure that environments are properly configured to avoid unintended deployments.
9. Tracking Deployment Status
Example: Using GitHub Actions to Track Deployment Status
name: Track Deployment Status
on:
deployment:
branches:
- main
jobs:
track-deployment:
runs-on: ubuntu-latest
steps:
- name: Check Deployment Status
run: |
echo "Deployment ID: ${{ github.run_id }}"
echo "Environment: ${{ github.event.deployment.environment }}"
| Property | Description | Value |
|---|---|---|
| github.event.deployment.id | Unique identifier for the deployment | ${{ github.event.deployment.id }} |
| github.event.deployment.environment | Name of the environment where deployment occurred | ${{ github.event.deployment.environment }} |
| github.event.deployment.status | Current status of the deployment (success, failure, pending) | ${{ github.event.deployment.status }} |
Note: The deployment event is triggered when a deployment is created or updated in GitHub.
Warning: Ensure that the deployment environment is properly configured to receive status updates.
10. Using Environment in Conditions
| Condition | Description | Usage |
|---|---|---|
| github.event_name | Name of the event that triggered the workflow | github.event_name == 'push' |
| github.ref | Ref that triggered the workflow | github.ref == 'refs/heads/main' |
| github.actor | User who triggered the workflow | github.actor == 'octocat' |
| github.repository | Full name of the repository | github.repository == 'octocat/Hello-World' |
| github.workflow | Name of the workflow | github.workflow == 'CI' |
| github.run_id | Unique identifier for the workflow run | github.run_id == '123456789' |
| github.run_number | Run number of the workflow | github.run_number > 100 |
| github.event | Full event payload | github.event.inputs.my_input == 'value' |
Example: Using environment in conditions
on:
push:
branches:
- main
jobs:
deploy:
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- name: Deploy to production
run: echo "Deploying to production environment"
Note: The
if condition is evaluated before the job runs, and can use any of the github context variables.
11. Reviewing Deployment History
| Field | Description | Example |
|---|---|---|
| deployment_id | Unique identifier for the deployment | 123456 |
| environment | Name of the environment | production |
| status | Current status of the deployment (success, failure, pending) | success |
| created_at | Timestamp when the deployment was created | 2025-04-01T10:00:00Z |
| updated_at | Timestamp when the deployment was last updated | 2025-04-01T10:05:00Z |
Example: Fetch Deployment History
const { GitHub } = require("@actions/github");
async function getDeploymentHistory() {
const github = new GitHub(process.env.GITHUB_TOKEN);
const { data } = await github.rest.repos.listDeployments({
owner: "octocat",
repo: "Hello-World",
environment: "production"
});
console.log(data);
}
getDeploymentHistory();
Note: Deployment history can be accessed via the GitHub API or through the GitHub UI under
Settings > Environments.
12. Deleting Environments
| Property | Description | Notes |
|---|---|---|
| environment.name | Name of the environment to delete | Required field |
| environment.id | Unique identifier for the environment | Optional if name is provided |
Example: Delete Environment by Name
name: Delete Environment
on:
workflow_dispatch: {}
jobs:
delete-env:
runs-on: ubuntu-latest
steps:
- name: Delete Environment
uses: actions/delete-package@v1
with:
environment-name: "staging"
Note: Deleting an environment will remove all associated secrets and variables. Ensure backups or migration plans are in place before deletion.