# Github > Interact with GitHub via the `gh` CLI. Use for issues (read, comment, file), pull requests (view, comment, check CI status), workflow runs, and `gh api` for queries the subcommands don't cover. Authentication is via the bot's GITHUB_TOKEN (already wired through `gh auth setup-git` at container start). - Skill: `jasoncarreira/github` (Agent Skill) - Install (CLI): `npx skillmds@latest add jasoncarreira/github` - Raw SKILL.md: https://api.skillmd.com/api/skills/jasoncarreira/github/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: jasoncarreira (https://skillmd.com/u/jasoncarreira) - Updated: 2026-08-19 - Page: https://skillmd.com/skills/jasoncarreira/github --- # GitHub The `gh` CLI is installed in the container and authenticated via `GITHUB_TOKEN` from the env. Commits the agent makes through `git push` go through the same credential helper, so `gh pr create` and `git push` both work. ## Contract **Trigger**: Any interaction with GitHub that goes beyond local git — reading issues or PRs, filing comments, checking CI, querying the API. If the task requires GitHub state (not just local repo state), invoke this skill. **Requires**: `GITHUB_TOKEN` in environment (verified by `gh auth status`). The PAT's scope determines which repos are reachable — operations on out-of-scope repos return 403; check what the operator configured if you hit one. **Guarantees**: - GitHub interactions happen via `gh` CLI (authenticated, auditable), not via WebFetch on raw GitHub URLs. - PAT scope is checked mentally before any cross-repo operation — a 403 from an out-of-scope repo is expected behavior, not a bug. **Does not**: Push code (that's `git push`, separate from `gh`); manage GitHub Actions billing; access repos outside the PAT scope; file issues on external repos without operator approval. When `cwd` is inside a git checkout of the target repo, you don't need `--repo` — gh resolves the upstream remote from the local `origin`. When working from elsewhere or operating on a different repo, pass `--repo owner/repo` (or use a URL). ## Pre-merge CHANGES_REQUESTED gate (chainlink #214, rule via #217) **Before invoking `gh pr merge` on any PR, ALWAYS check the current review state.** A reviewer can flip to CHANGES_REQUESTED after the first approval — calling `gh pr merge` without a fresh check can merge a PR that has outstanding blocking feedback. ```bash # Returns the login list of blocking reviewers (empty array [] if none) BLOCKING=$(gh pr view --json reviews --jq ' [.reviews | group_by(.author.login)[] | sort_by(.submittedAt)[-1] | select(.state == "CHANGES_REQUESTED") | .author.login]') # Refuse if non-empty if [ "$BLOCKING" != "[]" ]; then # blocked — do not merge; see steps below echo "Merge blocked by CHANGES_REQUESTED from: $BLOCKING" fi ``` If `$BLOCKING` is non-empty (one or more reviewers in CHANGES_REQUESTED state): 1. **Refuse the merge** — do not call `gh pr merge`. 2. Post a `gh pr comment` explaining why the merge was blocked and listing the blocking reviewers from `$BLOCKING` who need to re-approve. This is a non-negotiable hard gate — not a heuristic. "Operator approved once" is not sufficient if a subsequent CHANGES_REQUESTED arrived, even seconds later. (Structured event emission for blocked merges is tracked in chainlink #218.) ## Pre-push staleness gate (chainlink #219) **Before pushing a PR branch for re-review, ALWAYS check that the branch is current against `origin/main`.** Between the last rebase and the next push, other PRs may have merged to `main`; a stale base makes the PR diff include complete reverts of unrelated landed work. A squash-merge would silently drop those commits from `main`. Exception: Worklink slice branches named `issue/-a` are based on their epic integration branch, and `epic/*` integration branches merge to main only through the single epic draft PR. Do not rebase those machinery branches directly onto `origin/main` for this gate. ```bash # Step 1: fetch and check staleness git fetch origin main MERGE_BASE=$(git merge-base HEAD origin/main) MAIN_TIP=$(git rev-parse origin/main) if [ "$MERGE_BASE" != "$MAIN_TIP" ]; then echo "Branch is stale — rebasing onto current origin/main" git rebase origin/main fi # Step 2: inspect paths in the diff after rebase git diff origin/main..HEAD --name-only ``` **If the rebase fails with conflicts** (i.e. `git rebase origin/main` returned non-zero), abort with `git rebase --abort` and stop — **do not push**. A failed rebase leaves the branch in an intermediate state where the subsequent diff and push are both unsafe. Resolve the conflicts manually (or request operator guidance) before re-running the gate from step 1. After fetching (and rebasing if stale), inspect the path list: - If every path is **within the PR's declared scope** (the chainlink ID, PR title, or known feature area), the push is safe — proceed. - If any path is **outside scope** (a revert of unrelated work, or an accidentally-staged file), stop — do not push. Investigate whether a further rebase is needed or whether a stale commit slipped onto the branch. **Non-negotiable rule**: do not push to a PR branch for re-review without this check. The cost of missing a stale base is silently reverting landed work when the PR is squash-merged. Pairs with the pre-merge gate above — both gates exist because the window between "last rebase" and "reviewer sees diff" is enough for main to advance. Four concrete instances from 2026-05-27 that this gate would have caught: #393 (would have wiped #391/#388/#389/#392), #394 round 1 (stacked on stale #393), #396 (would have reverted #395 ~520 lines), #394 round 2 (stale base after #395 merged). ## Pull requests Budget rule: perform required GitHub side effects before optional long validation or repeated polling consumes the turn. Once a PR comment, review, or status update is the next required durable action, do it first and then run extra checks if budget remains. When the tool-call count is visibly high, reserve roughly 10-15 calls for the side effect, verification (`gh pr view` / `gh pr checks`), and wrap-up. ```bash gh pr list --state open # open PRs on the current repo gh pr view 42 # view a PR gh pr view 42 --json title,state,reviews # structured fields gh pr checks 42 # CI status gh pr create --title "..." --body "..." # open a PR (uses HEREDOC for body) gh pr comment 42 --body "looking now" gh pr diff 42 # the PR's diff ``` For PRs the bot opens, the convention (see mimirbot/README.md) is feature branch + PR; do not push to `main` directly. ## Issues ```bash gh issue list --state open gh issue view 7 gh issue comment 7 --body "ack — picking this up" gh issue create --title "..." --body "..." # only when explicitly asked ``` ## Workflow runs / CI ```bash gh run list --limit 10 gh run view # which steps passed/failed gh run view --log-failed # logs for failed steps only gh run watch # block until done ``` ## `gh api` for advanced queries When the subcommands don't cover what you need, drop to the API: ```bash gh api repos/jasoncarreira/mimir/pulls/42 --jq '.title, .state, .user.login' gh api repos/jasoncarreira/mimir/pulls/42/comments gh api 'repos/jasoncarreira/mimir/issues?state=open&labels=bug' --jq '.[] | "\(.number): \(.title)"' ``` `--jq` filters work like inline jq queries; chain with shell tools when needed. > **`--jq` is not available on poller or scheduled turns.** The trusted-service > shell profiles do not admit it: `gh` evaluates the filter in-process and jq's > `env` builtin reads the process environment, so the option is a credential > read rather than an output formatter. Use `--json ` and filter the > returned JSON yourself. Piped and bracketed filters were already refused on > those turns anyway, because `|`, `[` and `]` are shell metacharacters. ## When NOT to use this - Don't push to `main` even when you can — feature branch + PR is the convention. Operator merges. - Don't open issues without being asked; reading and commenting is the default mode. - Don't use `gh repo delete` or `gh release delete` ever (no destructive ops).