GitHub Actions Concurrency Experiment

This repository demonstrates the difference between workflow-level and job-level concurrency in GitHub Actions when using matrix strategies with environment protection rules.

Problem Statement

When using a matrix strategy to deploy to multiple environments (dev → test → prod) with environment protection rules requiring manual approval, workflow-level concurrency can cause unexpected blocking behavior:

1. First workflow runs, deploys to dev, waits for test approval
2. Second workflow run gets queued and shows as "pending" because the first workflow is still active
3. The entire second workflow is blocked, even though dev deployment could proceed independently

Test Setup

Environments

This repo uses three GitHub environments:

• env_dev - No protection rules (auto-deploys)
• env_test - Manual approval required
• env_prod - Manual approval required

Test Workflows

1. workflow-concurrency.yml - Current problematic setup

   • Uses workflow-level concurrency: group: build-${{ github.head_ref || github.ref_name }}
   • All jobs share the same concurrency group

2. job-concurrency.yml - Proposed solution

   • Uses job-level concurrency: group: deploy-${{ matrix.environment }}-${{ github.head_ref || github.ref_name }}
   • Each environment has its own concurrency group

How to Test

Prerequisites

1. Set up environment protection rules:
   • Go to repo Settings → Environments
   • For env_test and env_prod: Enable "Required reviewers" and add yourself

Test Scenario 1: Workflow-Level Concurrency Issue

1. Disable the job-concurrency workflow (add # before name:)
2. Make a change to test-file.txt and push to main
3. Observe the workflow run:
   • dev deployment completes
   • test deployment waits for approval (yellow clock icon)
4. While the first workflow is still pending approval, make another change to test-file.txt and push
5. Expected Issue: The second workflow run will show as "pending" and won't start until the first completes

Test Scenario 2: Job-Level Concurrency Solution

1. Disable the workflow-concurrency workflow
2. Enable the job-concurrency workflow
3. Repeat the same test steps as above
4. Expected Result:
   • First workflow: dev completes, test waits for approval
   • Second workflow: New dev deployment starts immediately, test waits in its own queue

Expected Behavior Comparison

Scenario	Workflow-Level Concurrency	Job-Level Concurrency
First push	✅ dev deploys, test waits	✅ dev deploys, test waits
Second push while test pending	❌ Entire workflow queued	✅ dev deploys immediately, test queued per environment
Third push	❌ Still queued	✅ dev replaces previous pending, test maintains queue

Key Insights

Workflow-Level Concurrency

• Pro: Simple configuration
• Con: Entire workflow shares concurrency group
• Issue: One pending job blocks all subsequent workflow runs

Job-Level Concurrency

• Pro: Fine-grained control per environment
• Pro: Independent concurrency groups per deployment target
• Result: Environments can deploy independently while respecting their own approval workflows

Files

• .github/workflows/workflow-concurrency.yml - Demonstrates the problem
• .github/workflows/job-concurrency.yml - Demonstrates the solution
• test-file.txt - Simple file to modify for triggering workflows
• README.md - This documentation

Concurrency Group Examples

Workflow-Level

concurrency:
  group: build-main
  cancel-in-progress: false

All jobs in workflow share this group.

Job-Level

concurrency:
  group: deploy-dev-main    # dev environment
  group: deploy-test-main   # test environment  
  group: deploy-prod-main   # prod environment

Each environment deployment has independent concurrency control.

Conclusion

Job-level concurrency provides the granular control needed for multi-environment deployments with approval workflows, preventing blocking behavior while maintaining proper deployment sequencing per environment.