Jobs, Steps, Matrices, Containers, Service Containers, and Dependency Graphs: Configuration, Design Choices, and Tradeoffs

1. One job versus several isolated jobs

A single job is attractive when steps use the same workspace, installed tools, and permission context and the work is short enough that isolation adds little value. Multiple jobs become valuable when you need independent scheduling, different runners/containers, clearer policy boundaries, parallelism, or a release gate that should depend on separately visible evidence.

The cost of splitting is real: each GitHub-hosted job starts a fresh runner, so source must be checked out again and generated files must be transferred or reproduced. A job boundary should therefore express an architectural boundary, not merely make the YAML look organized.

2. Matrix dimensions versus explicit jobs

A matrix is best when the steps are structurally the same and only bounded parameters vary. Explicit jobs are clearer when lanes have different purpose, permissions, service dependencies, or failure policy. Forcing unrelated jobs into a clever matrix saves lines of YAML but hides intent.

Review the Cartesian product in code review. A matrix that begins as 2 × 2 can become 4 × 5 × 3 after “one more platform,” creating 60 jobs. GitHub’s 256-job matrix ceiling prevents unbounded expansion, but a workflow can become costly and slow long before the hard limit.

3. Complete coverage versus fast failure

fail-fast: true is a latency/resource optimization: once a non-tolerated cell fails, queued/in-progress siblings may be cancelled. fail-fast: false is an evidence policy: every cell is allowed to finish, which is valuable when platform-specific failures matter. Neither choice is universally correct.

continue-on-error should be rarer. It changes whether a failure is treated as fatal. Every tolerated cell needs an owner, reason, and expiration condition. Otherwise “experimental” becomes a permanent hole in release evidence.

4. Job container versus installing dependencies on the runner

A job container is not a security sandbox that makes untrusted code safe by itself. The underlying runner, mounted workspace, token permissions, and service/network access still matter.

5. Service container versus external test service

A service container is excellent for disposable databases/caches that can start per job, contain synthetic data, and be destroyed with the job. An external service is appropriate when tests require behavior that cannot be reproduced locally—managed identity, proprietary API, region semantics, or shared integration infrastructure—but then credentials, tenancy, cleanup, network latency, rate limits, and billing become part of the test design.

6. Outputs versus artifacts versus reproducible checkout

Do not use outputs as a file-transfer mechanism. Outputs are strings and are ideal for identifiers, digests, version numbers, or decisions. Workflow artifacts are designed to move files between jobs and preserve selected outputs after a run. Reproducible checkout is preferable when downstream work only needs repository source at an exact SHA.

# Documentation shape only: pin artifact actions to reviewed full commit SHAs in production.
- name: Upload generated files
  uses: actions/upload-artifact@<PINNED_FULL_COMMIT_SHA>
  with:
    name: build-output
    path: dist/

# In a dependent job:
- name: Download generated files
  uses: actions/download-artifact@<PINNED_FULL_COMMIT_SHA>
  with:
    name: build-output
    path: dist/

Artifacts have retention, storage, integrity, and sensitive-content implications covered deeply in Chapter 17. The design rule here is narrower: generated files do not teleport between jobs.

7. Plan, runner, registry, and deployment constraints

• Public GitHub.com: standard GitHub-hosted runners are currently free and unlimited, but concurrency and other Actions limits still apply.
• Private repositories: hosted-runner minutes/storage and concurrency depend on plan and may incur billing.
• Containers/services: GitHub-hosted jobs must use Ubuntu; self-hosted jobs require Linux plus Docker.
• Private container images: registry authentication creates a credential boundary; scope credentials minimally and never print them.
• GitHub Enterprise Server: use the runner model supported by the deployed GHES release; do not assume GitHub.com-hosted runner availability.

8. Worked decision table: choose the topology

The best design is the smallest topology that makes the required isolation and evidence explicit. Complexity should buy a concrete property.

9. Production policy examples

• Every cross-job generated file has an explicit artifact/package contract or is deterministically recreated.
• Every matrix declares an owner, dimensions, expected cell count, failure policy, and parallelism cap when resource pressure matters.
• Container image sources are approved; production-critical images are pinned by immutable digest where feasible.
• Service containers contain synthetic/non-sensitive data and expose only required ports.
• Tolerated failures are labeled experimental with an owner and removal criterion.
• Summary jobs report prerequisite results but do not transform failed required validation into a successful release signal.

10. Lesson summary

Job boundaries, matrix dimensions, containers, and services are architectural choices. Use one job for genuine shared execution state, multiple jobs for isolation/parallel evidence, matrices for bounded variations of one shape, job containers for controlled Linux user-space, and service containers for disposable job-local dependencies. Move metadata through outputs and files through artifacts or reproducible source/package boundaries.

Knowledge check

Further reading — current official GitHub sources

• GitHub Docs — Workflow syntax
• GitHub Docs — Using jobs in a workflow
• GitHub Docs — Running variations of jobs
• GitHub Docs — GitHub-hosted runners
• GitHub Docs — Running jobs in a container
• GitHub Docs — Docker service containers
• GitHub Docs — Store and share workflow data
• GitHub CLI — gh run view
• GitHub REST — Workflow jobs
• GitHub Docs — Actions limits
• GitHub Docs — Secure use reference