Job Dependencies, needs, Concurrency, Cancellation, and Deployment Serialization: Configuration, Design Patterns, and Trade-Offs

1. Parallelism versus dependency

A dependency is justified by a causal requirement: one job needs a prior job’s result/output or must not start until that job finishes. If two checks only inspect the same revision independently, adding needs creates latency without adding correctness.

2. Workflow-level versus job-level concurrency

Workflow-level concurrency blocks or cancels the entire run. That is appropriate when the whole run is stale or conflicts with another run. Job-level concurrency is narrower: validation can run in parallel while only a deployment, migration, publication or other critical section is serialized.

# Narrow lock: expensive CI remains parallel; only staging mutation is serialized.
jobs:
  deploy_staging:
    concurrency:
      group: deploy-staging
      queue: max

Narrow locks usually improve feedback latency and runner utilization while keeping the actual external invariant protected.

3. Cancel-old versus queue

Even a FIFO concurrency queue is not a substitute for an external optimistic-lock/version check when target state can also be changed outside GitHub Actions.

4. One global lock versus target-scoped locks

group: production serializes everything that uses that key. A more precise key often includes workflow, application and target:

concurrency:
  group: deploy-${{ github.repository }}-${{ inputs.service }}-${{ inputs.environment }}
  queue: max

Do not include high-cardinality values such as github.run_id when you intend mutual exclusion: a unique group disables sharing. Conversely, do not omit the workflow/application dimension if unrelated workflows could then cancel or block one another.

5. Concurrency and environments solve different problems

A concurrency group provides mutual exclusion. A GitHub environment can add reviewers, secrets/variables and deployment protections depending on repository plan/configuration. Neither implies the other. A deployment can be approved yet still race another deployment unless serialization exists; a serialized deployment can still be unauthorized if environment governance is missing.

6. Cleanup: evidence-first, privilege-last

There are three distinct “cleanup” categories:

• read-only evidence finalization — summaries/log correlation; may use always() if it cannot mutate external state.
• ephemeral local cleanup — removing temp files on the current disposable runner; bounded and low privilege.
• external compensation/revocation — cloud resources, deployments, credentials; should be explicit, authorized and cancellation-aware.

A blanket if: always() on a privileged external cleanup job can keep destructive work running after cancellation. Prefer explicit conditions such as failure(), cancelled(), target guards and idempotent external APIs, and document whether compensation is safe to repeat.

7. Reusable workflow concurrency can cancel its caller

Called workflows see the caller workflow name through github.workflow. If both caller and called workflow derive the same group from that context and set cancel-in-progress: true, the called workflow can enter the same group and cancel the caller that invoked it.

# Safer namespace for a called deployment workflow.
concurrency:
  group: reusable-deploy-${{ inputs.environment }}
  queue: max

Treat the concurrency key as part of a reusable workflow’s public interface. Document who else uses the group and what cancellation/queue contract callers should expect.

8. Worked decision table

9. Trade-offs to document

• Maintainability: stable group naming and explicit DAGs are easier to review than hidden shell polling.
• Least privilege: put credentials only in the serialized mutation job, not upstream parallel checks.
• Portability: GitHub concurrency governs GitHub runs, not changes performed by other CI/CD systems.
• Auditability: record resolved group key, run IDs and target state.
• Latency/cost: over-broad locks leave runners idle and lengthen queues.
• Rollback: cancellation is not rollback; compensation must be designed at the external target layer.

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.