Github

Never edit this file directly. To make additions or modifications, edit the appropriate section in ./vstack.toml. Then run vstack refresh.

GitHub Queries

CLI wrapper for GitHub API operations used in PR workflows. Provides structured JSON output, bot account support, and configurable issue ID extraction.

.agents/skills/github/scripts/github.sh <command> [options]
.agents/skills/github/scripts/github.sh -C <path> <command> [options]  # Run in different directory

Commands

Most commands accept no PR number to auto-detect from the current branch. Exception: post-reply with a numeric comment ID never auto-detects — it requires an explicit --pr <N> (thread PRRT_... IDs need no PR number).

There is no CI wait command here: blocking until CI completes on a PR is the orch skill's .agents/skills/orch/scripts/ci-wait <PR_NUMBER> [interval] [max_wait] [--json]. ci-logs only fetches failure logs, and await-mergeable waits for merge-state resolution, not check completion.

Label application contract

label-add checks that the named label exists in the live repository inventory, resolves the target, and then uses GitHub's shared issue/PR label REST endpoint. The endpoint response is authoritative for the selected token's effective issues=write or pull_requests=write grant; repository roles are not used as a proxy because GitHub App and fine-grained token grants can differ from them. Label names are sent as literal strings, including names beginning with @ or resembling booleans, integers, nulls, and repository placeholders.

• --required is the default. A missing label is a repository configuration error (exit 78); a known GitHub label-write denial is a capability error (exit 77). Neither failure successfully mutates the PR or issue.
• --optional is only for labels the calling project policy explicitly marks non-gating. A missing label or insufficient permission emits a structured optional_unsupported result, exits zero, and does not mutate the target.
• Authentication, repository/target lookup, rate limits, server errors, and unexpected API failures are operational errors in both modes; they never become optional skips.

Workflow-required QA labels must use --required. Do not downgrade a required label to --optional merely because a consuming repository is misconfigured.

Git HTTPS Auth Helper

git-https-auth [-C path] <git args...> runs git normally, but when the target repo or explicit URL uses a GitHub SSH remote and gh auth is valid, it adds per-command config for gh auth git-credential and rewrites GitHub SSH URLs to HTTPS. This covers Codex and other harnesses where GitHub CLI auth is valid but an SSH key or agent is unavailable. It never persists git config.

Use it for workflow network operations that only need origin, for example:

.agents/skills/github/scripts/git-https-auth -C . fetch --prune origin
.agents/skills/github/scripts/git-https-auth -C . push -u origin HEAD:refs/heads/my-branch

Set VSTACK_GITHUB_GIT_HTTPS_FALLBACK=never to disable the fallback, or always to force the temporary config for a GitHub operation.

Diff Summary Helper

git-diff-summary [-C path] [base-branch|--staged|--head] is a standalone review-routing helper that emits JSON with changed-file domains, scope, insert/delete stats, and risk_flags. Rust-specific flags (unsafe_code_added, repr_c_struct_changed, extern_c_changed, atomics_modified) scan added lines from .rs diffs only, so scripts, docs, and other non-Rust files can discuss those tokens without triggering a Rust risk route.

PR Merge Outcomes

pr-merge returns three distinct outcomes — branch on the exit code, not on parsing stderr:

Before mutating merge state, pr-merge resolves the exact PR head and passes it through --match-head-commit. After a successful gh call it reads queue membership with GraphQL because gh pr view --json does not expose mergeQueueEntry. An OPEN PR with no autoMergeRequest is therefore still a successful exit 75 when its required merge-queue entry is active; an OPEN PR with neither queue nor auto-merge proof fails closed.

Actionable review threads (unresolved and not outdated) are a hard local gate. They make can_merge false and block both immediate merge and --auto before any merge or queue mutation. A failed or malformed thread lookup also blocks, because an unknown review state cannot be treated as clean. The documented --force flag is the only deliberate override and skips every safety check.

--force has immediate-only semantics and cannot be combined with --auto; the conflicting flags fail before any GitHub lookup or mutation. If its guarded gh pr merge mutation fails and the exact-head post-state is not MERGED, pr-merge returns BLOCKED even when classic auto-merge or a merge-queue entry was already active. Pre-existing deferred state is not proof that the forced immediate attempt succeeded. An authoritative exact-head MERGED post-state remains success; non-force and --auto idempotent pending outcomes retain exit 75.

A BLOCKED outcome is further classified on stderr as transient (mergeable UNKNOWN, ci_pending, CI fetch uncertainty — caller should await-mergeable and retry) or permanent (conflicts, ci_failed, changes_requested — caller must fix and re-push). Programmatic callers can check the transient field in the --check JSON output before deciding to retry.

PR Merge Check Output

{"can_merge": true, "issues": [], "warnings": [], "mergeable": "MERGEABLE", "review": "APPROVED", "transient": false}

transient: true means every blocking issue is recoverable by waiting (prefixes unknown:, ci_pending:, ci_unconfigured:, ci_fetch_failed:). Still-running checks are reported as ci_pending: ...; terminal failing or cancelled checks remain ci_failed: ....

Waiting for merge state (gotcha)

Never gate termination on gh pr view --json mergeable. That field stays UNKNOWN permanently after a PR is merged — it is only meaningful while the PR is open, where it transitions through MERGEABLE / CONFLICTING / UNKNOWN. An inline until [ "$(...mergeable...)" != "UNKNOWN" ] loop will never terminate post-merge.

To wait for resolution, use await-mergeable, which polls state and mergeStateStatus correctly:

github.sh await-mergeable 42                    # block until resolved
STATE=$(github.sh await-mergeable 42 | jq -r '.state')   # capture for branching

Resolution rules:

• state in {MERGED, CLOSED} → resolved.
• mergeStateStatus != UNKNOWN (any of CLEAN, BLOCKED, BEHIND, DIRTY, UNSTABLE, HAS_HOOKS) → resolved.
• mergeable alone is never used for termination.

Output Formats

--format is command-specific, not a global flag. Only the commands listed below accept it; others (e.g. pr-view, which takes only --json FIELDS) do not.

--json is accepted as alias for --format=safe on the commands above.

Configuration

Bot token supports direct tokens (ghp_*, gho_*, ghu_*, ghs_*, ghr_*, github_pat_*) and 1Password references (op://vault/item/field).

Non-secret GitHub defaults can live in committed vstack.settings.toml under [env]. Keep tokens in .env.local unless the parent process injects already-resolved values. GitHub helpers preserve parent-process values over project files for the same variable. github.sh then selects one effective router token before resolving 1Password references: first resolved GH_TOKEN, then resolved GH_BOT_TOKEN, then resolved GITHUB_TOKEN; only if no resolved token exists does it consider unresolved op:// references in that same order. op read runs only for that final selected reference. If the selected op:// reference cannot resolve, github.sh drops GH_TOKEN/GITHUB_TOKEN so gh can use keyring auth. Once a resolved GH_BOT_TOKEN is selected, helpers preserve that bot identity instead of replacing it with ambient keyring auth. Auth preflight validates selected env tokens with gh api user; gh auth status is only authoritative for keyring auth when no env token is selected. Bot-token operations still prefer an explicit GH_BOT_TOKEN over user-token variables.

pr-view failure contract

pr-view --json ... returns normal gh pr view JSON on success. On failure it prints structured JSON to stdout and exits nonzero:

{"status":"no_pr","error":"No pull request found for the current branch","detail":"...","exit_code":1,"number":null}

Known status values are no_pr, auth_error, token_resolution_failed, token_resolution_timeout, token_resolution_unavailable, auth_timeout, gh_timeout, and gh_error. Raw gh/op detail is also echoed to stderr so callers can distinguish no-PR, authentication, token resolution, and timeout cases without hanging.

Error Handling

• Most commands return {"error": "message"} on stderr with exit code 1
• pr-view --json ... returns structured failure JSON on stdout so callers can branch on status without losing raw stderr detail
• Automatic retry on rate limiting (3 attempts with backoff)
• NOT_FOUND errors return clean {"error": "Not found"}

Troubleshooting

Expected VAR_SIGN, actual: UNKNOWN_CHAR: Use multi-line GraphQL + -F for variables (shell escaping issue with $ in single-line queries).

gh says bad credentials / HTTP 401 even though gh auth status is healthy: A stale or wrong-account GH_TOKEN / GITHUB_TOKEN in the environment masks the keyring/gh auth login credentials — gh prefers the env var. This happens often when a bot token was exported for one command in a parent shell and is still active. Verify:

# Are env tokens leaking into this shell?
env | grep -E '^(GH_TOKEN|GITHUB_TOKEN)='

# Inspect what gh resolves:
gh auth status

If an unwanted token is set, prefer scoping both variables down for a single call (gh honours GH_TOKEN then GITHUB_TOKEN in order, so clearing only one is not enough):

# Single-call scoping — clears both for this one invocation only.
env -u GH_TOKEN -u GITHUB_TOKEN gh pr list
# Or, equivalently:
GH_TOKEN= GITHUB_TOKEN= gh pr list

For the rest of the shell: unset GH_TOKEN GITHUB_TOKEN. github.sh performs this fallback automatically when the selected env token fails but keyring auth succeeds, and it also drops unresolved op:// env tokens after a failed bounded op read. The pr-create wrapper above intentionally sets GH_TOKEN="$token" only for its one subprocess; it does not export it into the parent shell.

Dependencies

• gh CLI (authenticated)
• jq
• op CLI (optional, 1Password token references)