Workflow Files, YAML Structure, Jobs, Steps, and Actions: Configuration, Design Patterns, and Trade-Offs

1. The design question: what should be one schedulable unit?

A job is more than indentation. It is a runner allocation, environment boundary, permission scope, log group, retry unit, and potential parallelism unit. Splitting a workflow into jobs can improve isolation and make dependencies explicit, but every split also means another runner setup and an explicit strategy for moving data that cannot be recreated.

Conversely, putting everything into one giant job makes filesystem sharing easy but couples unrelated tasks to the same machine and failure path. The correct answer follows the delivery model, not a rule such as “one job per command” or “one job per workflow.”

2. One job versus multiple jobs

A useful heuristic is to split when trust, side effects, runner requirements, or failure ownership differ. Do not split only to make the YAML visually shorter.

3. run versus uses: ownership and dependency trade-offs

run is appropriate when the logic is small, repository-specific, and clearer as an explicit script. uses is appropriate when a reviewed reusable action owns a well-defined capability such as checkout or toolchain setup. But reuse introduces an executable dependency, so it carries version, provenance, runtime, and trust requirements.

For third-party code, full-SHA pinning is an immutable reference but not a substitute for source review. The repository owner, source, release process, requested credentials, network behavior, and update process still matter.

4. External action versus local action

An external action such as actions/checkout is fetched as a dependency according to its reference. A local action referenced as uses: ./.github/actions/example is part of your repository tree. On a hosted runner, that local repository content normally must be available in the workspace first, which means checkout is commonly required before invoking the local action.

Local actions can centralize repeated repository-specific logic, but they are still executable code and should have a clear interface. Chapter 17 will teach custom action implementation in depth; here the design lesson is simply that “local” changes the ownership/versioning boundary, not the need for review.

5. Workflow-level versus job-level versus step-level configuration

Put a setting at workflow scope only when it is genuinely a workflow-wide invariant. Put it at job scope when one job needs a different runner, permission set, environment, or default. Use step scope for exceptional shell/working-directory behavior.

permissions: {}

defaults:
  run:
    shell: bash

jobs:
  verify:
    permissions:
      contents: read
    runs-on: ubuntu-24.04
    defaults:
      run:
        working-directory: ./tools
    steps:
      - name: One step needs repository root
        working-directory: .
        run: pwd

The principle is least scope: broad defaults reduce repetition only when they do not hide meaningful differences. A production workflow should make privilege escalation and target changes conspicuous in review.

6. Stability: job IDs and check names can become external interfaces

Branch protection, dashboards, API consumers, or human runbooks may come to depend on job/check names. Refactoring identifiers is therefore not always cosmetic. Stable IDs and clear display names reduce accidental breakage, especially as workflows become reusable or governed organization-wide.

Keep machine-facing IDs concise and semantic. Keep human-facing names specific enough that a failed check can be understood without opening the YAML. Avoid auto-generated-looking names that make incident evidence ambiguous.

7. Readability versus abstraction

8. Worked scenario: build, test, and publish are not one trust boundary

Suppose a future pipeline has three concerns: compile source, run tests, and publish a release package. Compilation and tests need read-only repository access. Publication mutates an external registry and should run only for an authorized release event. A single job would make it easier to leak publication credentials into build steps and harder to rerun safely.

A stronger design is separate read-only build/test jobs plus a tightly gated publication job that depends on verified outputs. Chapter 02 does not implement package publication yet; the point is to recognize the future privilege boundary now. Job structure is how delivery policy becomes visible before credentials are added.

9. Decision checklist

• State: Does the next unit require the same ephemeral filesystem, or can inputs be recreated/transferred explicitly?
• Trust: Does one unit execute less-trusted code or need fewer privileges?
• Runner: Do units need different OS, architecture, hardware, or isolation?
• Failure: Should a reviewer be able to rerun one unit without repeating side effects?
• Evidence: Will logs/check names clearly identify the failed capability?
• Dependency: Is an action/reusable component worth its external code and update surface?
• Maintenance: Is configuration placed broadly because it is truly invariant, or only to save lines?

10. Production pattern and Chapter 02 boundary

The production pattern is not “more YAML.” It is a graph whose nodes align with trust, runner, side-effect, and recovery boundaries. Start explicit. Extract shared components only after their interface is understood. Grant permissions narrowly. Treat action references as dependencies. Keep stable names where external policy depends on them.

Knowledge check

Official references and version notes

• Understanding GitHub Actions — current definitions and execution relationships for workflows, jobs, steps, actions, and runners.
• Workflow syntax for GitHub Actions — authoritative workflow structure, jobs, steps, permissions, defaults, runners, and shell behavior.
• Setting default shell and working directory — current precedence and restrictions for workflow/job defaults.run.
• Using GitHub-hosted runners — job-to-runner isolation and filesystem sharing within a job.
• Secure use reference — current guidance to pin action dependencies to full-length commit SHAs and minimize privileges.
• Using pre-written building blocks — current action-reference options and immutable SHA guidance.
• Managing custom actions — current action release/reference practices; detailed custom-action construction is deferred to Chapter 17.