Troubleshoot GitHub Actions Workflow Runs: Logs, Matrix Re-runs and Artifacts (GH-200)

A workflow run starts only when an event listed under on: occurs and every filter on that event matches. When you read a trigger to predict or explain runs, check the event first, then the activity type, then each filter in turn: if any one of them fails, GitHub creates no run at all.

on:
  push:
    branches: [main]
    paths: ['src/**']
  pull_request:
    branches: [main]

• branches and paths together: when an event has both a branch filter and a path filter, the run starts only if both are satisfied. A push to main that touches only docs/ fails the path filter; a push to release/2.0 that touches src/ fails the branch filter.
• paths compare the changed files: a path filter passes when at least one file changed by the push (or by the pull request) matches a pattern. A commit that changes src/app.js and docs/guide.md passes src/**.
• branches-only filters ignore tags: if a push trigger defines only branches (or branches-ignore), pushing a tag does not start it. Tags are matched by tags/tags-ignore.
• pull_request default activity types: with no types: key, pull_request runs for opened, synchronize (a new push to the head branch) and reopened only. closed, labeled and the rest need to be listed. For pull_request, branches filters on the base branch.
• merging is a push: merging a pull request pushes a commit to the base branch, so a push: branches: [main] trigger starts a run for the merge, even though closed is not a default pull request type.

Applied to the trigger above: pushing a new branch feature/login starts nothing (it is not main), opening the pull request into main and pushing to it start two pull_request runs, and merging starts a push run on main only if the pull request changed at least one file under src/, because the push trigger's path filter still applies to the merge commit. The run list in the Actions tab names the event of each run, which is the fastest way to confirm which trigger fired; inside a run, github.event_name and the event payload show the same thing.

A workflow that is filtered out or skipped by a commit message creates no run, so any status check it would have produced never reports, and a required check stays Pending and blocks the merge. A job that is skipped by its if: condition is different: the run exists and the skipped job reports Success to required status checks.

Skip instructions. Workflows triggered by push or pull_request do not start when the commit message contains [skip ci], [ci skip], [no ci], [skip actions] or [actions skip], or ends with a skip-checks: true trailer (after two empty lines). For a pull request, the head commit's message counts. They apply only to push and pull_request: workflows on pull_request_target, workflow_dispatch and other events still run. Skip instructions are the only per-commit switch: disabling a workflow in the Actions tab is a separate, repository-wide setting that stops all of that workflow's runs until it is enabled again.

Path-scoped required checks. If a required check comes from a workflow with a paths filter, pull requests that change no matching files wait forever. Swapping paths for paths-ignore has the same problem, and branch protection cannot require a check only for certain paths. The reliable pattern is to let the workflow always run and skip the expensive job instead, for example with an if: on the output of an earlier job that detects which files changed — the skipped job then reports Success and the pull request can merge.

A pull_request run does not build the head branch's latest commit: GITHUB_REF is refs/pull/<number>/merge and GITHUB_SHA is the last merge commit on that ref — the head branch merged into the current base branch. actions/checkout with default inputs checks out that merge commit, so git rev-parse HEAD in the job prints a SHA that matches no commit on the head branch.

This explains a common failure: a branch passes locally, but its pull request run fails in a file the pull request never touched, because commits landed on main after the branch was created and the merge result no longer compiles. To reproduce it, merge the current base branch into the branch locally (or check out the merge ref) and build that — building the branch tip or main alone shows only half of the combination. pull_request_target runs in the context of the base branch, which is why it is used for trusted automation such as labelling, not for building contributor code.

To diagnose a failed run, open the run, select the failed job and read its step logs: failed steps expand automatically, annotations at the top of the run summary point to the errors, and each step shows its command and output. Two log-page behaviours often confuse people: the Search logs box only searches steps that are currently expanded (expand a collapsed passing step, or download the log archive, to search it), and values registered as secrets are masked as ***.

Why a step can pass when a command failed. A run step's exit code decides whether it passes, and the shell decides what that exit code is. On Linux and macOS:

So when a step pipes a command into another one, such as pytest | tee report.log, the default shell reports only the last command's status: the step passes even when the first command fails. Setting shell: bash explicitly adds pipefail, so any failing command in the pipeline fails the step while the pipeline itself is unchanged. Step settings that decide whether a step starts or whether its failure stops the job do not change the exit code the shell produces. On Windows runners the default shell is PowerShell (pwsh).

Other clues in a failed run: a job that hit timeout-minutes (default 360 minutes per job) is reported as cancelled with a message that it has exceeded the maximum execution time — that message, not the missing output, is the reliable clue; a job marked cancelled in a matrix may have been stopped by fail-fast (see below); and the run's history in the Actions tab shows whether the same workflow passed on earlier commits, which narrows the change that broke it.

GitHub Actions has two debug switches, and they produce different output: step debug logging adds debug lines to the step logs, while runner diagnostic logging adds the runner's own log files to the log archive.

Both can be set as a repository (or organization) secret or variable named exactly as shown, with no workflow edit, and then apply to every later run. If a secret and a variable with the same name both exist, the secret takes precedence, so check both lists when debug output does not appear as expected. RUNNER_DEBUG is different: the runner sets it to 1 when debug logging is on, so scripts can check it; setting it yourself does not enable debug output.

For a one-off investigation, use Re-run jobs → Enable debug logging on the run page (or gh run rerun <run-id> --debug, or enable_debug_logging in the REST re-run requests). That turns on both step debug and runner diagnostic logging for that re-run only, without commits or settings that affect other runs. It cannot add debug output to an attempt that has already finished.

Re-running a workflow does not create a new run: it adds an attempt to the same run. github.run_id and github.run_number stay the same and github.run_attempt increments. In the web interface, the Latest dropdown next to the run name lists every attempt, so you open an earlier attempt's logs from there — the run list shows one entry per run, not per attempt.

A re-run replays the original run. It uses the same GITHUB_SHA and GITHUB_REF as the original event, so a fix committed after the run started is not picked up — even a fix to the workflow file itself. To test a fix you need a new run: push a new commit that triggers the workflow, or start it with workflow_dispatch (Run workflow). Remember that a fix commit carrying a skip instruction starts no push run.

Who and when. Re-running needs write access to the repository and is possible for up to 30 days after the initial run, with at most 50 re-runs of a run. In a re-run, github.actor remains the user who triggered the initial run and the attempt uses that user's privileges, while github.triggering_actor is the user who started this attempt.

Logs per attempt. Each attempt keeps its own logs. After Re-run failed jobs, only the re-run jobs actually ran in the new attempt, so the latest attempt's logs are not a reliable record of how every job ran the first time. To be sure you have every job's log as it originally ran, choose attempt 1 in the Latest dropdown and download its archive, or call the attempt endpoint:

GET /repos/{owner}/{repo}/actions/runs/{run_id}/attempts/{attempt_number}/logs

Listing run history via REST. To fetch the runs of one workflow, call GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs, where workflow_id can be the workflow's numeric ID or its file name (for example ci.yml), and filter on the server with query parameters such as branch, event and status. The repository-wide GET /repos/{owner}/{repo}/actions/runs lists runs of every workflow and has no workflow filter. GET /actions/runs/{run_id}/jobs returns each job's metadata — status, conclusion, steps, IDs — but not log text.

A YAML anchor (&name) labels a node and an alias (*name) inserts a full copy of it elsewhere in the file. GitHub Actions workflow files support anchors and aliases, so before reasoning about what a workflow does, expand each alias into the content it copies.

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - run: npm run lint
  unit: &suite
    needs: lint
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - &clone
        uses: actions/checkout@v5
        with:
          submodules: true
      - run: npm test
  integration: *suite

• An aliased step is an exact copy, including its with: inputs: - *clone in another job also checks out submodules. It is still a separate step on that job's own runner — aliases copy configuration, not files or results.
• An aliased job copies the whole mapping, including needs, if and timeout-minutes. Above, integration gets the same needs as unit, so it has the same dependency and is skipped in the same circumstances. Note that an alias copies the job's body, not its key: the copy keeps its own job name.

Merged mappings. In YAML generally, a merge key (<<: *name) copies an anchored mapping's keys into another mapping and lets keys written locally override the copied ones. The official skill names merged mappings, but GitHub's workflow documentation describes anchors and aliases only and does not document merge keys, so do not rely on << in a workflow file without testing it. When reading any configuration that uses one, expand it the YAML way: start from the anchored mapping, then apply the locally written keys on top.

A matrix creates one job for every combination of its variables, then applies exclude, then applies include. To work out the jobs in a run, follow that order exactly:

1. Cross product: two os values × two node values = four combinations.
2. exclude: removes every combination that matches the entry. A partial match counts, so - os: windows-latest removes all Windows combinations.
3. include (processed after exclude): each entry's key–value pairs are added to every combination they can join without overwriting an original matrix value. Values that an earlier include added can be overwritten by a later include. An entry that cannot join any combination becomes a new combination of its own.

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    python: ['3.12', '3.13']
    include:
      - python: '3.13'
        coverage: full
      - os: windows-latest
        coverage: none
      - os: macos-latest
        python: '3.13'

Expanded: the first entry adds coverage: full to both Python 3.13 combinations. The second joins both Windows combinations and, on Windows/3.13, overwrites the added full with none. The third would have to overwrite an original os value in every combination, so it becomes a new, fifth job (macOS, Python 3.13, no coverage). Two general consequences follow: because include runs after exclude, an include can add back a single combination that an exclude removed; and an include whose original-matrix values all match existing combinations only adds keys to them and creates no new job.

Correlating names to axes. By default a matrix job's name is the job name followed by its matrix values in parentheses, such as test (ubuntu-latest, 22), in the order the variables are declared. Values that an include adds to a combination appear in that name too. Read the job list against the axes to see which values each job used.

When matrix variants fail, look for the axis the failures share: if every Windows job fails whatever the Node.js version, the cause is specific to Windows (paths, line endings, shell syntax); if every Node.js 24 job fails across operating systems, look at that runtime. Only jobs that actually ran to a failure tell you something — cancelled jobs have unknown results.

fail-fast defaults to true: when one matrix job fails, GitHub cancels the matrix's in-progress and queued jobs. A run with one red variant and several cancelled ones therefore has exactly one known failure. Set fail-fast: false to let every variant report. max-parallel only limits how many variants run at once, and a concurrency group cancels across runs, not between variants of one run.

Re-run options. Each matrix variant is its own job with its own job ID, so you can retry exactly the variants you need:

Dependents are included because a job that needed the failed one was skipped: re-running a failed test (windows-latest, 22) also runs the report job that needs test. "Re-run failed jobs" always retries every failed job, so to retry only some of the failures, list the run's jobs with GET /actions/runs/{run_id}/jobs, take each chosen variant's job ID, and re-run those jobs individually. The --job flag and the job endpoint take the numeric job ID, not the job's name. All of these respect the same rules as any re-run: same commit, 30-day window, write access.

Every run's logs and artifacts are reachable from its run page, and the same data is available through the REST API and gh. In the UI, open the Actions tab, choose the workflow in the sidebar, then the run: the job list and step logs are on the run page, the log view's menu offers Download log archive, and uploaded files are listed in the Artifacts section of the run summary, where clicking an artifact's name downloads it as a zip.

All paths start with /repos/{owner}/{repo}. The download endpoints answer with a 302 redirect whose URL expires after one minute, so a script must follow it straight away. Artifacts are addressed by ID: there is no download-by-name endpoint, zip is the only archive format, and the repository-wide name filter can return artifacts from other runs, so to fetch a named artifact from a specific run, filter that run's artifact list by name and use the ID it returns. An artifact's metadata also shows expired and expires_at. Annotations from the checks API and the jobs list are not log text.

GitHub CLI. gh run view <run-id> --log prints every step's log, and --log-failed prints only the failed steps. gh run download <run-id> downloads all of a run's artifacts, and -n <name> downloads only the named one. Reading logs is always gh run view; gh run list and gh run rerun list and re-run runs.

Downloading in a later job. Within the same run, a later job gets an artifact with actions/download-artifact; the job must needs the uploading job so the artifact exists when it starts.

- id: get
  uses: actions/download-artifact@v8
  with:
    name: web-bundle
    path: out/

• name downloads one artifact, extracted directly into path (default: the workspace). With no name, every artifact of the run is downloaded, each into its own directory named after the artifact.
• pattern selects artifacts by a glob on their names, and merge-multiple: true extracts all matching artifacts into the same directory instead of one directory each. Neither changes file contents or permissions.
• The download-path output gives the directory the files landed in, for later steps. It belongs to download-artifact; upload-artifact has no such output.
• Downloading from a different run needs run-id plus a github-token with read access to Actions (and repository when that run is in another repository). The token is what switches the source: without github-token, run-id is ignored and the action downloads from the current run, so a missing token shows up as an artifact not found.
• When the token is GITHUB_TOKEN and the workflow or job sets a permissions block, every scope it does not list becomes no access, so the block must include actions: read or the other run's artifacts cannot be read. A typical case is a deploy workflow triggered by workflow_run that fetches the build run's artifact with run-id: ${{ github.event.workflow_run.id }}.

on:
  workflow_run:
    workflows: [Build]
    types: [completed]
permissions:
  actions: read
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v8
        with:
          name: web-bundle
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ github.token }}

Inside the uploading job. actions/upload-artifact returns artifact-id, artifact-url and artifact-digest outputs, so a later step can link the artifact in the job summary with steps.<id>.outputs.artifact-url — no API call and no hand-built URL.

Managing artifacts. Deleting needs write access. Deleting one artifact keeps the run and its logs; deleting a run deletes its logs and artifacts too, and there is no single call that deletes all of one run's artifacts. Retention settings decide when artifacts and logs expire and apply to new artifacts, not ones already stored (retention configuration itself is covered with workflow authoring). Uploaded artifacts are zipped, and zipping does not keep file permissions — downloaded directories get 755 and files 644, so a compiled binary loses its execute bit. To keep exact modes, pack the files into a tar archive, upload that single file with archive: false (supported from upload-artifact@v7), and extract it after download.