github-workflow
Complete GitHub workflow: authentication (HTTPS/SSH/gh CLI), PR lifecycle (branch, commit, open, CI, merge), code review (local and PR-level), issue management (create, triage, label, assign), reposit
SKILL.md.claude/skills/github-workflow/SKILL.md
GitHubGitHub Workflow — Complete Guide
End-to-end GitHub operations: auth, PRs, code review, issues, and repo management. Each section shows gh first, then curl fallback.
Auth Setup
See references/github-auth.md for full auth guide. Quick reference:
- gh CLI:
gh auth login(interactive) orecho "<token>" | gh auth login --with-token - HTTPS token:
git config --global credential.helper store→ paste token on first operation - SSH:
ssh-keygen -t ed25519→ add public key at https://github.com/settings/keys - API without gh:
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/...
MCP GitHub vs gh CLI Fallback (2026-06-30)
Hermes kann GitHub über zwei völlig getrennte Pfade ansprechen, und die Credentials sind NICHT geteilt:
| Pfad | Auth-Quelle | Token-Speicher |
|---|---|---|
mcp_github_* Tools (MCP) |
mcp_servers.github.env.GITHUB_TOKEN in ~/.hermes/config.yaml |
Docker-Container-Env |
gh api ..., gh issue ... etc. |
gh auth login (keyring) oder ~/.config/gh/hosts.yml |
System-keyring + Config |
Symptom wenn MCP GitHub 401t während gh CLI funktioniert:
mcp_github_get_me() → {"error": "failed to get user: GET https://api.github.com/user: 401 Bad credentials []"}
gh auth status → ✓ Logged in to github.com account Toqsick
Was dann zu tun ist (Pitfall-Pattern):
- NICHT mehrfach MCP-Tools retryen — das ändert nichts, weil MCP eigene Credentials hat.
- NICHT blind
mcp_servers.github.env.GITHUB_TOKENpatchen — kann Config-Drift zwischen MCP-Docker-Container und Host-ghAuth verursachen. - Sofort auf
ghCLI umsteigen für read-only Operations:- User-Suche:
gh search users --json login,name - Repo-Liste:
gh repo list Toqsick --json name,pushedAt,description - Issues:
gh issue list --repo Toqsick/hermes-v7 --state open - Issue-Body:
gh issue view 1 --repo Toqsick/hermes-v7 --json body | jq -r .body - PR-Suche:
gh search prs --author Toqsick --state open --json number,title,repository - API-generisch:
gh api "repos/Toqsick/hermes-v7/contents/ROADMAP.md" --jq .content
- User-Suche:
- Verifizieren mit
gh auth status— zeigt aktiven Account + Token-Scopes. - Bei MCP-Fix-Bedarf: siehe
devops/hermes-adminSkill → "Auth prüfen" Sektion (Container-Restart nachconfig.yaml-Patch nötig).
Wann MCP reparieren statt umgehen: Wenn der User explizit MCP-basierte Features nutzt (z.B. MCP-Tool-Routing via Plugin-Registry) oder wenn mehrere Sessions neu starten müssen. Für einmalige Research-Tasks: gh CLI ist schneller und zuverlässiger als MCP-Config-Debugging.
MCP-tool response traps (verified 2026-07-07 batch CONTRIBUTING.md push):
mcp__github__create_or_update_filemay return "File already exists. Provide SHA." even when the file genuinely does NOT exist on the target repo. Verified: file was missing (curl 404), MCP said "already exists", but the server-side write still went through and the file appeared on the next GET. Treat MCP write errors as soft signals, not ground truth. After any error from this tool, always curl-verify the resulting state withcurl -s -o /dev/null -w "%{http_code}" https://raw.githubusercontent.com/OWNER/REPO/BRANCH/PATH.mcp__github__get_file_contentsreturns a sentinel success with SHA777035533703e3b24b90916e17598aeb2f8fb17afor files that don't exist (curl gives HTTP 404). Never trust MCP existence checks — always curl-confirm withhttps://api.github.com/repos/OWNER/REPO/contents/PATH?ref=BRANCHand parse the JSON.mcp__github__create_or_update_fileenters "MCP server 'github' is unreachable after 3 consecutive failures. Auto-retry available in ~32s." cooldown after repeated failures. Do not keep hammering it — switch togh api -X PUTor curl withgh auth tokenfor the rest of the session. The cooldown is per-tool-call, not per-session, and the warning explicitly says "Do NOT retry this tool yet".- When MCP and curl disagree on a file's existence, curl wins. MCP's success metadata is not authoritative for filesystem-shape questions (file present? which SHA? which size?).
Beispiel-Workflow für Repo-Audit (read-only via gh):
# Repo-Inventar
gh repo list Toqsick --limit 100 --json name,description,pushedAt
# Heutige Commits (alternative zu MCP search)
gh api "repos/Toqsick/$repo/commits?since=$(date +%Y-%m-%d)T00:00:00Z&per_page=100" --jq 'length'
# Issue-Triage mit Labels
gh issue list --repo Toqsick/$repo --state open --limit 20 --json number,title,labels,createdAt \
| jq -r '.[] | "#\(.number) [\(.labels | map(.name) | join(","))] \(.title)"'
"Was wurde kürzlich gepusht?" — Push-Audit-Recherche
Wenn User behauptet „du hast gestern gepusht" / „da wurde was committed" / „ich glaub mein Auto-Push ist gelaufen" — die Frage ist „was sagt der Remote-Stand im Vergleich zu lokal?", nicht „was sagt mein lokales Log?".
Ground-Truth-Reihenfolge:
git ls-remote origin→ autoritativ, zeigt direkt was remote existiert (SHA + Ref pro Branch/PR)- Vergleich mit
git rev-parse origin/mainundgit rev-parse HEAD→ identisch = nichts gepusht - Wenn MCP GitHub 401 wirft: nicht retryen, sondern direkt
gh apiodergit ls-remotenutzen - Wenn
curl https://api.github.com/repos/.../commits404 zurückgibt → Repo ist privat, das ist eine nützliche Diagnose, kein Fehler
Vollständige Verifikationsmatrix (MCP/ls-remote/gh/public-API Triangulation), häufige Fehler (z. B. „Working tree clean ≠ nichts gepusht") und Session-Recipes: siehe references/push-audit-research.md.
PR Lifecycle
See references/github-pr-workflow.md for full guide. Quick reference:
set -euo pipefail
# Branch → Commit → Push → Create PR → Monitor CI → Merge
git checkout -b feat/description
git add . && git commit -m "feat: description"
git push -u origin HEAD
gh pr create --title "feat: description" --body "Summary\n\nCloses #42"
gh pr checks --watch
gh pr merge --squash --delete-branch
Code Review
See references/github-code-review.md for full guide. Quick reference:
Local Changes (Pre-Push)
set -euo pipefail
git diff main...HEAD --stat # scope
git diff main...HEAD # full diff
git diff main...HEAD | grep -n "print\|console\.log\|TODO\|FIXME" # debug statements
PR Review on GitHub
set -euo pipefail
gh pr view 123
gh pr diff 123
git fetch origin pull/123/head:pr-123 && git checkout pr-123 # local checkout
gh pr review 123 --approve --body "LGTM"
gh pr review 123 --request-changes --body "See inline comments"
Inline Comments (curl fallback)
set -euo pipefail
# Get HEAD SHA, then POST to /repos/{owner}/{repo}/pulls/{number}/reviews
Issue Management
See references/github-issues.md for full guide. Quick reference:
set -euo pipefail
# Create
gh issue create --title "Bug: X" --body "..." --label "bug" --assignee "@me"
# List
gh issue list --state open --label "bug"
gh issue list --assignee @me
# Manage
gh issue edit 42 --add-label "priority:high"
gh issue edit 42 --add-assignee username
gh issue comment 42 --body "Investigated — working on fix"
gh issue close 42
gh issue reopen 42
Pitfalls
gh issue view <N> --json ...does NOT includenumber(it also stripsrepository). The output gives title/body/labels/comments/state, but every field you'd reasonably expect fromgh issue list --json number,title,...is missing. Python parsers that dod['number']getKeyError. Workarounds: (a) pair eachgh viewwith the number you already know —[{"number": <N>, **d}]; (b) read numbers fromgh issue list --json number,titleseparately and join. Verified 2026-07-07 on Toqsick/greyscripts triage — every per-issue read needed this fix.Read-only vs mutating triage — ask before assuming. When the user says "kategorisieren", "priorisieren", "review", "audit", default to read-only (categorize, write report, but do NOT add labels / comments / close anything). Explicitly note "read-only" in the report footer so the user knows. Only mutate when the user explicitly says "label them", "close the empty ones", etc. Many reviewer/external/audit profiles do not have mutation rights.
Cross-check the user's numerical assumptions. If the user names a count ("alle 54 offenen Issues") or describes scope, verify against actual API state before diving in. The discrepancy is load-bearing context — the user may be working from a stale mental model, the repo was recently groomed, or they're testing whether you'll blindly trust framing. Surface the gap clearly at the top of the report; don't silently adjust and proceed. Verified 2026-07-07: user said "54", repo had 7 (other 47 closed) → flagging this upfront saved the session.
Triage-report shape — what the user actually wants. A categorized, prioritized Markdown report, not just a list. Default deliverable: per-issue row with number/title/category/labels/priority/recommendation; activity check (
age_days+stale_days, flag stale beyond threshold); empty-body issue detection (CI-badge-only or "[BUG]" placeholder → recommendstate_reason=not_planned); recommended execution order based on dependency graph; summary table by category. Skip any of these only when the user signals a different deliverable.
Repository Management
See references/github-repo-management.md for full guide. Quick reference:
set -euo pipefail
# Clone/Create/Fork
gh repo clone owner/repo
gh repo create my-project --public --clone
gh repo fork owner/repo --clone
# Settings
gh repo edit --description "..." --visibility public
gh repo edit --enable-auto-merge
# Releases
gh release create v1.0.0 --title "v1.0.0" --generate-notes
# Secrets
gh secret set API_KEY --body "value"
gh secret list
# Actions
gh workflow list
gh run list --limit 10
Documentation Health Audit
When the user asks to update READMEs, check what's outdated, or audit repo docs, use the pattern from references/documentation-health-audit.md (10 phases).
Core phases (1–7): Parse claims → Count state → Count support files → Verify standalone deps → Find thin sub-READMEs → Cross-reference category listings → Verify CI badges
Post-update phases (8–10): Markdown verification → Thin README expansion → Category table enrichment
Common pitfalls:
find . -maxdepth 2avoids counting nested build outputs and git-internal copies- Always exclude
bin/,build/,src/,test/,tests/,includes/,scripts/from tool counts — these are support, not tools grep -l+xargsavoids false positives from backup dirs; usefind -path './de/*' -pruneto exclude import snapshots- standalone.md is usually the most stable doc (deps don't change), main README is the most drift-prone (numbers get stale)
- After updating READMEs, always run Phase 8 (Markdown verification) — even text-only changes can break links or introduce syntax errors
- Thin READMEs (< 500B) are often template placeholders; expand with real build paths and feature descriptions (600–1100B target)
See references/documentation-health-audit.md for the full shell script patterns, execute_code alternatives, and a session example.
GitHub Automation Scripts
See references/github-automation-patterns.md for a complete pattern. Quick reference:
set -euo pipefail
# Build a reusable Python automation script
scripts/
hermes-automation.py # Main CLI: issue, branch, build, pr, status, etc.
# Typical commands:
python3 scripts/hermes-automation.py issue --title "Bug: X" --label bug --milestone v1.0.0
python3 scripts/hermes-automation.py branch --issue 42 --name feature/toolname
python3 scripts/hermes-automation.py pr --issue 42 --title "feat: tool Closes #42" --body "..."
python3 scripts/hermes-automation.py status --json > results/status.json
GreyHack/Greybel CI addendum
For GreyHack repos that use greybel-js, see references/greybel-ci-pattern.md. It captures the current greybel build <output-dir> syntax, the fact that the installed executable may be named greybel rather than greybel-js, how to avoid stale imported-tool directories in default CI, and safe issue/PR body handling with --body-file.
Key patterns:
- Single script, multiple subcommands — use
argparsewith subparsers forissue,branch,build,pr,status, etc. ghCLI as primary interface — all GitHub API calls throughgh api,gh issue,gh pr- Clean JSON output for cron jobs — when
--jsonis passed, output ONLY valid JSON (no status text, no progress logs). Put human-readable output in the non-JSON path. - Build verification — for code repos, add a
verify-allcommand that builds/tests all source files and writes results toresults/. - Cron integration — schedule daily status checks with
hermes cronjob create. Use[SILENT]protocol when nothing changed. - Shell escaping — when passing multi-line strings to
gh pr comment --body, wrap in single quotes or write body to a temp file to avoid shell interpreting backticks and$.
Pitfalls:
- Backticks in shell strings:
gh pr comment --body "Text withcode"will executecode. Use single quotes orgh pr edit --body-file/gh pr create --body-file. - JSON pollution: If
--jsonoutputs anything before the JSON object, downstream parsers fail. Gate all print statements withif not json_output. - Subagent rate limits: When using multi-agent orchestration for GitHub tasks, subagents may hit API rate limits. Parent should verify claims and complete critical fixes directly.
- Working tree cleanliness: Before JSON status reports, clean
__pycache__/and other generated artifacts to avoid false "dirty" reports. - Duplicate PR cleanup: When creating PRs programmatically across multiple branches, check for stale duplicate PRs before reporting status. Close duplicates with
gh pr close <num> --comment "Duplicate of #<target>". - Issue/PR state drift: GitHub does not always auto-close issues when PRs merge. If the PR title has
(#3)but the body doesn't containCloses #N, the issue stays OPEN even after merge. Always useCloses #NorFixes #Nin the PR body, and manually close withgh issue close <num>if drift is detected.
Batch File Push via Contents API
When the user wants the same file (e.g. CONTRIBUTING.md, LICENSE, .github/CODEOWNERS, a policy file) pushed to multiple repos in one shot, prefer the Contents API (PUT /repos/{o}/{r}/contents/{path}) over git clone × N: faster, no local working tree, atomic per-repo commit.
Pattern (gh CLI, parallel across repos):
# Pre-encode once, reuse for every repo
CONTENT_B64=$(base64 -w0 /path/to/file)
COMMIT_MSG="docs: add CONTRIBUTING.md"
push_one() {
local repo="$1" branch="$2"
local body
body=$(jq -n --arg m "$COMMIT_MSG" --arg c "$CONTENT_B64" --arg b "$branch" \
'{message:$m, content:$c, branch:$b}')
local resp
resp=$(gh api -X PUT "repos/OWNER/$repo/contents/PATH" \
-H "Accept: application/vnd.github+json" \
--input - <<<"$body" 2>&1)
if echo "$resp" | jq -e '.commit.sha' >/dev/null 2>&1; then
echo "OK $repo@$branch commit=$(echo "$resp" | jq -r '.commit.sha' | head -c7)"
else
echo "FAIL $repo@$branch $(echo "$resp" | head -c 200)"
fi
}
push_one repo-a main
push_one repo-b main
push_one repo-c master # some repos use master, some main
Pitfalls
409 Conflict"is at <real-SHA> but expected <stale-SHA>":gh api PUT contents/caches a stale HEAD-SHA from an earlier fetch in the same process. The repo HEAD moved (parallel worker, CI, web commit) but the request still carries the old expected blob SHA. Fix: retry without theshafield — the API then treats the request as a fresh Create-or-Update against current HEAD. To overwrite an existing file intentionally, fetch the currentshafirst and pass it explicitly.# Retry without sha (Create path) body=$(jq -n --arg m "$COMMIT_MSG" --arg c "$CONTENT_B64" \ '{message:$m, content:$c, branch:"main"}') gh api -X PUT "repos/OWNER/$repo/contents/PATH" --input - <<<"$body" # Or with current sha (Update path) CUR_SHA=$(gh api "repos/OWNER/$repo/contents/PATH" --jq .sha 2>/dev/null) body=$(jq -n --arg m "$COMMIT_MSG" --arg c "$CONTENT_B64" --arg s "$CUR_SHA" \ '{message:$m, content:$c, branch:"main", sha:$s}')Default branch matters.
gh api repos/OWNER/REPO --jq .default_branchis the source of truth — never trust user-supplied branch names in a batch task. Pushing to a non-existent branch returns 422, not 409.Content field is base64-with-embedded-newlines. GitHub inserts
\nevery 60 chars.jq -r '.content' | base64 -dworks;base64 -ddirectly on the raw JSON string fails silently. Use-w0on encode side for round-trip determinism.Push returning
200 OK+commit.sha≠ content-is-correct. Verify byte-identicality after a batch push with an MD5 cross-check (catches CRLF/LF/BOM drift, truncation, accidental overwrites):SOURCE_MD5=$(md5sum /path/to/file | awk '{print $1}') for repo in repo-a repo-b repo-c; do remote_md5=$(gh api "repos/OWNER/$repo/contents/PATH" --jq '.content' 2>/dev/null \ | base64 -d 2>/dev/null | md5sum | awk '{print $1}') [ "$remote_md5" = "$SOURCE_MD5" ] && echo "MATCH $repo" || echo "DIFFER $repo" doneWhen NOT to use this pattern: files > ~100 MB (Contents API truncates), repos with branch protection that block direct main commits (use a feature branch + PR), or files with merge-conflict potential (e.g. existing
CONTRIBUTING.mdwith project-specific content — overwriting silently is destructive).Domain-specific templates may not be reusable. When copying a
CONTRIBUTING.md/LICENSE/ template from one repo, read it first and check that the language/structure fits the target repos. A GreyScript template withimportcode/fail()/shellrules is useless in a TypeScript/React project. Fall back to a generic template if the source is too domain-specific. Verified 2026-07-07: greyscripts-CONTRIBUTING.md(38 lines, German, GreyScript conventions) was not reusable across 4 mixed repos (hermes-v7, MaxClaw, sse-dashboard, multi-agent-workflows) — fell back to a 14-line generic MIT-licensed template.
Skill Conversion & Config-Sync Workflow
When user asks to 'push my skills to github', 'sync skills between devices', 'convert skills from <X> to <Y>' — these are common, distinct from PR work, and follow a non-obvious pattern. Apply this 7-step workflow:
Inventory target repo first.
gh repo view <name> --json name,description,pushedAt,defaultBranchRef. Discover if repo exists or whethergh repo createwould fail silently.If repo exists and has unrelated code:
gh repo clone <name> ~/worktree. Don'tgh repo create— it errors withName already exists.If repo doesn't exist and you already have a local working tree ready (e.g.
/tmpstage dir), use the atomic pattern:cd /path/to/local-working-tree git init -q git config init.defaultBranch main # ← PREVENT master-branch issue git add -A && git commit -q -m "Initial commit" gh repo create <name> --private --description "..." --source=. --pushThe
--source=. --pushflag creates the remote AND pushes in one command — no separategit remote addneeded. BUT:gh repo createwith--source=. --pushpushes the local branch name as-is. If you forgetconfig init.defaultBranch main, the remote getsmaster. Fix:git branch -m master main git push origin main gh repo edit --default-branch main # update GH's default refSimpler: set
init.defaultBranch mainbefore git init — then the remote getsmaindirectly.Without
--source=. --push(older pattern, still valid):gh repo create <name> --public --description '...' git remote add origin "https://github.com/USER/<name>.git" git push -u origin mainUse HTTPS-with-token from
gh auth tokenfor push, not SSH:TOKEN=$(gh auth token) git remote set-url origin "https://Toqsick:${TOKEN}@github.com/Toqsick/<repo>.git" git push -u origin mainThis avoids SSH-host-verification failures which turn into long debugging.
Pick a flat-id namespace under one umbrella dir. For skill conversion (Hub ↔ Hermes, etc.), never merge categories — use e.g.
skills/hub-imported/<hub-id>/. Seesoftware-development/skill-format-conversionfor the canonical workflow.Commit on a feature branch if the default branch is populated. Use
git switch -c feat/skills-import-<date>. Thengh pr createfor review.Always include secrets-preflight when converting skills: many skill-system source trees carry
~/.hermes/auth.jsonreferences or hardcoded tokens.grep -rE '(api[_-]?key|secret|password|bearer|token)[^[:space:]]{0,5}[:=]["'"'"']?[A-Za-z0-9_-]{16,}'over the source before committing.
Pitfall — pushing to a populated repo on main:
$ git push -u origin main
To https://github.com/<owner>/<repo>.git
! [rejected] main -> main (fetch first)
error: failed to push some refs
This means the repo has commits you don't have. Either:
git fetch origin && git merge origin/main --allow-unrelated-histories(if desired to add on top)- Branch instead:
git switch -c feat/skills-2026-07-03-import && git push -u origin feat/skills-2026-07-03-import && gh pr create
- Shell escaping in
gh pr comment: Multi-line bodies with backticks get executed by the shell. Use single quotes or--body-fileto avoid command substitution. - Missing labels/milestones:
gh issue create --labelfails if the label does not exist. Check labels first or create missing labels intentionally. Someghversions lackgh milestone; usegh api -X GET 'repos/{owner}/{repo}/milestones?state=all'instead. - Workflow YAML linting: Quote the GitHub Actions trigger key as
"on":to avoidyamllinttruthy-value warnings.
Issue-to-PR workflow pattern:
set -euo pipefail
1. Merge automation PR first
2. Create feature branch from develop
3. Build/verify target file
4. Fix syntax/import errors
5. Commit + push
6. Create PR with `Fixes #<issue>`
7. Clean up duplicate PRs if any
8. Show final status
This pattern was validated with Issue #5 (routerinfo) on 2026-06-18.
GreyHack/Greybel CI pattern
For GreyHack repos that build GreyScript with greybel-js, treat CI as a first-class issue/PR flow, not just a script edit:
set -euo pipefail
# 1. Create explicit CI issues before coding.
gh issue create --title '[CI] Add Greybel build verification to CI' --body-file /tmp/issue-ci-greybel-build.md --label ci,enhancement,roadmap --milestone v0.5.0
gh issue create --title '[CI] Make ci-build.sh scan active .src directories' --body-file /tmp/issue-ci-build-script.md --label ci,bug,enhancement --milestone v0.5.0
# 2. Branch from develop and implement both sides of the CI contract.
git checkout -b feat/p0-ci-greybel-build
# 3. Update the build script to scan active source dirs, not stale bin/ paths.
# 4. Add a workflow job that installs greybel-js, runs the script, and uploads outputs.
# 5. Commit, push, and open a PR with `Closes #<issue>` lines in the body.
Use this shape:
scripts/ci-build.shscans active.srcdirectories such assrc/,tools/, andgreyhack-tools/if present.- CI installs
greybel-jswithnpm install -g greybel-js. - CI runs
bash scripts/ci-build.sh --out-dir .ci-build. - CI uploads
.ci-build/as an artifact. .gitignoreignores.ci-build/.- Quote the workflow trigger key as
"on":to avoidyamllinttruthy warnings.
Pitfalls:
- Workflow TODOs may live in docs/plans instead of
.github/workflows/*.yml; scan docs and plans too. gh api repos/OWNER/REPO/milestonesdefaults to POST; usegh api -X GET 'repos/{owner}/{repo}/milestones?state=all'.gh milestonemay be unavailable in the installed gh CLI; usegh apifor milestones.gh issue create --label roadmapfails if the label does not exist; create the label first or use existing labels.- Use
--body-fileforgh pr create/gh pr editwhen the body contains backticks/code fences; otherwise the shell may execute code inside backticks.
See references/greyhack-greybel-ci.md for a concrete session reference with the issue/PR URLs, changed files, validation commands, and pitfalls.
Read-only CI Failure Diagnosis (gh CLI workflow)
When the user reports "CI is red", "build fails", "issue #N says build broken", or asks to debug CI without committing anything — use this recipe. It is read-only by design: no commits, no workflow edits, no --push, no PR comments unless explicitly requested.
Workflow
# 1. Find the failing run
gh run list -R OWNER/REPO --limit 10 --json databaseId,status,conclusion,name,headBranch,event,createdAt
# 2. Get the failed-step log (mixes labels + ANSI + real errors — filter)
gh run view <run-id> -R OWNER/REPO --log-failed 2>&1 | grep -E '##\[error\]|exit code [0-9]+|Process completed' | head -40
# 3. Read the workflow YAML that owns the failing job
gh api 'repos/OWNER/REPO/contents/.github/workflows/<file>.yml?ref=main' \
-H 'Accept: application/vnd.github.raw'
# 4. Cross-reference with issue body (always read the actual issue body, not the summary)
gh issue view N -R OWNER/REPO --json title,body,labels
# 5. Verify every file path mentioned in the issue actually exists on main
# (issue tables often cite stale paths after a rename or repo restructure)
gh api 'repos/OWNER/REPO/git/trees/main?recursive=1' \
| python3 -c "import json,sys; d=json.load(sys.stdin); print('\n'.join(e['path'] for e in d['tree'] if e['path'].endswith('.src')))"
# 6. Fetch each surviving file with raw endpoint + sed to the exact lines
gh api 'repos/OWNER/REPO/contents/<path>?ref=main' -H 'Accept: application/vnd.github.raw' | sed -n '20,32p'
Output shape
The deliverable is a Markdown report in ~/docs/system/<repo>-ci-diagnose-<date>.md with these sections:
- TL;DR table — CI-Workflow / Helper-Skript / Issue A / Issue B / real root cause
- Which jobs fail? — full job graph + which step inside each failing job, distinguishing "skipped because
needs:" vs "actually failed" - Root-cause analysis — split into "actual CI killer" + "outdated issues that name the wrong files"
- Concrete fix proposals — patch-style diff snippets for each, ranked P0/P1/P2
- Verification commands — what to run after the fix to confirm green
- Issue comment drafts (do NOT post unless asked) — wording the user can copy into the issue thread
- Repro commands — copy-pasteable for next session
Always footer the report with **Analyse-Modus:** read-only (gh-CLI + GitHub-API only, keine Code-Mutation) so it's clear no writes happened.
Pitfalls — these all bit on 2026-07-07 Toqsick/greyscripts triage
gh api …/contents/<path>?ref=main with Accept: application/vnd.github.raw returns empty body for paths that don't exist — looks like a successful empty response, not an error. Combine with git/trees/main?recursive=1 to verify path existence first; if the tree lists the path, the empty body means a different branch or a renamed file. Verified pattern: bin/ps.src from Issue #43 was a stale path — the file lived under greyhack-tools/ps/ps.src (and had already been fixed). Tree-API before raw fetch = zero wasted fetches.
gh api …/contents/<path> (no Accept: raw header) returns JSON with content_base64 field — NOT content. Earlier docs and Stack Overflow snippets say base64.b64decode(d['content']). That field doesn't exist on the Contents API — it's content_base64. Piping JSON to python3 -c "import json,sys,base64; print(base64.b64decode(json.load(sys.stdin)['content']))" returns KeyError. Use content_base64 or, better, switch to the raw endpoint to avoid the dance entirely.
JSONDecodeError "Extra data: line 1 column 128" from python3 -c "json.load(sys.stdin)" — means gh api output got piped into something and gh wrote two JSON-like blocks to stdout (the API response + a status/log line). Switch to the raw endpoint (-H 'Accept: application/vnd.github.raw') to skip the JSON wrapper entirely. Do not try to "fix" the JSON parser — the problem is the wrapper.
needs:-chain jobs are skipped, not failed. When job 1 fails with exit 1, job 2 (which has needs: job-1) shows as "skipped" in the run summary. Don't trust "skipped" as a green signal — trace back to find which upstream job actually failed. The "real" CI killer is often job 1, not the job the issue title names. Verified: Toqsick/greyscripts issue #30 said "Greybel build failt" but the actual red job was lint-yaml (yamllint default rules vs. no override) → greybel-build was only skipped.
Stale issue tables — verify before fixing. Issue bodies often contain tables with | Datei | Zeile | listings. Before patching any file at the listed line, verify the file exists at the listed path on the current main and the line still contains what the issue claims. Repos rename directories, move files into core/ or lib/ subfolders, and earlier bug-sweep commits fix issues without closing them. Treat issue tables as hypotheses until verified against git/trees/main?recursive=1 + raw file fetch. Verified: Issue #43 listed 5 bin/ps.src:24-style sites — none of those paths existed on main (bin/ was reduced to .gitkeep). The real fixes lived under greyhack-tools/ and were already applied.
Read existing helper scripts before flagging "missing tooling". A repo may already have a helper script (e.g. lint-workflows.sh) that the CI workflow simply doesn't call. The diagnosis is "wrong wiring", not "missing tool". Check .github/workflows/lint-*.sh and scripts/ci-*.sh first. Verified: Toqsick/greyscripts had lint-workflows.sh with the correct yamllint override — ci.yml just didn't invoke it.
exit_code: 2 at the end of gh run view … --log-failed is normal. The run failed (that's why you're reading the log). Don't report this as a new error.
process.completed with exit code 1 ≠ test failures inside the job. GitHub Actions reports the step exit code as the job exit code. Look for ##[error] markers in the log to find which command actually returned non-zero.
When the real cause is upstream tooling, not the issue
A common pattern: issue A says "X is broken", issue B says "Y is broken", but the CI run they both point to failed in a completely different job (lint-yaml, setup-node, setup-python). Steps to take:
- State explicitly: "Issue #A beschreibt X. Realer Fail-Stand ist Y (anderer Job, andere Ursache)." — don't bury the lede.
- For each cited issue, check whether the cited fix would even be observable in the failing CI run. Often the cited failure mode is downstream of an upstream block.
- Propose P0 fix for the actual CI killer (usually a 1-line workflow edit), then P1+ for the issue's original concern.
- Suggest the issue gets a comment with status update rather than being closed prematurely.
See references/ci-failure-diagnosis.md for a worked example: Toqsick/greyscripts Issue #30 + #43 (yamllint override mismatch + stale issue tables).
Cron Monitoring
set -euo pipefail
# Daily status check
hermes cronjob create \
--schedule "0 9 * * *" \
--name "repo-daily-status" \
--prompt "Check git status, open issues, open PRs. If nothing changed: [SILENT]"
See references/github-automation-patterns.md for the full cron prompt template and [SILENT] protocol.
References
references/github-auth.md— Auth setup (HTTPS, SSH, gh CLI, API detection)references/github-pr-workflow.md— PR lifecycle (branch, commit, CI, merge)references/github-code-review.md— Code review (local, PR, inline)references/github-issues.md— Issue managementreferences/github-repo-management.md— Repo management (clone, create, fork, releases, secrets, actions)references/github-automation-patterns.md— Automation scripts, clean JSON output, cron jobs, shell escapingreferences/greybel-ci-pattern.md— GreyHack/Greybel CI build verification patterns and pitfallsreferences/greyhack-greybel-ci.md— Session-specific GreyHack Greybel CI reference forToqsick/greyscriptsreferences/documentation-health-audit.md— Repo documentation audit: count verification, standalone dep check, thin READMES detection, category cross-reference (2026-06-25)references/push-audit-research.md— "Was wurde kürzlich gepusht?"-Recherche:git ls-remoteals Ground Truth, MCP-401-Triangulation,gh api-Fallbacks, Diagnosetabellen für private/public Repos (2026-07-04)references/batch-contributing-md-push-2026-07-07.md— Session-Referenz: Batch-Push via Contents API über 4 Repos inkl. 409 stale-SHA-Pitfall, MD5-Verifikation, Domain-Template-Reusability-Lesson (2026-07-07)references/mcp-github-quirks-batch-push-2026-07-07.md— MCP-Tool-Antwort-Fallen:create_or_update_file"already exists"-Lügen,get_file_contents-Sentinel-SHA, "unreachable after 3 failures"-Cooldown; curl-Fallback mitgh auth token; 4-Repo-Contents-API-Push (2026-07-07)references/ci-failure-diagnosis.md— Session-Referenz: Read-only CI-Diagnose Issue #30 + #43 auf Toqsick/greyscripts (yamllint-Override-Mismatch als Root-Cause, stale issue-table Pfade via tree-API verifiziert,needs:-Skip-Chain, 1-Zeilen-Patch macht beides grün) (2026-07-07)