GitHub Automation

Runtime selection (dual surface)

This skill supports two GitHub tool surfaces. Selection is per session, decided once by account eligibility, then kept:

How to decide: run the identity call — official github_get_me first. If the official surface is configured and returns a healthy identity, stay on it for the session. If the official server is missing, fails to connect, or returns 401/403/network errors (token problem or server down), switch to the own local surface (gh_get_me) for the session and do not retry the official one blindly — check the token via ./setup.sh. If a call fails mid-task, re-evaluate: switch that remaining task to the working surface and continue it there. Do not mix surfaces per call without cause — the switch is the fallback, not the default.

Coverage is not 1:1. The own local surface implements the workflows below with the gh_*/git_* equivalents, but some official github_* tools have no local equivalent and degrade to report-only (see Workflow equivalents).

Prerequisites

Own local surface (gh_* / git_*)

The gh-git-mcp server is a local FastMCP over the gh and git CLIs, wired to the runtime by setup.sh (multi-entry MCP block). Prerequisites:

• gh CLI ≥ 2.x installed and authenticated (gh auth login) — the server delegates all auth to gh; it never sees or embeds a token.
• git available on PATH.
• uv available (the server runs from the deployed copy at $HOME/.config/sdd-own/srv/gh-mcp-server via uv run --directory "$HOME/.config/sdd-own/srv/gh-mcp-server" python -m src.server).

The server exposes typed envelopes {ok, data, summary, error}. Destructive operations are two-phase: call the tool once to get the computed effect (dry-run), then confirm by echoing that exact data object back — all fields, verbatim, including the dry_run marker. The server re-derives the effect, fingerprints it (SHA-256), and executes only on a match. Never call a destructive tool with confirmed=true without a preceding dry-run echo-back.

Official surface (github_*)

This skill assumes the GitHub MCP server is configured for your runtime — normally via ./setup.sh (see the repository README, "GitHub MCP"). It uses the official GitHub MCP server (github/github-mcp-server).

This skill never handles credentials. Tokens live in $GITHUB_PERSONAL_ACCESS_TOKEN (for the runtime's process environment) or in the per-runtime 0600 env file ~/.config/sdd-own/github-mcp.env, provisioned by setup.sh. You never read, print, or write a token yourself. If a tool call needs the token and it is missing, tell the user to run ./setup.sh — do not ask for the secret in chat.

Tool Surface

The official server exposes idiomatic github_* tools. The constantly updated names matter here: always check the live tool list before automating (mcp__github__<server>__list_tools style discovery, or the server's tools listing) instead of hardcoding names from memory.

Families you operate:

Scope discipline: for pure read/analysis work prefer the readonly toolset if your runtime lets the MCP server run with it; for automation (create/add/review/merge/re-run) you need the full toolset. If a call fails with a permissions error, report whether the server is running in readonly mode — do not "work around" it with a second server.

Gating: issue triage and PR review act on what the queue shows, not on what you imagine. Always list → read → act, in that order.

Workflow equivalents (own local surface)

When running on the own local gh_*/git_* surface, the families map as follows. Read-only workflows are fully covered. Write/action workflows are covered where a local equivalent exists; unmappable actions degrade to report-only (tell the user what to do, never fake the action).

Rule: never fake an unmappable action. If a workflow needs a write the own surface cannot do (comment, labels, review), produce the exact gh CLI command or switch to the official surface for that single step, and say so.

Automation Workflows

Repository ops

• Confirm repo exists and its defaults (default_branch, visibility, topics) before scripting anything against it. github_get_repo first, always.
• Batch discovery uses github_list_repositories and github_search_repositories (lookahead on org/owner before assuming the repo lives where you think).

Issue triage ops

Order: github_list_issues (queue) → github_get_issue (detail: labels, assignees, linked PR) → github_add_issue_comment (follow-up, repro questions, labels) or signal to the human.

• Triage by root class, never one-by-one: if the same failure mode shows up across issues, name the class and let the fix shrink the system, not spawn per-issue patches.
• Linking an issue to a fixing PR (via commit message keywords like "Fixes #NN") is the standard chain — prefer it over manual close.

PR review/merge/status ops

• Status before review: github_get_pull_request + github_get_pull_request_status + github_get_pull_request_checks. A PR with red checks is a review-with-evidence, not a merge candidate.
• Review: read the actual diff intent via compare/list-files, then github_review_pull_request with comments tied to concrete lines. Approve only when the diff + checks + context line up; REQUEST_CHANGES needs the same evidence standard.
• Merge: only when checks are green AND the base branch is up to date. Prefer the merge method the repo's history uses (squash vs merge vs rebase) — check recent merged PRs before choosing.
• Chained/stacked PR review belongs to the branch-pr/chained-pr skills; here you operate status, checks, and merge.

Branch/commit ops

• Create branches only from the current default branch unless explicitly told otherwise. Name them scoped (<scope>/<slug>) to match repo convention.
• Delete branches only after confirming the work is merged (github_compare_commits default..branch) — never delete an unmerged branch on a guess.
• Commit history reads (github_list_commits/github_get_commit) serve review context: find what introduced a regression, then the fix lives in the code, not the history.

Actions ops

• Failed run evidence: github_list_workflow_runs → github_get_workflow_run → github_download_workflow_run_logs. The logs are the truth; never infer a failure from the run name.
• Re-running a failed, flaky run is legitimate (timing/transient), but two consecutive re-runs of the same job without a code fix is a signal: read the logs and diagnose instead.

Code-search ops

• github_search_code is the fastest "where is X" for public code; scope it with q=repo:owner/name when the target is a known repo.
• It is rate-limited harder than repo search — batch queries, and prefer github_get_file once you know the path.

Pitfalls

• Hardcoded tool names go stale. GitHub MCP renames/extends github_* tools; verify the live surface before every automation batch. On the own local surface the surface is fixed (gh_*/git_*) but still verify availability of a tool before assuming it exists.
• 403/401 from the official server is a token/config issue, not an account-plan issue. The official remote endpoint api.githubcopilot.com/mcp/ serves any GitHub account via a valid PAT; a 403 forbidden: access denied means an invalid or expired token, or the server entry missing "enabled": true in the runtime config. Fix the token via ./setup.sh (it asks, validates, and stores the PAT; never ask for the secret in chat) — do not switch surfaces on a clean auth failure. If the server is down/unreachable, fall back to the own local surface.
• Rate limits. Search and Actions calls burn budget fast. Read-heavy batches (reviewing many PRs) should run in the smallest number of calls that answer the question.
• Token in the wrong place. The token belongs ONLY in the runtime env ($GITHUB_PERSONAL_ACCESS_TOKEN, env file, or the runtime's own mechanism). Never inline it in tool input, logs, chat output, commits, or config files. The own local surface never sees a token at all.
• Reviewing without checks. Status/checks first, always. Approving a PR with a red check ships broken intent.
• Deleting on a guess. Branch deletion without a merged-check is how useful work gets lost.
• Skipping the echo-back. On the own local surface, a destructive confirmation must echo the exact dry-run data; guessing or hand-writing the confirmation data never executes safely.

Quick Reference

Own-surface pitfalls (additional)

• Do not mix surfaces. Decide once per session (identity call → what works), then stay consistent.
• Destructive echo-back is mandatory. confirmed=true without the exact dry-run data echo-back never executes — and neither should you attempt to bypass it.
• Unmappable writes are report-only. No local tool can post a comment, write labels, or submit a review; never pretend an action happened that did not.