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.
Quick reference — reach for these first
on: [push, pull_request, workflow_dispatch]When the workflow runs; add branches:/paths: to narrow the match.jobs: { build: { runs-on: ubuntu-latest } }Each job gets a fresh runner VM; its steps share that filesystem.- uses: actions/checkout@v4Run a prebuilt, version-pinned action — contrast with run: for shell.strategy: { matrix: { node: [20, 22] } }Fan one job into parallel variants; one combo per value set.${{ secrets.NPM_TOKEN }}Inject encrypted secrets; GITHUB_TOKEN is auto-provided per run.How a workflow run is wired together
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
| Task | Command | What to check |
|---|---|---|
| Scaffold a workflow file | mkdir -p .github/workflows && EDITOR .github/workflows/ci.yml | File lives under .github/workflows/ with a .yml or .yaml extension. |
| Validate YAML before pushing | yamllint .github/workflows/ci.yml | No syntax errors; indentation is spaces, not tabs. |
| Trigger manually (workflow_dispatch) | gh workflow run ci.yml --ref BRANCH | A new run appears in gh run list within seconds (needs on: workflow_dispatch). |
| List recent runs | gh run list --workflow ci.yml --limit 10 | Status column shows completed / in_progress / queued per run. |
| Watch a run live | gh run watch RUN_ID | Steps stream to the terminal and the command exits on completion. |
| Read only the failing logs | gh run view RUN_ID --log-failed | Shows just the failed step's output, not the entire run log. |
| Order jobs with needs | needs: [build] | The dependent job starts only after build completes successfully. |
| Cache dependencies | uses: actions/cache@v4 (key: npm-${{ hashFiles('**/package-lock.json') }}) | A later run logs 'Cache restored from key'. |
| Upload a build artifact | uses: 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 runs | concurrency: { 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 jobs | gh run rerun RUN_ID --failed | Only previously failed jobs restart; passed jobs are untouched. |
| Save full logs for offline grep | gh run view RUN_ID --log > run.log | Complete log written locally and greppable. |
| Gate a deploy with required reviewers | environment: production | The job pauses for approval in the repo's Deployments tab before running. |
Debug a failing run: red to green
debugging
gh run list --workflow ci.yml --limit 5
# completed failure CI main push 12345678gh run view 12345678 --log-failed
# X Run tests
# FAIL src/auth.test.ts
# Expected 200, received 500npm ci && npm test
# FAIL src/auth.test.ts — same failure locally, so it is the code, not the runnergit switch -c fix/auth-500 && git commit -am 'fix: handle null session'
git push -u origin fix/auth-500
gh run watch $(gh run list -L1 --json databaseId -q '.[0].databaseId')
# ok CI successTroubleshooting — symptom → first check → next check
| Symptom | First check | Establishes | Next check |
|---|---|---|---|
| Workflow did not trigger at all | gh 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 run | Is 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_TOKEN | Inspect 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 pass | gh 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 unexpectedly | Did 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
- Workflow syntax for GitHub Actionsdocs.github.com
- Events that trigger workflowsdocs.github.com
- Using secrets in GitHub Actionsdocs.github.com
- Automatic token authentication (GITHUB_TOKEN)docs.github.com
- gh run — GitHub CLI manualcli.github.com
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.