Environments

The environments section configures deployment environments for GitHub Actions workflows. Environments provide deployment protection rules, reviewers, branch policies, and environment-specific variables.

Basic Configuration

name

string

required

The name of the environment. This will be referenced in workflows with environment: <name>. Names are automatically converted to lowercase.

environments:
  - name: production

Wait Timer

wait_timer

integer

default:"0"

The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).

environments:
  - name: production
    wait_timer: 30  # Wait 30 minutes before deployment

Reviewers

prevent_self_review

boolean

default:"false"

Whether a user who created the job is prevented from approving their own job.

environments:
  - name: production
    prevent_self_review: true

reviewers

array

The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. Only one of the required reviewers needs to approve the job for it to proceed.Important: Reviewers must be given explicit access to the repository as either a team or collaborator before they can be added as environment reviewers.

type

string

required

The type of reviewer. Can be:

User - An individual user
Team - A team

integer

required

The ID of the user or team who can review the deployment.To get IDs:

Team: gh api /orgs/<org>/teams/<team-slug> | jq .id
User: gh api /users/<username> | jq .id

environments:
  - name: production
    prevent_self_review: true
    reviewers:
      - type: Team
        id: 1234647
      - type: User
        id: 139262123

Deployment Branch Policy

deployment_branch_policy

object or null

The type of deployment branch policy for this environment. Set to null to allow all branches to deploy.

protected_branches

boolean

required

Whether only branches with branch protection rules can deploy to this environment.

If protected_branches is true, custom_branch_policies must be false
If protected_branches is false, custom_branch_policies must be an array

custom_branch_policies

array or boolean

Whether only branches that match the specified name patterns can deploy to this environment.

If custom_branch_policies is false, protected_branches must be true
If custom_branch_policies is an array, protected_branches must be false

Each policy can be:

A string (branch name pattern) - automatically treated as type: branch
An object with names array and type field

names

array

Array of branch or tag name patterns.

type

string

The type of ref. Can be:

branch - Branch patterns
tag - Tag patterns

Allow All Branches

environments:
  - name: development
    deployment_branch_policy: null

Protected Branches Only

environments:
  - name: production
    deployment_branch_policy:
      protected_branches: true
      custom_branch_policies: false

Custom Branch Patterns

environments:
  - name: production
    deployment_branch_policy:
      protected_branches: false
      custom_branch_policies:
        - names: ['main', 'release']
          type: branch
        - names: ['v*.*.*']
          type: tag

Simplified String Format

environments:
  - name: production
    deployment_branch_policy:
      protected_branches: false
      custom_branch_policies:
        - main
        - release/*

Environment Variables

variables

array

Environment variables that can be referenced in GitHub Actions workflows. Variable names are automatically converted to lowercase.

name

string

required

The name of the variable.

value

string

required

The value of the variable.

environments:
  - name: production
    variables:
      - name: API_URL
        value: https://api.example.com
      - name: MAX_RETRIES
        value: '3'

Deployment Protection Rules

deployment_protection_rules

array

Custom deployment protection rules provided by GitHub Apps.

app_id

integer

required

The GitHub App installation ID that provides the deployment protection rule.

integer

The ID of the deployment protection rule (used internally by Safe Settings).

environments:
  - name: production
    deployment_protection_rules:
      - app_id: 25112

Complete Examples

Development Environment

environments:
  - name: development
    wait_timer: 0
    deployment_branch_policy: null  # Allow all branches
    variables:
      - name: API_URL
        value: https://dev-api.example.com
      - name: DEBUG
        value: 'true'

Staging Environment

environments:
  - name: staging
    wait_timer: 5
    prevent_self_review: false
    reviewers:
      - type: Team
        id: 5678
    deployment_branch_policy:
      protected_branches: false
      custom_branch_policies:
        - names: ['main', 'develop']
          type: branch
    variables:
      - name: API_URL
        value: https://staging-api.example.com
      - name: LOG_LEVEL
        value: info

Production Environment

environments:
  - name: production
    wait_timer: 30
    prevent_self_review: true
    reviewers:
      - type: Team
        id: 1234647  # Platform team
      - type: User
        id: 139262123  # Lead engineer
    deployment_branch_policy:
      protected_branches: false
      custom_branch_policies:
        - names: ['main']
          type: branch
        - names: ['v*.*.*']
          type: tag
    deployment_protection_rules:
      - app_id: 25112  # Custom approval app
    variables:
      - name: API_URL
        value: https://api.example.com
      - name: LOG_LEVEL
        value: warn
      - name: MAX_CONNECTIONS
        value: '100'

Multiple Environments

teams:
  - name: platform-team
    permission: write

collaborators:
  - username: lead-engineer
    permission: write

environments:
  - name: development
    wait_timer: 0
    deployment_branch_policy: null
    variables:
      - name: ENV_NAME
        value: development
  
  - name: staging
    wait_timer: 5
    reviewers:
      - type: Team
        id: 1234647
    deployment_branch_policy:
      protected_branches: false
      custom_branch_policies:
        - names: ['main', 'develop']
          type: branch
    variables:
      - name: ENV_NAME
        value: staging
  
  - name: production
    wait_timer: 30
    prevent_self_review: true
    reviewers:
      - type: Team
        id: 1234647
      - type: User
        id: 139262123
    deployment_branch_policy:
      protected_branches: false
      custom_branch_policies:
        - names: ['main']
          type: branch
        - names: ['v*.*.*']
          type: tag
    variables:
      - name: ENV_NAME
        value: production

Important Notes

Reviewer Access

Reviewers must be given explicit access to the repository before they can be added as environment reviewers. Add them to the teams or collaborators section:

teams:
  - name: super-friends
    permission: write

collaborators:
  - username: KalEl
    permission: write

environments:
  - name: production
    reviewers:
      - type: Team
        id: 1234647  # ID for super-friends team
      - type: User
        id: 139262123  # ID for KalEl

Branch Policy Validation

You cannot set both protected_branches: true and provide custom_branch_policies
You must specify either protected_branches: true or provide custom_branch_policies
Setting deployment_branch_policy: null allows all branches to deploy

Variable Names

Environment variable names are converted to lowercase by Safe Settings
In your workflow, reference them as configured: ${{ vars.API_URL }}

Using Environments in Workflows

Once configured, reference the environment in your workflow:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: |
          echo "Deploying to ${{ vars.API_URL }}"
          # deployment steps

API Reference

For more details, see GitHub’s REST API documentation:

Get Started

Deployment

Configuration

Settings Reference

Advanced

Operations

Basic Configuration

Wait Timer

Reviewers

Deployment Branch Policy

Allow All Branches

Protected Branches Only

Custom Branch Patterns

Simplified String Format

Environment Variables

Deployment Protection Rules

Complete Examples

Development Environment

Staging Environment

Production Environment

Multiple Environments

Important Notes

Reviewer Access

Branch Policy Validation

Variable Names

Using Environments in Workflows

API Reference

Build docs developers (and LLMs) love

Get Started

Deployment

Configuration

Settings Reference

Advanced

Operations

​Basic Configuration

​Wait Timer

​Reviewers

​Deployment Branch Policy

​Allow All Branches

​Protected Branches Only

​Custom Branch Patterns

​Simplified String Format

​Environment Variables

​Deployment Protection Rules

​Complete Examples

​Development Environment

​Staging Environment

​Production Environment

​Multiple Environments

​Important Notes

​Reviewer Access

​Branch Policy Validation

​Variable Names

​Using Environments in Workflows

​API Reference

Build docs developers (and LLMs) love

Basic Configuration

Wait Timer

Reviewers

Deployment Branch Policy

Allow All Branches

Protected Branches Only

Custom Branch Patterns

Simplified String Format

Environment Variables

Deployment Protection Rules

Complete Examples

Development Environment

Staging Environment

Production Environment

Multiple Environments

Important Notes

Reviewer Access

Branch Policy Validation

Variable Names

Using Environments in Workflows

API Reference