When an API test fails in GitHub Actions, preserve more than a screenshot or a copied error line. A useful failure bundle combines the workflow run and attempt identifiers, the relevant job logs, machine-readable test results, and a short manifest explaining what was collected. GitHub provides log-download APIs and workflow artifacts, but it does not define a standard failure-bundle format; choose the files, naming, and redaction rules for your project.
What to put in a failure bundle
Use a small, consistent set of files so someone else can identify the failed execution and understand which evidence is included. For example, a project could use this layout:
failure-bundle/
manifest.json
logs/
run-attempt.zip
failed-job.txt
test-results/
results.xmlThis is a proposed project format, not a GitHub requirement. Adapt names and report formats to your workflow and test runner.
- Manifest: repository, workflow and run IDs, run attempt, head SHA, job ID and name, failed step when available, collection time, and a list of included files.
- Logs: the failed job’s plain-text log, the run-attempt archive when broader context is needed, or both.
- Test report: a structured report supported by your test runner, such as an XML report if your runner can emit one.
Apply your repository’s secret and personal-data handling rules before retaining or sharing files. Logs and test reports can contain credentials, request data, or other sensitive values; redact them according to project policy.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches#1 Best Overall
Choose the right GitHub Actions logs
GitHub offers two useful scopes. The workflow-job endpoint downloads a specific job’s plain-text log; the workflow-runs API can return an archive of logs for a particular run attempt. In both cases, the returned download URL is temporary and expires after one minute, so fetch the file promptly rather than saving the redirect for later.
| Collection method | What it gives you | Best use | Important limitation |
|---|---|---|---|
| Workflow-job log endpoint | Plain-text log for one job. | Investigating a known failing job or collecting its log alongside a test report. | The download link expires after one minute. The endpoint requires repository read access; token permissions for a private repository vary by token type. |
| Workflow-run log endpoint | An archive of logs for a specified run attempt. | Preserving broader run context in one download. | The archive link also expires after one minute. One attempt may not include logs for jobs that ran in other attempts. |
For the exact request, parameters, and authorization requirements, use GitHub’s workflow-jobs API documentation or workflow-runs API documentation. Make the API call with a token that has the required repository read access, then immediately download the file from the redirect URL. Preserve the returned archive or text log locally or as an artifact; do not assume the temporary URL itself is durable.
Account for retries and earlier run attempts
A run-attempt archive is scoped to that attempt, not necessarily every job that has ever run for the workflow execution. GitHub notes that obtaining complete logs can require archives from previous run attempts that ran other jobs. The workflow run logs guidance explains this behavior.
Record the attempt number and job coverage in the manifest. If you collect more than one attempt, identify which archive came from each attempt rather than merging them into an unlabeled file. This makes it clear whether the bundle represents the failed attempt alone or a wider history of the run.
Rank #3
Save test results as a workflow artifact
API logs explain what the workflow printed; a structured test report can make failures easier to inspect, compare, or process. Configure the test command to emit a machine-readable report in a format its runner supports, then upload that report with the relevant logs. GitHub describes build and test output as examples of workflow artifacts and documents the upload-artifact and download-artifact actions for storing and sharing them in its workflow artifacts documentation.
Place artifact upload after the test step and configure it to run even when that step fails; otherwise, the failure can prevent the evidence from being saved. Include a concise manifest and any logs your workflow has already collected in the same artifact. Artifacts are the practical choice for accessing outputs after job completion, while the API endpoints are useful when you need to collect logs directly for a specific job or run attempt.
A practical collection sequence
- Capture execution identity. Record the repository, workflow/run ID, run attempt, head SHA, job ID and name, and failed step when available. GitHub’s job and run API responses expose identifiers and step status information.
- Select the evidence scope. Use the job-log endpoint for a single target job. Use the run-attempt endpoint when you want the broader archive, and consider both when the structured test report alone will not give enough context.
- Download temporary links immediately. Fetch the plain-text job log or run-attempt archive as soon as the API returns its redirect. The download URL expires after one minute.
- Check attempt coverage. If the workflow ran relevant jobs on prior attempts, collect those attempt archives as needed and label the coverage accurately.
- Emit and upload test output. Configure the test runner to write its supported structured report, then upload it with logs and the manifest as a workflow artifact after a failure.
- Review before sharing. Inspect the collected files for secrets and personal data, apply repository redaction rules, and ensure the manifest describes the files that remain.
Keep the bundle reproducible and interpretable
Consistency matters more than a particular filename convention. Choose a schema once, populate it from workflow context where possible, and ensure each log or report can be tied to a run, attempt, and job. The bundle should state its collection time and scope, especially when it contains multiple attempts. That small amount of provenance prevents a text log, archive, and test report from being mistaken for evidence from the same execution when they are not.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
