GitHub Platform

Branch, commit and pull request conventions: the git-workflow skill. Docs: https://docs.github.com/en/pull-requests

The MCP server

GitHub's own remote server, https://api.githubcopilot.com/mcp/. VS Code signs in with OAuth. Every other assistant sends GITHUB_PERSONAL_ACCESS_TOKEN, so the server acts as that token's user — call get_me first to know whose name every comment will carry. Tool names change between releases: read the tool list the server offers instead of assuming a name.

• Toolsets. On by default: context, repos, issues, pull_requests, users. An X-MCP-Toolsets header on the server entry turns on more (actions for CI logs), and X-MCP-Readonly: true drops every write tool.
• Token. Fine-grained and limited to the repositories the agents work in: Contents, Pull requests and Issues read and write, Metadata and Actions read. A 404 on a repository you know exists is the token: its repository list, or an organization that has not approved it.
• gh covers the rest: review threads, job logs and stacks, below. It signs in on its own (gh auth status).

Gotchas

• A review is pending until submitted. Comments added to a pending review are invisible to everyone else, and a session that ends before the submit leaves them unsent.
• Why a PR cannot merge: gh pr view 42 --json mergeStateStatus. BEHIND needs a rebase onto its base, DIRTY has conflicts, BLOCKED lacks a required review or check, UNSTABLE has a non-required check failing.
• A person merges, as git-workflow says. Stop at a reviewed PR with green checks, though both the server and gh offer a merge.
• Open a draft while work remains (gh pr create --draft) and mark it ready when it is done (gh pr ready 42). Closes #123 in the body closes the issue only when the PR merges into the default branch.
• In a review comment, a ```suggestion block replaces the commented lines when the author applies it. Use it for any fix that fits those lines.
• Search allows 30 requests a minute. Narrow with repo: and is:open rather than paging.

Review threads

The REST API returns review comments without saying which are resolved. GraphQL says.

1. List the threads:

   gh api graphql -F owner='{owner}' -F repo='{repo}' -F pr=42 -f query='
     query($owner: String!, $repo: String!, $pr: Int!) {
       repository(owner: $owner, name: $repo) { pullRequest(number: $pr) {
         reviewThreads(first: 100) { nodes { id isResolved isOutdated path line
           comments(first: 20) { nodes { databaseId author { login } body } } } } } } }'

2. Fix what each unresolved thread asks, then commit and push. An isOutdated thread sits on code that has since changed: check that its point still applies.

3. Reply in the thread with what changed: gh api repos/{owner}/{repo}/pulls/42/comments/<databaseId>/replies -f body='Fixed in <sha>: …'

4. Resolve it: gh api graphql -F id=<thread id> -f query='mutation($id: ID!) { resolveReviewThread(input: {threadId: $id}) { thread { isResolved } } }'

Done when step 1 shows every thread you fixed as resolved. A point you disagree with gets a reply and stays open for the reviewer.

Failing checks

1. gh pr checks 42 lists every check on the head commit. --watch --fail-fast waits, and stops at the first failure.
2. Read the failure with gh run view <run-id> --log-failed, which prints only the failed steps (the run ID is in the check's link). Start at the first error, not the last line.
3. Reproduce it with the command the step ran, fix it, and push. Done when gh pr checks 42 passes on the new head commit.
4. If your diff cannot explain the failure, run gh run rerun <run-id> --failed once. A second failure is real.

Causes no log names:

• A push made with GITHUB_TOKEN inside a workflow starts no other workflow, so a bot's commit gets no checks. Push with a GitHub App token or a personal token when it needs them.
• A required check whose workflow is skipped by a paths filter never reports, and the PR waits for it forever. Run the job and exit early instead.
• A PR from a fork runs pull_request workflows with a read-only token and no secrets. pull_request_target has both and runs the base branch's workflow, so checking out the PR's code there runs it with your secrets.
• Set permissions: on each workflow rather than inheriting the repository default, which is read and write on older repositories.

Stacked pull requests

A change too big for one review becomes a stack: a chain of layers, each its own PR on the branch below, with the bottom one on trunk (the default branch). Dependencies point down: shared types and schema at the bottom, the code that uses them above. Each PR is held to trunk's required reviews and checks, so every layer builds and passes CI on its own. With agents, one task per layer.

The gh stack extension does the bookkeeping: gh extension install github/gh-stack. Name every branch on the command line, because a bare command opens a prompt.

1. gh stack init feat/search-01-schema, then commit the first layer.
2. For each next layer, from the top one: gh stack add feat/search-02-api, then commit.
3. gh stack push, then gh stack submit --auto. This opens one draft PR per branch, each based on the one below, linked as a stack. Give each its title and body with gh pr edit <n> --title "…" --body-file <file>. Done when gh stack view --json lists every branch with its PR.
4. To change a lower layer: gh stack checkout feat/search-01-schema, commit, then gh stack rebase --upstack, gh stack push and gh stack top.
5. After a layer merges, gh stack sync --prune rebases what remains onto trunk, pushes, and deletes the merged branches.

• Merges go bottom up, and a person does them. Merging a PR merges every layer below it.
• History stays linear. Rebase rather than merging trunk into a layer, and push with gh stack push, which uses --force-with-lease per branch.
• A stack lives in one repository; it cannot span forks.
• Exit code 3 is a rebase conflict: resolve it, git add, then gh stack rebase --continue, or --abort to restore every branch.
• Exit code 9 means stacks are not enabled for this repository. Open each PR by hand with gh pr create --draft --base <branch below>. After a layer is squash-merged, rebase the next one with git rebase --onto origin/main <merged branch> <next branch> so the squashed commits are not replayed.