github-guardian

name: github-guardian description: Diagnose and repair GitHub authentication, credential helpers, and repo sync state. The go-to skill when any backup or push operation fails. version: 2.0.0 author: repo-man tags: [github, auth, repair, credential-helper, self-healing]

github-guardian

Purpose

Diagnose and fix GitHub connectivity problems — broken auth tokens, dead credential helper paths, and repo sync drift. This is the repair skill that other skills call when they encounter push failures. It follows a non-destructive protocol: never force-push, never reset history, never delete commits.

When to use

• Any backup skill reports "push failed" or "authentication failed"
• /repo-health shows unreachable repos or HTTP 401
• After container rebuilds (credential helper paths change)
• After OpenClaw updates (image may have different binary locations)
• When gh auth status shows "not logged in"
• When /key-drift-check reports GH_TOKEN missing

Invoke

/github-guardian

Steps

Phase 1: Preflight diagnosis

Collect the evidence first. Run ALL of these before attempting any fix.

# 1a. gh CLI exists and is functional
gh --version

• If "command not found": gh CLI is not installed in the container. This is catastrophic for all GitHub operations. ERROR MEANING: The container image may have been rebuilt without gh. gh is installed at build time. HISTORY: This has never happened, but would require a Dockerfile fix (infra change — confirm with Robert). FIX: As root: docker compose exec --user root openclaw-gateway sh -c "apt-get update && apt-get install -y gh" (temporary — will vanish on next rebuild).

# 1b. Auth status
gh auth status 2>&1

• If "Logged in to github.com": Auth is working. Problem is elsewhere.
• If "not logged in": GH_TOKEN is missing or expired. ERROR MEANING: The GH_TOKEN env var is how gh authenticates. It's injected from /root/openclaw/.env via docker-compose env_file. FIX: Check inside container: echo $GH_TOKEN | head -c 10 (should show ghp_). If empty, check docker-compose.override.yml has env_file: [.env].

# 1c. Git credential helper
git config --global --get-all credential.https://github.com.helper

Required value: !/home/node/.openclaw/scripts/gh auth git-credential

• If empty: Credential helper was never set or got cleared.
• If points to /usr/bin/gh or another path: Dead path after container rebuild. ERROR MEANING: Git uses this helper to authenticate pushes. If it points to a binary that doesn't exist in the current container image, every git push fails with "authentication failed" — a misleading error that looks like a token problem but is actually a path problem. HISTORY: Broke on 2026-05-10 after v2026.5.8 update rebuilt the image. The gh binary moved paths. FIX: Set the correct helper (see Phase 2).

Phase 2: Repair

Apply fixes based on Phase 1 findings. Minimum-change principle — fix only what's broken.

Fix: Credential helper

git config --global credential.https://github.com.helper '!/home/node/.openclaw/scripts/gh auth git-credential'

Fix: GH_TOKEN missing in container This requires host-side action — the token comes from docker-compose env injection:

1. Verify on host: grep GH_TOKEN /root/openclaw/.env (should exist)
2. Verify override: grep env_file /root/openclaw/docker-compose.override.yml (should reference .env)
3. If both present, restart container to re-inject: docker compose restart openclaw-gateway

Phase 3: Safety checks (history protection)

For each repo (openclaw-config, openclaw-workspace, openclaw-skills):

git -C /home/node/.openclaw/repos/<repo> status -sb
git -C /home/node/.openclaw/repos/<repo> rev-list --left-right --count origin/main...main

Interpret the rev-list output L R:

• 0 N — local is N commits ahead. Safe to push.
• N 0 — remote is N commits ahead. Do a git pull --rebase first.
• N M — DIVERGED. Pause and escalate with exact counts.

Rules:

• NEVER git reset --hard for sync recovery
• NEVER force-push backup history unless Robert explicitly approves
• Prefer git push origin main (simple push)
• If diverged: pause and escalate with the exact divergence counts and a proposed merge/rebase plan

Phase 4: Verify repair

Test one repo push first, then apply fleet-wide.

# Pick one repo as canary
git -C /home/node/.openclaw/repos/openclaw-workspace push origin main 2>&1

• If success: Apply same fix to remaining repos.
• If "authentication failed": Credential helper fix didn't take. Re-check Phase 1c.
• If "rejected (non-fast-forward)": Diverged history. Go back to Phase 3.

Then verify all repos:

for repo in openclaw-config openclaw-workspace openclaw-skills; do
  echo "=== $repo ==="
  git -C "/home/node/.openclaw/repos/$repo" rev-parse main
  git -C "/home/node/.openclaw/repos/$repo" rev-parse origin/main
  git -C "/home/node/.openclaw/repos/$repo" status -sb
done

Success = local and remote SHAs match on main, and status shows no ahead/behind drift.

Phase 5: Audit log

/home/node/.openclaw/scripts/log-event.sh INFO github-guardian "Repaired: <what was broken>. Verified: <evidence>"

Error diagnosis

Completion report

[Repo-Man] github-guardian: <PASS/PARTIAL/FAIL>
  Credential helper: <OK/FIXED/MISSING>
  Auth: <OK/FIXED/EXPIRED>
  Repo sync:
    openclaw-config: <OK/AHEAD N/DIVERGED>
    openclaw-workspace: <OK/AHEAD N/DIVERGED>
    openclaw-skills: <OK/AHEAD N/DIVERGED>
  Risk: <none / description of remaining issues>

Related

• /backup-suite — calls this when any backup push fails
• /repo-health — detects the problems this skill fixes
• /key-drift-check — GH_TOKEN is one of the keys it monitors
• /github-flight-recorder — deeper forensics if guardian can't diagnose the issue
• chart search "github auth" — history of auth repairs
• chart read learning-override-rollback-safety — env var injection failures

Notes

• This skill is referenced by nearly every other Repo-Man skill as the "fix auth" runbook. Keep it authoritative.
• The credential helper path !/home/node/.openclaw/scripts/gh auth git-credential is specific to this container layout. If container paths change (e.g., user changes from node to something else), this path must be updated everywhere.
• After container rebuilds, always run this skill as a preflight check before any backup operation.

Intent: Recoverable [I15], Secure [I16].