GitHub Actions Tutorial — Reading Logs

Reading Logs

Workflow run logs are your primary debugging tool. Knowing how to navigate them quickly saves time — especially for complex workflows with many jobs and steps.

---

Accessing Logs

GitHub UI

1. Repository → Actions tab
2. Click the workflow run
3. Click a job in the left sidebar
4. Expand individual steps

GitHub CLI

# List recent workflow runs
gh run list

# View a specific run
gh run view <run-id>

# View logs
gh run view <run-id> --log

# View failed logs only
gh run view <run-id> --log-failed

# Download logs as zip
gh run download <run-id>

API

curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID/logs \
  -L -o logs.zip

---

Log Structure

Workflow Run: CI Pipeline #142
├── Job: test
│   ├── Set up job              ← runner setup, image pull
│   ├── Run actions/checkout@v4 ← action output
│   ├── Run npm ci              ← your commands
│   ├── Run npm test            ← test output
│   └── Post Run actions/checkout@v4  ← cleanup
├── Job: build
│   ├── ...
└── Job: deploy
    ├── ...

Key Sections

Section	What It Shows
Set up job	Runner OS, image version, environment
Action steps	Action version, inputs, internal operations
Run steps	Your command output (stdout/stderr)
Post steps	Cleanup operations (cache save, logout)
Complete job	Final status, duration

---

Log Annotations

GitHub Actions uses special log commands to create annotations:

steps:
  - run: |
      echo "::notice::Deployment starting"
      echo "::warning::Cache miss — build will be slower"
      echo "::error file=src/app.js,line=10::Syntax error found"

Annotation	Appearance
::notice::	Blue info banner
::warning::	Yellow warning banner
::error::	Red error banner

Annotations also appear in the Summary tab and on PR checks.

---

Searching Logs

In the UI

• Use the search box at the top of the log view
• Click timestamps to get a permalink to a specific line

With GitHub CLI

# Search for specific text in logs
gh run view <run-id> --log | grep -i "error"

# View only failed steps
gh run view <run-id> --log-failed

Downloadable Logs

# Download and search
gh run download <run-id>
grep -r "FAILED" ./<run-name>/

---

Log Groups

Collapse related output into expandable groups:

steps:
  - run: |
      echo "::group::Install dependencies"
      npm ci
      echo "::endgroup::"

      echo "::group::Run tests"
      npm test
      echo "::endgroup::"

Groups appear as collapsible sections in the UI — much easier to scan than flat output.

---

Common Mistakes

Mistake	Fix
Can’t find the error	Use --log-failed or search for “Error” in the UI
Logs too long	Use ::group::/::endgroup:: to organize output
Logs expired	Logs are kept for 90 days (configurable down to 1 day)
Need to share a log line	Click the timestamp for a permalink

---

Quick Reference

Action	Command / Location
View in UI	Actions → Run → Job → Step
CLI view	gh run view <id> --log
Failed only	gh run view <id> --log-failed
Download	gh run download <id>
Search	Search box in UI or grep on CLI
Group output	::group::Title … ::endgroup::
Annotations	::error::, ::warning::, ::notice::

---

← Previous: Act (Local Testing)

Next: Debugging Strategies →