GitHub Actions

Why this matters

Checks are the gatekeeper on every pull request, and when one fails the merge button locks. Usually the cause is your change and the fix takes a minute, if you can find it. This lesson is about reading the result; Section 14 is about the ideas and writing the file.

The vocabulary

Workflow files live in .github/workflows/, one file per workflow, and they are part of the repository, so you can read them without asking anyone.

Where you see it

Statuses are success, failure, cancelled, skipped, queued and in progress. A check can also be neutral, which does not block a merge.

Reading a failure

Four steps, and the third is where people give up too early.

1. Open the failing job, from the pull request's Checks tab or the Actions tab. The summary only tells you which job failed.
2. Find the failed step. Steps are collapsible; the failed one is expanded and marked. Everything above it succeeded.
3. Read upwards from the end of that step, not the last line of the log. The final line is often Process completed with exit code 1, which says only that something failed. The useful line is above it and usually names a file and a line number.
4. Match it to your change. If it names a file you touched, it is yours. If not, check whether the same workflow fails on main before assuming you broke it.

A Markdown lint failure, the one a documentation contributor meets most, looks like this:

docs/getting-started.md:31 MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]
Error: Process completed with exit code 1

File, line, rule, expectation. Fix that line, commit, push; the workflow runs again by itself.

Re-running

Re-run jobs offers all jobs or only the failed ones, and Re-run with debug logging adds verbose output. Re-running is right when the failure was infrastructure: a timeout, a runner problem, a network error fetching a dependency. It is wrong when the log names your file, because the same code fails the same way.

A job that fails intermittently on unchanged code is flaky and deserves an issue rather than a habit of re-running.

Reading a workflow file

name: CI

on:
  push:
  pull_request:

jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m unittest discover -s tests -v

  lint-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx --yes markdownlint-cli "**/*.md" --ignore node_modules

Five things to recognize:

• on is the event list: this runs on every push and every pull request.
• jobs names the jobs; tests and lint-docs run in parallel.
• runs-on is the runner's operating system.
• uses pulls in someone else's action, pinned to a version.
• run is a command. You can run these yourself, locally, before pushing, which is the best way to avoid red checks.

That last point is worth acting on: npx markdownlint-cli "**/*.md" takes ten seconds locally and catches what the workflow would catch ten minutes later.

Secrets and permissions, briefly

Workflows read secrets from Settings → Secrets and variables → Actions, referenced as ${{ secrets.NAME }}. GitHub redacts them from logs, but two facts matter to a contributor:

• Secrets are not passed to workflows triggered by a pull request from a fork, which is why a fork's checks sometimes skip a job.
• Anyone who can change a workflow file can make it print what it can read, which is why workflow changes attract careful review.

How to do it

$ python3 -m unittest discover -s tests -v
$ npx --yes markdownlint-cli "**/*.md" --ignore node_modules

Common mistakes

• Reading only the last line. Process completed with exit code 1 is the symptom.
• Re-running a real failure. The same code fails the same way.
• Assuming red means you broke it. Check whether main is red too.
• Not running the workflow's own commands locally. They are written down in the file.
• Pushing repeatedly to see whether it passes, which costs minutes and clutters the pull request.