Job Dependencies, needs, Concurrency, Cancellation, and Deployment Serialization: Core Concepts and Mental Model

1. The practical problem: capacity is not ordering

Suppose a repository has four jobs: lint, unit tests, package, and deploy. If the YAML lists them in that order, GitHub does not infer a pipeline. Jobs without dependencies are independently eligible and may run in parallel on different runners. A deployment that must happen only after successful validation therefore needs an explicit graph.

Now add a second workflow run while the first deployment is still changing the same target. More runners make the conflict easier to create. The problem is no longer “can GitHub execute both?” but “should these operations overlap, wait, or cancel?”

2. Causal model: DAG first, arbitration second

Start with job eligibility. needs creates dependency edges. Completed dependencies expose conclusions and outputs. Only then does a job that reaches a concurrency boundary compete for its concurrency group. Arbitration may let it run, make it pending, replace an older pending item, queue it, or cancel in-progress work depending on configuration.

flowchart TD
  A[Workflow run created] --> B[Independent jobs become eligible]
  B --> C1[lint]
  B --> C2[test]
  C1 --> D[needs fan-in: aggregate]
  C2 --> D
  D --> E{aggregate result / outputs}
  E -->|ready| F[deployment job reaches concurrency group]
  E -->|not ready| G[deployment skipped]
  F --> H{group arbitration}
  H -->|free| I[run critical section]
  H -->|busy + queue| J[pending / queued]
  H -->|cancel old| K[cancel in-progress work]
  I --> L[external side effect + evidence]
  K --> M[side effects already committed remain]

The DAG answers what must finish before this job is eligible? Concurrency answers which eligible jobs or runs may occupy this critical section at the same time? Cancellation answers what happens to older work when a replacement arrives? None of those mechanisms automatically reverses an external change already committed.

3. Name the states that must be observable

4. needs is an explicit DAG edge

Without needs, jobs are peers. With needs, a job waits for the listed direct dependencies. If a needed job fails or is skipped, the dependent job is skipped by default unless its own if explicitly allows continuation.

jobs:
  lint:
    runs-on: ubuntu-24.04
    steps:
      - run: echo "lint ok"

  test:
    runs-on: ubuntu-24.04
    steps:
      - run: echo "tests ok"

  aggregate:
    needs: [lint, test]
    runs-on: ubuntu-24.04
    steps:
      - run: echo "both direct dependencies succeeded"

This is a fan-out/fan-in graph: lint and test can run in parallel; aggregate waits for both.

5. needs exposes only direct dependencies

The needs context contains each direct dependency’s outputs and result. Results are success, failure, cancelled, or skipped. It does not recursively contain dependencies of dependencies.

aggregate:
  if: ${{ always() }}
  needs: [lint, test]
  runs-on: ubuntu-24.04
  steps:
    - shell: bash
      run: |
        printf 'lint=%s\n' '${{ needs.lint.result }}'
        printf 'test=%s\n' '${{ needs.test.result }}'

6. Concurrency is repository-wide mutual exclusion

A concurrency group is a repository-level key shared by jobs or workflow runs that declare the same resolved value. Group names are case-insensitive. Workflow-level concurrency arbitrates entire runs; job-level concurrency arbitrates only the job that reaches that boundary.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

This is a good pattern for stale CI on a branch: a newer run can replace older in-progress work. It is usually a bad default for an irreversible deployment, because a canceled deployment may already have changed the external target.

7. Pending replacement, queueing and cancellation are different policies

queue: max and cancel-in-progress: true are mutually exclusive. A queue is appropriate when each deployment must be observed and serialized. Cancellation is appropriate only when older work is genuinely disposable or has a safe compensation protocol.

8. Cancellation is a control signal, not rollback

When GitHub cancels a run, it re-evaluates conditions on running jobs and steps. Work whose condition remains true can continue; other work receives a cancellation signal and is eventually terminated. If an external API call already committed a release, database migration, DNS update, or fake target marker, process termination does not reverse it.

run A timeline
00:00 prepare
00:20 external target changed to revision A   <-- committed
00:25 run B arrives, cancels run A
00:26 runner process stops

external target is still revision A unless compensation changes it.

9. Read-only inspection before changing policy

Before adding a lock or cancellation rule, capture the current workflow revision and run graph. In GitHub UI or gh, record run ID/attempt/SHA, job IDs, conclusions, timestamps and whether overlapping runs currently exist. Do not cancel anything merely to “see what happens” in a production repository.

# Optional read-only inspection in an authorized repository.
gh run list --limit 10
gh run view RUN_ID --json databaseId,attempt,headSha,event,status,conclusion,jobs

Then state the delivery invariant in plain language, such as “only one deployment to staging may execute at a time, and accepted deployments must not be dropped.” That sentence determines the concurrency design.

Knowledge check

Official references and version notes

• GitHub Docs — workflow syntax: needs — explicit job dependencies, skip propagation and job-level conditions.
• GitHub Docs — needs context — direct-dependency results and outputs.
• GitHub Docs — control workflow/job concurrency — concurrency groups, cancellation, queue behavior and expression contexts.
• GitHub Docs — concurrency concepts — simultaneous execution, pending replacement and serialized queues.
• GitHub Docs — workflow cancellation reference — server condition re-evaluation, runner signals and forced termination.
• GitHub Docs — reusable workflow configuration — caller/called-workflow concurrency interaction.