GitHub Actions Deployments: Environments, Active Status, and Protection Rules

How GitHub deployment tracking works

GitHub Deployments are first-class objects: when a workflow deploys to an environment, it creates a deployment record associated with that commit and environment. GitHub tracks the status (pending, in_progress, success, failure) and marks the latest successful deployment as active.

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production   # creates/updates a deployment for this environment
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        run: ./scripts/deploy.sh
      # GitHub automatically creates a deployment record and marks it active on success

The environment: key in a job does three things:

1. Creates a deployment record when the job starts
2. Sets the deployment status to success or failure when the job completes
3. Makes the deployment the active one for that environment on success

Branch protection with required deployments

In GitHub settings, environment deployment protection rules can gate merges:

# Branch protection rule (configured in GitHub UI):
# Require deployments to succeed before merging → staging

# Your PR's workflow must deploy to 'staging' successfully
# AND that deployment must be the 'active' one

When multiple PRs are open and all deploy to staging:

• PR-1 deploys at 10:00 → staging active deployment = PR-1
• PR-2 deploys at 10:05 → staging active deployment = PR-2 (PR-1 is superseded)
• PR-1 cannot merge — its deployment is no longer active

To make PR-1 mergeable again: re-trigger its deployment workflow (push a commit, re-run the job, or trigger via API).

Dynamic environments: per-PR isolation

The clean solution is naming environments after the PR or branch:

name: Deploy PR

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: staging-pr-${{ github.event.pull_request.number }}
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to PR environment
        run: |
          ./scripts/deploy.sh \
            --env "pr-${{ github.event.pull_request.number }}" \
            --url "https://pr-${{ github.event.pull_request.number }}.staging.example.com"
      - name: Set deployment URL
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.repos.createDeploymentStatus({
              owner: context.repo.owner,
              repo: context.repo.repo,
              deployment_id: context.payload.deployment.id,
              state: 'success',
              environment_url: 'https://pr-${{ github.event.pull_request.number }}.staging.example.com'
            })

GitHub creates the staging-pr-42 environment automatically when the workflow runs. Each PR gets its own deployment record and active status — no conflicts.

Caveat: automatically created environments don't inherit deployment protection rules or secrets configured on the base staging environment. You must either:

1. Configure secrets and rules on each dynamic environment (not scalable)
2. Store environment-specific secrets elsewhere (Vault, AWS Secrets Manager) and inject them at deploy time
3. Accept that dynamic environments have no protection rules (appropriate for preview/review deployments, not for gating production)

steps:
  - name: Create GitHub deployment
    id: create-deployment
    uses: actions/github-script@v7
    with:
      script: |
        const deployment = await github.rest.repos.createDeployment({
          owner: context.repo.owner,
          repo: context.repo.repo,
          ref: context.sha,
          environment: 'production',
          auto_merge: false,
          required_contexts: []   # skip status check requirements
        });
        core.setOutput('deployment-id', deployment.data.id);

  - name: Deploy
    run: ./scripts/deploy.sh

  - name: Update deployment status
    if: always()
    uses: actions/github-script@v7
    with:
      script: |
        await github.rest.repos.createDeploymentStatus({
          owner: context.repo.owner,
          repo: context.repo.repo,
          deployment_id: ${{ steps.create-deployment.outputs.deployment-id }},
          state: '${{ job.status == "success" && "success" || "failure" }}',
          environment_url: 'https://production.example.com'
        });