← All cheatsheets

CI/CD

GitHub Actions — workflows, triggers, and debugging failed runs

Author, trigger, and debug GitHub Actions workflows — from the five YAML building blocks (on, jobs, uses, matrix, secrets) to reading a failed run with the gh CLI and driving it back to green.

Docs-checkedgithub-actionsci-cdworkflowsyamlsecrets

Quick reference — reach for these first

on: triggeron: [push, pull_request, workflow_dispatch]When the workflow runs; add branches:/paths: to narrow the match.
job + runs-onjobs: { build: { runs-on: ubuntu-latest } }Each job gets a fresh runner VM; its steps share that filesystem.
uses: action- uses: actions/checkout@v4Run a prebuilt, version-pinned action — contrast with run: for shell.
matrixstrategy: { matrix: { node: [20, 22] } }Fan one job into parallel variants; one combo per value set.
secrets${{ secrets.NPM_TOKEN }}Inject encrypted secrets; GITHUB_TOKEN is auto-provided per run.

How a workflow run is wired together

GitHub Actions execution modelAn event triggers a workflow file under .github/workflows; the workflow runs jobs on runner VMs, ordered by needs, each job built from steps that use actions or run shell, with secrets and GITHUB_TOKEN injected under least-privilege permissions.Events (on:)pushpull_requestworkflow_dispatchschedule (cron)+ branch / path filters.github/workflows/ci.ymlbuildruns-on:ubuntu-latesttestmatrix:node 20,22needs: [build]secrets + GITHUB_TOKEN${{ secrets.NPM_TOKEN }}permissions: { contents: read }fork PRs: no secretsSteps (job: test)- uses: actions/checkout@v4- uses: actions/setup-node@v4- run: npm ci && npm testOutputsupload-artifact / download-artifactcache@v4 (restore by key)debug: gh run view --log-failed

Text equivalent: Flow left to right: Events (push, pull_request, workflow_dispatch, schedule, plus branch and path filters) trigger the workflow file .github/workflows/ci.yml. Inside it a build job runs on ubuntu-latest and a test job declares needs on build and a matrix over node 20 and 22. A dashed box shows secrets and GITHUB_TOKEN injected under least-privilege permissions, noting fork PRs get no secrets. The steps of the test job use checkout and setup-node actions and run npm test, producing outputs: uploaded artifacts, a restored cache keyed by lockfile, and the gh run view --log-failed debug entry point.

Common tasks

Task · Command · What to check

TaskCommandWhat to check
Scaffold a workflow filemkdir -p .github/workflows && EDITOR .github/workflows/ci.ymlFile lives under .github/workflows/ with a .yml or .yaml extension.
Validate YAML before pushingyamllint .github/workflows/ci.ymlNo syntax errors; indentation is spaces, not tabs.
Trigger manually (workflow_dispatch)gh workflow run ci.yml --ref BRANCHA new run appears in gh run list within seconds (needs on: workflow_dispatch).
List recent runsgh run list --workflow ci.yml --limit 10Status column shows completed / in_progress / queued per run.
Watch a run livegh run watch RUN_IDSteps stream to the terminal and the command exits on completion.
Read only the failing logsgh run view RUN_ID --log-failedShows just the failed step's output, not the entire run log.
Order jobs with needsneeds: [build]The dependent job starts only after build completes successfully.
Cache dependenciesuses: actions/cache@v4 (key: npm-${{ hashFiles('**/package-lock.json') }})A later run logs 'Cache restored from key'.
Upload a build artifactuses: actions/upload-artifact@v4 (name: dist, path: dist/)Artifact appears in the run summary and is downloadable.
Scope GITHUB_TOKEN (least privilege)permissions: { contents: read }Token is read-only; a write operation returns 403 until a scope is granted.
Prevent overlapping runsconcurrency: { group: ${{ github.ref }}, cancel-in-progress: true }A new push cancels the prior in-flight run on the same ref.
Re-run only the failed jobsgh run rerun RUN_ID --failedOnly previously failed jobs restart; passed jobs are untouched.
Save full logs for offline grepgh run view RUN_ID --log > run.logComplete log written locally and greppable.
Gate a deploy with required reviewersenvironment: productionThe job pauses for approval in the repo's Deployments tab before running.

Debug a failing run: red to green

debugging

1
Find which run failed
gh run list --workflow ci.yml --limit 5
# completed  failure  CI  main  push  12345678
2
Read only the failing step
gh run view 12345678 --log-failed
# X Run tests
#   FAIL src/auth.test.ts
#   Expected 200, received 500
3
Reproduce locally with the same command the step ran
npm ci && npm test
# FAIL src/auth.test.ts — same failure locally, so it is the code, not the runner
4
Fix on a branch with a conventional commit
git switch -c fix/auth-500 && git commit -am 'fix: handle null session'
5
Push so the push trigger re-runs CI
git push -u origin fix/auth-500
6
Confirm the new run is green
gh run watch $(gh run list -L1 --json databaseId -q '.[0].databaseId')
# ok  CI  success

Troubleshooting — symptom → first check → next check

SymptomFirst checkEstablishesNext check
Workflow did not trigger at allgh workflow list — is it enabled, and is the file on the default branch?Whether the event type, branches: filter, or paths: filter actually matched this push.Fix on:/branches:/paths:; remember push uses the workflow as it exists on the pushed branch, and a brand-new workflow must land on the default branch first.
Secret is empty in a pull_request runIs the PR from a forked repository?Fork PRs run without access to repo/org secrets by design (supply-chain safety).Move the secret into an environment the job declares, or use pull_request_target only with careful, read-only handling of untrusted code.
Permission denied / 403 from GITHUB_TOKENInspect the permissions: block plus repo Settings → Actions default token access.The token scope is read-only or missing the scope the step needs (e.g. packages: write).Grant the minimal scope at job or workflow level — least privilege, not write-all.
One matrix combo fails, the rest passgh run view RUN_ID --log-failed to isolate the failing combo.Whether it is genuine version-specific breakage versus flaky infrastructure.Set strategy.fail-fast: false to see every combo, then matrix.exclude/include to pin or quarantine the bad one.
Cache always misses (never restored)Compare the key: expression against the 'Cache restored from key' log line.The key changes every run (contains a timestamp/commit) or hashFiles points at the wrong path.Base the key on the lockfile hash and add restore-keys: with a stable prefix for partial hits.
Downstream job is skipped unexpectedlyDid an upstream needs: job fail or get skipped?needs propagates failure and skip downstream unless an explicit if: overrides it.Add if: ${{ !cancelled() }} or an explicit needs-context check where partial progress should still run.

References

GitHub-hosted runners (ubuntu-latest); gh CLI installed and authenticated against the repo; marketplace actions pinned to @v4; YAML indented with spaces, never tabs. Placeholders in CAPS: RUN_ID, BRANCH, EDITOR.