GitHub Actions: Debugging, Logs, and Troubleshooting

GitHub Actions•Permalink

Debug failing GitHub Actions workflows with log grouping, debug logging, step summaries, shell flags, and common troubleshooting patterns.

View

Standard Detailed Compact

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.

Create a collapsible log group

Group related output in the Actions log.

↗#

bashANYlogsgroup

bash

echo "::group::Install dependencies"
npm ci
echo "::endgroup::"

Log grouping keeps noisy steps readable.

Emit a notice annotation

Add an informational annotation to the run log.

↗#

bashANYnoticeannotations

bash

echo "::notice title=Build::Build completed successfully"

Workflow commands can create notices, warnings, and errors visible in the run UI.

Emit a warning annotation

Highlight a non-fatal issue in the run log.

↗#

bashANYwarningannotations

bash

echo "::warning file=package.json,line=1::Deprecated config detected"

Annotations make important issues much easier to spot in long logs.

Emit an error annotation

Mark a step error with file context.

↗#

bashANYerrorannotations

bash

echo "::error file=src/app.js,line=42::Build failed"

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"

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.

Use strict Bash mode

Fail fast in shell scripts.

↗#

bashANYbashstrict-mode

bash

set -euo pipefail

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"

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 -200

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@v4

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
done

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.

Recommended next

No recommendations yet.

Browse all sheets →