Skip to main content

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.

Was this article helpful?