Github Contribution Workflow

GitHub Contribution Workflow

The gh-CLI contribution loop for an agent acting on a GitHub repo: branch → commit → PR → CI → merge, plus issues, GitHub-side file ops, repo secrets, and contribution-flow repo settings. Encodes conventions that keep an agent's contributions reviewable and consistent. Tool-agnostic in spirit; concrete commands are gh + git.

Native mechanism

Claude Code's Hooks can intercept and block a tool call before it runs — e.g. a PreToolUse hook matching Bash can deny a git push --force or a bare rm -rf. Hooks enforce a hard gate at the tool layer; the --no-verify rule and CLEAN-before-merge convention below are conventions this skill asks the agent to follow voluntarily where no hook exists to enforce them.

When to invoke

• Opening or merging a PR; opening or commenting on an issue.
• Creating or editing a file through GitHub (API / web flow) rather than a local clone.
• Setting a repo secret or configuring contribution-flow repo settings.
• Checking CI status before a merge; bumping a submodule pin.
• User says "open a PR / issue", "merge this", "set the secret", "configure the repo".

Scope — what this does NOT own (route to sibling)

• Verifying the diff matches the commit's claims before push/PR → pr-diff-verification.
• Security repo settings (Secret Scanning, push protection, gitleaks, .gitignore baseline) → apple-dev-skills:apple-public-repo-security.
• Parallel-session / submodule worktree conflicts → subagent-conflict-detection.
• Distributing or installing skill plugins (marketplace, depth-1 rule) → claude-skill-plugin-packaging.
• Pure local git with no GitHub surface → out of scope.

Intent → command

Conventions

• Branch names use Conventional-Commits-style type prefixes (house convention, not a named spec): feat/ fix/ chore/ docs/ ci/ refactor/ test/.
• PR titles follow Conventional Commits (some repos enforce this with a CI gate — e.g. a "Validate PR title" check; a non-conforming title fails the PR).
• Commit trailer: end commit messages with the agreed Co-Authored-By: trailer. PR body: end with the 🤖 footer.
• Merge: --squash --delete-branch. Never merge unless mergeStateStatus is CLEAN — gh pr checks itself never prints CLEAN; that's a gh pr view --json mergeStateStatus value, not a gh pr checks state. Use gh pr checks <n> --watch to wait for checks (exit 0 = all pass, exit 8 = still pending, any other non-zero = a check failed). BLOCKED covers more than pending checks — it also covers a failed required check, a missing review, or an unresolved conversation — so don't poll it indefinitely assuming it will clear on its own; also watch for UNSTABLE (a non-required check failing) and BEHIND (branch needs updating against base).
• Secrets: gh secret set <NAME> without --body — a literal --body "$TOKEN" exposes the value in process args (ps) and in this harness's Bash-tool transcript, and if typed literally (not as $TOKEN) also lands in shell history. Use the interactive prompt or gh secret set NAME < file. Verify presence (not value) with gh secret list.
• Submodule pin bump: set the gitlink surgically with git update-index --cacheinfo 160000,<commit-sha>,<submodule-path> — no submodule checkout needed (works in a fresh worktree). Confirm the target SHA is pushed/tag-reachable on the submodule's remote first (git ls-remote --tags <url> <tag>).
• --no-verify: allowed ONLY for a commit with no code and no secrets (a submodule-pin bump, a .gitmodules/config-only change) when the repo's pre-commit gate is heavy and times out. git commit --no-verify skips both the pre-commit and commit-msg hooks (a commitlint-style message check is bypassed too — double-check the message format by hand); git push --no-verify separately skips pre-push. Never use either for code or content commits — those must pass the hooks.
• Shared repo / submodule: edit via an isolated worktree branched from origin/main + PR, never in place — see subagent-conflict-detection.

Repo settings (contribution-flow only)

This skill owns the contribution-flow repo config: merge-button policy (allow_squash_merge, delete_branch_on_merge), branch protection requiring CI, required status checks, and labels. Security settings (Secret Scanning, push protection) are owned by apple-dev-skills:apple-public-repo-security — set them there, not here.

Common Mistakes

1. Merging on a non-CLEAN mergeStateStatus — assuming BLOCKED only ever means pending checks and polling it forever, or force-merging past a real red check. Use gh pr checks <n> --watch plus mergeStateStatus; merge only on CLEAN.
2. gh secret set --body "$TOKEN" — exposes the value in process args and the tool transcript (and, if typed literally, shell history too). Use the interactive prompt or gh secret set NAME < file.
3. Non-Conventional PR title — fails a repo's title-lint gate; the PR can't merge.
4. Editing a shared repo / submodule in place — two writers clobber each other; use a worktree + PR.
5. --no-verify on a code/content commit — bypasses the gate that protects the repo. Reserve it for no-code/no-secret commits only.
6. Hand-editing a submodule's checked-out files from the parent repo — bump the pin instead (git update-index --cacheinfo), and land the submodule's own change via its own PR.
7. Duplicating a sibling's job — re-doing diff verification, security settings, or worktree conflict checks here instead of routing to the owning skill.

Review Checklist

• Branch name uses a Conventional prefix; PR title is Conventional Commits.
• Commit carries the Co-Authored-By: trailer; PR body ends with the 🤖 footer.
• mergeStateStatus is CLEAN before merge (via gh pr checks <n> --watch + gh pr view <n> --json mergeStateStatus); merged with --squash --delete-branch.
• Any secret was set via interactive gh secret set (no --body); verified with gh secret list.
• A submodule bump used git update-index --cacheinfo against a remote-reachable SHA.
• --no-verify used only on a no-code/no-secret commit, with the reason stated.
• Shared-repo/submodule edits went through a worktree + PR.
• Nothing here duplicates a sibling skill's scope.

Related skills

• pr-diff-verification — verify git show --stat --summary HEAD matches the commit's claims before push/PR.
• apple-dev-skills:apple-public-repo-security — security repo settings + secret-leak prevention.
• subagent-conflict-detection — worktree + PR flow for parallel sessions / submodules.
• claude-skill-plugin-packaging — distributing/installing skill plugins.