bash
echo "::group::Install dependencies"
npm ci
echo "::endgroup::"Notes
Log grouping keeps noisy steps readable.
GitHub Actions: Debugging, Logs, and Troubleshooting
Debug failing GitHub Actions workflows with log grouping, debug logging, step summaries, shell flags, and common troubleshooting patterns.
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all
Debug logging and log structure
Make logs easier to inspect and turn on deeper diagnostics when needed.
bash
echo "::notice title=Build::Build completed successfully"Notes
Workflow commands can create notices, warnings, and errors visible in the run UI.
bash
echo "::warning file=package.json,line=1::Deprecated config detected"Notes
Annotations make important issues much easier to spot in long logs.
bash
echo "::error file=src/app.js,line=42::Build failed"Notes
Useful when custom scripts want to surface failures in a GitHub-native way.
Write a markdown step summary
Add a rich markdown summary to the workflow run.
bashANYGITHUB_STEP_SUMMARYsummary
bash
echo "## Test Summary" >> "$GITHUB_STEP_SUMMARY"Notes
Step summaries are excellent for concise results, links, and deployment info.
Shell failures and common fixes
Avoid brittle shell scripts and diagnose common workflow failures.
bash
set -euo pipefailNotes
This catches missing variables and pipeline failures early.
Inspect the raw event payload
Dump the event JSON file path or contents for debugging.
bashANYevent-payloadjq
bash
jq . "$GITHUB_EVENT_PATH"Notes
Very useful when your workflow depends on event payload fields and conditions.
Verify workspace contents
Check that expected files exist after checkout or artifact download.
bashANYworkspacefilesdebug
bash
find . -maxdepth 3 -type f | sort | head -200Notes
A quick workspace listing often reveals wrong paths or missing artifacts.
Pin actions to a major or full version
Avoid unexpected behavior from drifting dependencies.
yamlANYpinningactions
yaml
- uses: actions/checkout@v4Notes
Pinned versions improve predictability and security compared with unpinned references.
Retry a flaky network step in Bash
Wrap transient operations in a simple retry loop.
bashANYretryflaky
bash
for i in 1 2 3; do
npm install && break
sleep 5
doneNotes
Use sparingly for transient network issues while you investigate the real cause.
More in GitHub Actions
GitHub Actions: Runners, Containers, Services, and Self-Hosted Execution
GitHub-hosted runners, self-hosted runners, job containers, service containers, labels, and operational patterns for GitHub Actions execution.
GitHub Actions: Testing, Build, Release, and Deploy Pipelines
Practical CI/CD recipes for testing, build matrices, release creation, package publishing, and environment-based deployments in GitHub Actions.
GitHub Actions: Secrets, Permissions, Security, and OIDC
Secure GitHub Actions workflows with permissions, environments, secrets, masking, fork safety, and OpenID Connect for cloud auth.
GitHub Actions: Caching, Artifacts, and GitHub CLI Workflows
Cache dependencies, upload and download artifacts, and drive workflows with GitHub CLI commands in GitHub Actions.
GitHub Actions: Expressions, Contexts, Variables, and Outputs
Expressions, contexts, env vars, configuration variables, step outputs, job outputs, and dynamic workflow logic in GitHub Actions.
GitHub Actions: Jobs, Steps, Matrix, and Reusable Building Blocks
Jobs, steps, matrix builds, conditional execution, reusable workflows, composite actions, and service containers in GitHub Actions.