Events, jobs, and runners

Automate a check you already understand

Continuous integration regularly checks changes as they join shared code. A CI service executes defined commands and reports their results. It does not decide what correctness means for your program; that comes from the checks you choose. GitHub Actions is the primary implementation here. Jenkins and GitLab CI are later comparisons, and Argo CD follows Kubernetes in Advanced DevOps.

A workflow is a YAML file under .github/workflows/. An event, such as a pull request or manual dispatch, triggers it. A job groups work on a runner, the machine executing it. Steps in a job run in sequence; separate jobs may run concurrently unless dependencies constrain them. A step uses either a shell command (run) or a reusable action (uses).

Read a complete first workflow

In a practice repository, save .github/workflows/anatomy.yml:

name: Study workflow anatomy
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  inspect:
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    steps:
      - name: Show runner operating system
        run: uname -s
  followup:
    needs: inspect
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    steps:
      - name: Show the dependency completed
        run: echo 'The inspect job succeeded.'

workflow_dispatch supplies a manual trigger when the workflow is available on the default branch and Actions is enabled. contents: read limits the workflow's repository token permissions. runs-on chooses a runner image; it is not a deployment target. A timeout limits how long a job may run. needs: inspect makes the second job depend on the first job's success under the default behavior.

This workflow deliberately needs no checkout because it only inspects the runner and prints a message. Repository files are not automatically in a fresh hosted runner's working directory. The later lab adds checkout and a Python runtime before using your actual code.

Predict a failure before running it

Draw two boxes with an arrow from inspect to followup. If the first command exits nonzero, the dependent job should normally be skipped. If you remove needs, textual placement below the first job does not guarantee ordering. A condition can alter failure behavior, so read conditions along with the graph.

Separate jobs do not automatically share files, even when one waits for another. Use explicit outputs for small values and artifact upload/download for files. A matrix repeats a job with chosen values, such as supported Python versions; it increases coverage and resource use, not guaranteed speed.

Observe the execution context

If you choose to run this in an owned practice repository, use its normal commit workflow, then open the Actions run. Check the event, source revision, job sequence, runner, logs, and conclusion. Expect Linux from the first job and the displayed message from the second. A local YAML file alone is a prepared workflow, not evidence of a hosted run. Usage depends on the account's plan and allowances.

A self-hosted runner is a machine you manage. Untrusted code running on a persistent host can affect other files or credentials on it. The introductory workflow needs no deployment secrets or privileged host access. Reusable actions are executable dependencies; review and pin their immutable revisions before relying on them.

Checkpoint: why can a job fail to find capacity.py? Checkout may be missing, or the working directory may be wrong. Why does needs not transfer a built file? It describes order, not storage. Next, choose checks that fail for meaningful defects.

References: Actions concepts↗, jobs↗, workflow syntax↗, and secure action use↗.