Running in CI

First Steps — Read Context

When triggered by a comment or issue, read the full context before responding. The prompt provides a URL — extract the PR/issue number from it.

For PRs:

gh pr view <number> --json title,body,comments,reviews,state,statusCheckRollup
gh pr diff <number>
gh pr checks <number>

For issues:

gh issue view <number> --json title,body,comments,state

Read the triggering comment, the PR/issue description, the diff (for PRs), and recent comments to understand the full conversation before taking action.

Security

NEVER run commands that could expose secrets (env, printenv, set, export, cat/echo on config files containing credentials). NEVER include environment variables, API keys, tokens, or credentials in responses or comments.

PR Creation

When asked to create a PR, use gh pr create directly.

Before creating a branch or PR, check for existing work:

gh pr list --state open --json number,title,headRefName --jq '.[] | "#\(.number) [\(.headRefName)]: \(.title)"'
git branch -r --list 'origin/fix/*'

If an existing PR addresses the same problem, work on that PR instead.

Pushing to PR Branches

Always use git push without specifying a remote — gh pr checkout configures tracking to the correct remote, including for fork PRs. Specifying origin explicitly can push to the wrong place.

If pushing fails (fork PR with edits disabled), fall back to posting code snippets in a comment. Don't reference commit SHAs from temporary branches — post code inline.

CI Monitoring

After pushing, wait for CI before reporting completion.

Use run_in_background: true for the polling loop so it does not block the session. When the background task completes you will be notified — check the result and take any follow-up action (dismiss approval, post analysis) at that point.

# Run with Bash tool's run_in_background: true
for i in $(seq 1 10); do
  sleep 60
  if ! gh pr checks <number> --required 2>&1 | grep -q 'pending\|queued\|in_progress'; then
    gh pr checks <number> --required
    exit 0
  fi
done
echo "CI still running after 10 minutes"
exit 1

Poll gh pr checks <number> --required every 60 seconds until all required checks complete (up to ~10 minutes). Ignore non-required checks (benchmarks).
If a required check fails, diagnose with gh run view <run-id> --log-failed, fix, commit, push, repeat.
After required checks pass, also poll codecov/patch via gh pr checks <number> (without --required) — this repo treats it as mandatory despite being marked non-required. Fix coverage gaps if it fails.
Report completion only after all required checks and codecov/patch pass.

Never report "done" before CI passes — CI runs on Linux, Windows, and macOS. Avoid gh run watch and gh pr checks --watch — both can hang indefinitely.

Before dismissing local test failures as "pre-existing", check main branch CI:

gh api "repos/{owner}/{repo}/actions/runs?branch=main&status=completed&per_page=3" \
  --jq '.workflow_runs[] | {conclusion, created_at: .created_at}'

If you cannot verify, say "I haven't confirmed whether these failures are pre-existing."

Replying to Comments

Reply in context rather than creating new top-level comments:

Inline review comments (#discussion_r): Reply in the review thread:

cat > /tmp/reply.md << 'EOF'
Your response here
EOF
gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies \
  -F body=@/tmp/reply.md

Conversation comments (#issuecomment-): Post a regular comment (GitHub doesn't support threading).

Comment Formatting

Keep comments concise. Put supporting detail inside <details> tags — the reader should get the gist without expanding. Don't collapse content that is the answer (e.g., a requested analysis).

<details><summary>Detailed findings (6 files)</summary>

...details here...

</details>

Always use markdown links for files, issues, PRs, and docs. Prefer permalinks (commit SHA URLs) over branch-based links for line references — line numbers shift and blob/main/...#L42 links go stale.

Files: link to GitHub (blob/main/... for file-level, blob/<sha>/...#L42 for lines)
Issues/PRs: #123 shorthand
External: [text](url) format

Don't add job links or footers — claude-code-action adds these automatically.

Shell Quoting

Shell expansion corrupts $ and ! in arguments (bash history expansion mangles ! in double-quoted strings). Always use a temp file for comment bodies and shell-sensitive arguments:

# Comments — ALWAYS use a file
cat > /tmp/comment.md << 'EOF'
Fixed — the `format!` macro needed its arguments on separate lines.
EOF
gh pr comment 1286 -F /tmp/comment.md

# Review replies — ALWAYS use a file
cat > /tmp/reply.md << 'EOF'
Good catch! Updated to use `assert_eq!` instead.
EOF
gh api repos/{owner}/{repo}/pulls/{number}/comments/{id}/replies \
  -F body=@/tmp/reply.md

# GraphQL — write query to a file
cat > /tmp/query.graphql << 'GRAPHQL'
query($owner: String!, $repo: String!) { ... }
GRAPHQL
gh api graphql -F query=@/tmp/query.graphql -f owner="$OWNER"

# jq with ! — use a file
cat > /tmp/jq_filter << 'EOF'
select(.status != "COMPLETED")
EOF
gh api ... --jq "$(cat /tmp/jq_filter)"

Use << 'EOF' (single-quoted delimiter) to prevent expansion. For file-based bodies: gh pr comment uses -F /tmp/file (path directly), while gh api uses -F body=@/tmp/file (field assignment with @ prefix).

Keeping PR Titles and Descriptions Current

When revising code after review feedback, update the title and description if the approach changed:

gh api repos/{owner}/{repo}/pulls/{number} -X PATCH \
  -f title="new title" -F body=@/tmp/updated-body.md

Atomic PRs

Split unrelated changes into separate PRs — one concern per PR. If one change could be reverted without affecting the other, they belong in separate PRs.

Investigating Other CI Runs

The primary evidence for diagnosing bot behavior is the session log artifact — not console output (show_full_output defaults to false).

gh run download <run-id> -n claude-session-logs -D /tmp/session-logs-<run-id>

The artifact contains JSONL files (path like -home-runner-work-worktrunk-worktrunk/<session-id>.jsonl). Each line has a type field (user, assistant, system).

# Skills loaded
jq -r 'select(.type == "assistant") | .message.content[]? |
  select(.type == "tool_use" and .name == "Skill") | .input.skill' <FILE>.jsonl

# Tool calls
jq -r 'select(.type == "assistant") | .message.content[]? |
  select(.type == "tool_use") |
  "\(.name): \(.input | tostring | .[0:100])"' <FILE>.jsonl

# Assistant reasoning
jq -r 'select(.type == "assistant") | .message.content[]? |
  select(.type == "text") | .text' <FILE>.jsonl

Find the right run among multiple workflows:

gh api 'repos/{owner}/{repo}/actions/runs?per_page=30' \
  --jq '.workflow_runs[] | select(.name | startswith("claude-")) |
    {id, name, event, head_branch, created_at, conclusion}'

Check for artifacts before downloading:

gh api repos/{owner}/{repo}/actions/runs/<run-id>/artifacts \
  --jq '.artifacts[] | {name, size_in_bytes}'

Review-response runs triggered by pull_request_review or pull_request_review_comment events sometimes produce no artifact when the session is very short.

Grounded Analysis

CI runs are not interactive — every claim must be grounded in evidence. The user can't ask follow-up questions; treat every response as your final answer.

Read logs, code, and API data before drawing conclusions. Show evidence: cite log lines, file paths, commit SHAs. Trace causation — if two things co-occur, find the mechanism rather than saying "this may be related." Never claim a failure is "pre-existing" without checking main branch CI history. Distinguish what you verified from what you inferred.

Tone

Raise observations, don't assign work. Never create checklists or task lists for the PR author.

PR Review Comments

For review comments on specific lines ([Comment on path:line]), read that file and examine the code at that line before answering.

running-in-ci