What's changed: New GH-200 Chapter 2 (interpreting/troubleshooting = triggers/status, logs/annotations/run history, ACTIONS_STEP_DEBUG, YAML anchor expansion, reading matrix and re-running individual jobs, fetching logs/artifacts via UI/API; templates & reuse = starter vs reusable workflows vs composite actions, org/non-public templates, disabling vs deleting)
2.1Interpreting Results and Troubleshooting
Read configuration and logs to understand what triggered a run and what happened, and diagnose failed runs from logs and run history. Understand expanding YAML anchors/aliases, reading matrix expansions (mapping job names to axes), analyzing failed variants and re-running individual jobs, and accessing logs/artifacts in the UI and via API.
Being the "consumer" of workflows—using existing pipelines, reading results, and fixing failures—is a key GH-200 area. The run page shows the trigger (event) that started it, the commit/PR, the target branch, and the status (success/failure/skipped/cancelled) of each job and step. The first step in troubleshooting is to reconcile "what the configuration (YAML) intended vs what actually happened in the logs."
2.1.1Diagnosing failures — logs and run history
For a failed job, expand the relevant step on the run page to see logs. Errors appear as summarized annotations that jump to the offending line. The run history shows whether the same workflow previously succeeded and when it started failing, helping isolate the cause (a code change, a dependency update, a runner-image update). If detail is insufficient, enable debug logging by setting the ACTIONS_STEP_DEBUG secret at the repo/org. Logs can be viewed and downloaded later while within retention.
2.1.2Expanding YAML anchors/aliases
Reading someone else’s workflow, you may find fragments reused via anchors (&) and aliases (*) and merge keys (<<). The YAML parser expands these before evaluation, so when analyzing you must expand—mentally or with a formatter—where an anchored value lands. Remember anchors/aliases are reuse within a single file and do not propagate to workflows in other files.
2.1.3Reading matrix expansions and re-running individual jobs
A matrix job appears as parallel jobs named like job (ubuntu-latest, 20) per combination. On failure, identify from the job name which axis combination (OS, version) broke and inspect its logs. You need not re-run everything—you can Re-run failed jobs only; conversely Re-run all jobs retries under the same GITHUB_RUN_ATTEMPT. When "only a specific variant fails," suspect environment-specific issues (deps, paths, OS differences).
2.1.4Accessing logs and artifacts (UI and API)
Logs and artifacts can be downloaded directly from the run-page UI and also listed/fetched/deleted via the REST API (or the gh CLI). For CI/CD automation and auditing, script operations like "fetch a run’s logs," "list and fetch artifacts," and "delete unneeded outputs." Because artifacts expire after their retention period, fetch and offload them in time if long-term storage is needed.
| Situation | Action |
|---|---|
| Only one matrix variant failed | Re-run failed jobs (individual) |
| A flaky failure across the run | Re-run all jobs |
| Cause unclear | Enable debug logs via ACTIONS_STEP_DEBUG |
| Find when it started failing | Review run history |
Common: (1) Diagnose failures via the step’s logs + annotations + run history to find the onset; for detail use ACTIONS_STEP_DEBUG. (2) Identify matrix failures by job name (axis) and Re-run failed jobs individually. (3) Read YAML anchors/aliases after expansion (single file). (4) Logs/artifacts are fetchable/deletable via UI and REST API/gh CLI, and disappear after retention.
Watch out: (1) "Re-run failed jobs" ≠ "Re-run all jobs"—use all for flaky failures, individual for a specific variant. (2) Missing anchor/alias expansion leads to misreading the config. (3) Logs are unavailable after retention—fetch early if needed. (4) Identify matrix jobs by axis values, not by position alone.
2.1.5Section summary
- Check trigger/status on the run page; diagnose via step logs + annotations + run history (detail via ACTIONS_STEP_DEBUG)
- Read YAML anchors/aliases after expansion (reuse within one file)
- Identify matrix failures by job name (axis); Re-run failed jobs individually
- Fetch/delete logs/artifacts via UI and REST API/gh CLI; they expire after retention
Sign in to track progress — Log in.
Quick check
(just a quick review)Q1. In an OS×Node-version matrix, only the windows-latest × Node 18 job failed. What is the most efficient response?
Q2. You need more detailed step-execution logs to investigate a failure the normal logs don’t explain. What do you do?
Q3. A colleague’s workflow uses many YAML anchors (&) and aliases (*). What is the correct premise for interpreting it?
Q4. For auditing, you want to script the retrieval and inventory of a specific run’s logs and artifacts. What can you use?
Q5. CI that succeeded until yesterday fails this morning. Which is an appropriate first move to isolate the onset?
Q6. A flaky network issue caused the whole run to fail randomly (the code is correct). What is the most appropriate response?