Cleanup GitHub

Progressive audit and cleanup of GitHub accounts with user approval before any destructive actions.

Overview

This skill audits a GitHub account for:

• Failing workflows and misconfigured security scanning
• Stale forks with no custom changes
• Orphaned secrets not used by any workflow
• Dependabot and security configuration
• Dependabot alert triage — trace alerts to source, prune unused deps, upgrade transitive deps

Workflow: Audit all categories → Present findings → Get approval → Execute cleanup

Prerequisite: gh auth status must pass.

When to Use

• "clean up my GitHub" / "audit my repos"
• "check for stale forks" / "orphaned secrets"
• "GitHub hygiene" / "repo cleanup"
• "Dependabot trouble" / "fix Dependabot alerts" / "unused deps"
• Investigating failing GitHub Actions
• Periodic account maintenance

When NOT to Use

• Creating new repos or workflows
• Managing issues or PRs
• CI/CD pipeline setup
• Repository content changes

Execution Modes

Full Audit (default)

Run all phases, present consolidated findings.

Quick Check

Focus on failing workflows and obvious issues only.

quick check my GitHub

Targeted Audit

Focus on specific category:

check for stale forks
check for orphaned secrets
check failing workflows
triage Dependabot alerts
audit deps across my repos

Phase Workflow

Phase 0: Prerequisites

Verify gh CLI and detect username:

gh auth status
GH_USER=$(gh api user --jq '.login')
echo "Auditing GitHub account: $GH_USER"

Verify username matches auth: The GH_USER variable can be shadowed by env vars or stale shells. Cross-check:

AUTH_USER=$(gh auth status 2>&1 | grep 'account' | awk '{print $NF}' | tr -d '()')
[ "$GH_USER" = "$AUTH_USER" ] && echo "Username verified: $GH_USER" || echo "MISMATCH: API=$GH_USER Auth=$AUTH_USER — investigate before proceeding"

Count repos for expectations:

gh repo list $GH_USER --limit 1000 --json name --jq 'length'

Phase 1: Failing Workflows Audit

List all repos with workflows:

# Using bash to iterate (gh CLI doesn't have built-in cross-repo workflow listing)
/bin/bash -c 'for repo in $(gh repo list GH_USER --limit 100 --json name --jq ".[].name"); do
  workflows=$(gh workflow list --repo "GH_USER/$repo" 2>/dev/null)
  if [ -n "$workflows" ]; then
    echo "=== $repo ==="
    echo "$workflows"
  fi
done'

Check CodeQL default setup (NOT a workflow file!):

gh api repos/GH_USER/REPO/code-scanning/default-setup --jq '.state'

Key insight: CodeQL "default setup" is configured via GitHub Security settings, not workflow files. The API endpoint is code-scanning/default-setup, not workflows.

Check recent workflow runs for failures:

gh run list --repo GH_USER/REPO --limit 5 --json status,conclusion,name \
  --jq '.[] | select(.conclusion == "failure") | "\(.name): \(.conclusion)"'

Phase 2: Stale Forks Audit

List all forks:

gh repo list GH_USER --fork --json name,parent --jq '.[] | "\(.name) (fork of \(.parent.nameWithOwner // "unknown"))"'

Compare fork to upstream:

gh api repos/GH_USER/REPO/compare/UPSTREAM_OWNER:main...GH_USER:main \
  --jq '{ahead: .ahead_by, behind: .behind_by}'

Flag candidates for deletion:

• ahead_by: 0 = No custom changes
• behind_by: N = Stale (upstream has moved on)

Present finding:

REPO: 0 commits ahead, 445 behind upstream
→ Recommendation: DELETE (no custom changes, very stale)

Phase 3: Orphaned Secrets Audit

List secrets per repo:

gh api repos/GH_USER/REPO/actions/secrets --jq '.secrets[].name'

Cross-reference with workflow files:

# Get workflow file content and search for secret references
gh api repos/GH_USER/REPO/contents/.github/workflows --jq '.[].name' | while read file; do
  gh api "repos/GH_USER/REPO/contents/.github/workflows/$file" --jq '.content' | base64 -d | grep -o 'secrets\.[A-Z_]*'
done | sort -u

Flag orphaned secrets:

• Secret exists but not referenced in any workflow
• Present for user review (secrets are sensitive - never auto-delete)

Phase 4: Security Config Audit

Check Dependabot:

# Check for dependabot.yml
gh api repos/GH_USER/REPO/contents/.github/dependabot.yml 2>/dev/null && echo "Dependabot configured"

# Check vulnerability alerts status
gh api repos/GH_USER/REPO/vulnerability-alerts 2>/dev/null && echo "Alerts enabled"

Check code scanning status:

gh api repos/GH_USER/REPO/code-scanning/default-setup --jq '{state: .state, languages: .languages}'

Phase 4b: Dependabot Alert Triage

Phase 4 checks if Dependabot is configured. This phase triages actual alerts by tracing them to their source and recommending the right fix: prune unused deps (preferred) or upgrade lock files.

Mental model: pyproject.toml/package.json is the shopping list (direct deps). The lock file is the trolley (everything installed, including transitive deps). Dependabot scans the trolley. Unused items on the shopping list are pure waste — they expand the attack surface and drag in transitive deps you don't need.

Step 1: Scan all repos for open alerts

# Only count real alerts (JSON arrays), not 403 errors (JSON objects)
for repo in $(gh repo list GH_USER --limit 200 --json name --jq ".[].name"); do
  result=$(gh api "repos/GH_USER/$repo/dependabot/alerts?state=open" 2>/dev/null)
  count=$(echo "$result" | python3 -c "
import sys,json
d=json.load(sys.stdin)
print(len(d) if isinstance(d, list) else 0)
" 2>/dev/null)
  if [ "$count" != "0" ] && [ -n "$count" ]; then
    echo "=== $repo ($count) ==="
    echo "$result" | python3 -c "
import sys,json
for a in json.load(sys.stdin):
    sev = a.get('security_advisory',{}).get('severity','?')
    pkg = a.get('dependency',{}).get('package',{}).get('name','?')
    eco = a.get('dependency',{}).get('package',{}).get('ecosystem','?')
    manifest = a.get('dependency',{}).get('manifest_path','?')
    fix = a.get('security_vulnerability',{}).get('first_patched_version')
    fix_v = fix.get('identifier','no fix') if fix else 'no fix'
    print(f'  [{sev:6s}] {pkg} ({eco}) via {manifest} -> fix: {fix_v}')
"
  fi
done

Key gotcha: Repos with Dependabot disabled return HTTP 403 with a JSON error object (3 string fields). Naive JSON length-counting mistakes this for "3 alerts". Always check isinstance(d, list).

Step 2: For each repo with alerts, audit direct deps

For Python repos (pyproject.toml + uv.lock):

# 1. List declared deps
grep -A 50 '^\[project\]' pyproject.toml | grep -A 50 'dependencies' | head -20

# 2. Find all third-party imports in source
grep -rn "^import \|^from " src/ tests/ *.py 2>/dev/null | grep -v "from \." | sort -u

# 3. Compare — any declared dep with zero imports is a removal candidate

For Node repos (package.json + package-lock.json):

# 1. List declared deps
jq '.dependencies, .devDependencies' package.json

# 2. Find all third-party imports in source
grep -rn "from ['\"]" src/ --include="*.ts" --include="*.tsx" --include="*.js" | grep -v "from ['\"]\." | sort -u
grep -rn "require(['\"]" src/ scripts/ --include="*.js" | sort -u

Step 3: Categorise each alert

Prefer removal over upgrade. Removing an unused dep is a permanent fix. Upgrading a lock file is a point-in-time fix — new CVEs will trigger new alerts against the same transitive chain.

Step 4: Execute fixes

For Python repos:

# Remove unused dep from pyproject.toml (edit manually)
# Then regenerate and sync:
uv lock --upgrade
uv sync
# Run tests if they exist:
uv run pytest 2>/dev/null || echo "No tests"

For Node repos:

# Remove unused dep:
npm uninstall PACKAGE_NAME
# Or edit package.json then:
npm install
# Run tests:
npm test 2>/dev/null || echo "No tests"

Step 5: Commit and push per-repo

git add pyproject.toml uv.lock  # or package.json package-lock.json
git commit -m "Remove unused deps, upgrade transitive deps

[describe what was removed and why]

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
git push

Important: GitHub's Dependabot scanner runs asynchronously after push. Alerts take a few minutes to clear. Don't wait — verify by checking the lock file no longer contains the vulnerable version.

Anti-patterns for this phase:

Phase 4c: General Dependency Hygiene

Phase 4b is reactive (triggered by Dependabot alerts). This phase is proactive — sweep all local repos for unused or missing deps regardless of whether they've triggered alerts. Unused deps that haven't caused a CVE yet are still dead weight: slower installs, larger attack surface, unnecessary transitive trees.

Scope: All repos in ~/Repos with a pyproject.toml or package.json.

Step 1: Find all repos with dependency manifests

echo "=== Python ===" && find ~/Repos -maxdepth 2 -name "pyproject.toml" -not -path "*/.*" | sort
echo "=== Node ===" && find ~/Repos -maxdepth 2 -name "package.json" -not -path "*/node_modules/*" -not -path "*/.*" | sort

Step 2: For each repo, compare declared vs imported

Use parallel Opus subagents (one per repo) for speed. Each agent should:

1. Read the dependency manifest
2. Search all source files for third-party imports
3. Report two lists:
   • Declared but not imported (removal candidates)
   • Imported but not declared (fragile transitives to promote)

Python pattern:

# Declared deps
grep -A 20 'dependencies' pyproject.toml

# Actual imports (exclude stdlib and relative)
grep -rn "^import \|^from " src/ tests/ *.py 2>/dev/null | grep -v "from \." | sort -u

Node pattern:

# Declared deps
jq '.dependencies, .devDependencies' package.json

# Actual imports
grep -rn "from ['\"]" src/ --include="*.ts" --include="*.tsx" --include="*.js" | grep -v "from ['\"]\." | sort -u

Step 3: Categorise findings

Nuance on "runtime engines": Some packages are never import-ed but are loaded at runtime by other packages. Common examples:

• openpyxl — pandas Excel engine (pd.read_excel() loads it internally)
• lxml — BeautifulSoup parser (BeautifulSoup(html, 'lxml'))
• kaleido — Plotly static export (fig.write_image())
• pytest-asyncio — pytest plugin (loaded via pytest plugin discovery)

Grep for string references like 'lxml', 'openpyxl', write_image to verify these before removing.

Step 4: Execute fixes, commit per-repo, push

Same as Phase 4b execution steps. Present findings to user before making changes.

Phase 5: "What Did We Miss?" Checklist (MANDATORY)

This phase is NOT optional. Run through the comprehensive checklist before presenting final findings.

See references/audit-checklist.md for the full checklist.

Quick sweep:

# Check for local clones that might have stale remotes
find ~/Repos -maxdepth 2 -name ".git" -type d 2>/dev/null | while read gitdir; do
  repo=$(dirname "$gitdir")
  remote=$(git -C "$repo" remote get-url origin 2>/dev/null)
  # Check if remote points to any repo we're considering deleting
  echo "$repo: $remote"
done

Items to verify:

• Local clones with stale remotes (to repos being deleted)
• GitHub Apps installations
• Deploy keys per repo
• Webhooks
• Collaborators on personal repos

Phase 6: Cleanup Execution

Present consolidated findings:

## Audit Summary

### Stale Forks (delete)
- repo1 (0 ahead, 200 behind)
- repo2 (0 ahead, 50 behind)

### Orphaned Secrets (delete)
- repo3: SECRET_NAME (not referenced)

### Failing Workflows (disable or fix)
- repo4: CodeQL misconfigured for wrong language

### Local Clone Check
- No local clones found for repos being deleted

Use AskUserQuestion for approval:

Which cleanup actions should I perform?
[ ] Delete stale forks (2)
[ ] Delete orphaned secrets (1)
[ ] Disable failing workflows (1)

Execute approved actions:

# Delete fork (requires delete_repo scope)
gh repo delete GH_USER/REPO --yes

# Delete secret
gh api repos/GH_USER/REPO/actions/secrets/SECRET_NAME -X DELETE

# Disable CodeQL
gh api repos/GH_USER/REPO/code-scanning/default-setup -X PATCH -f state=not-configured

# Disable workflow
gh workflow disable "Workflow Name" --repo GH_USER/REPO

Verify after cleanup:

# Confirm repo deleted
gh repo view GH_USER/REPO 2>&1 | grep -q "not found" && echo "Confirmed deleted"

# Confirm secret deleted
gh api repos/GH_USER/REPO/actions/secrets --jq '.secrets[].name' | grep -v SECRET_NAME

Quick Reference

Essential Commands

Scope Requirements

Anti-Patterns

References

• gh-cli-patterns.md - Complete CLI reference with jq patterns
• audit-checklist.md - Comprehensive "what did we miss?" checklist
• cleanup-operations.md - Safe patterns for destructive operations