SuperAPI AI Directory

soia-dev-github-ops

General & other

View repository

Updated 10-16 08:34

About this skill

soia-dev-github-ops

Use this skill when the user asks to inspect or operate GitHub state: issues, pull requests, checks, reviews, workflow run logs, labels, releases, or PR lifecycle actions.

Do not use it for local-only git work such as commits, rebases, branch cleanup, or worktree management unless a GitHub operation is also required.

Customer-readable description

What this skill can do

Use gh CLI for GitHub issue, PR, checks, review, workflow run, release, and collaborator-permission operations, plus a pre-merge rule-review procedure and an author-side "address a review and fix it" procedure, with structured JSON output and safety gates

Customer wants Skill will do Customer can see
Complete the work covered by this skill Read the user request, necessary context, and this skill's main workflow, and execute the minimal reliable steps The customer will see the execution plan, command output summary, code/document changes, verification results, and risk description.
Add/check/revoke repository collaborator permissions for someone First confirm the target repository, username, and permission level, then execute gh api write operation and verify it takes effect Permission level description, confirmation checklist, effective verification result
Want to know whether this PR complies with the rules before merging Pull the diff + this repository's own rules files, cross-check, then give tiered recommendations; do not auto-merge One-sentence conclusion, findings list tiered by blocking/should-fix/no objection, and CI and mergeable status
Received review comments (paste PR/review URL and say "help me fix it") Pull the review (including inline + conversation comments) → checkout branch → delegate to fix-loop to fix item by item → push back to the original branch and request re-review; do not auto-merge Handling status of each comment, verification evidence, push result, re-review request receipt
Missing dependency, permission, configuration, or key Stop actions that require external state, and clearly state what is missing Installation command, application address, configuration path, or questions requiring customer confirmation
Execution complete Summarize successes, skips, failures, file changes, and verification results A completion receipt that can be copied into a ticket/log

How the customer uses it

  1. Describe the goal in natural language and provide the necessary inputs: files, URLs, repo, workspace, proposal, vault, or platform account status.
  2. The Agent first determines whether this skill applies, then checks dependencies, configuration, permissions, and risky actions.
  3. For actions that can be dry-run or previewed, provide a preview first; for deletion, overwriting, sending, publishing, or writing remote state, seek customer confirmation first.
  4. After execution, verify the real output; do not substitute "looks successful" for evidence.
  5. The final reply must provide a customer-visible summary: what was done, log summary, file changes, issues, and next steps.

Dependencies and installation

Install this skill (single skill):

npx skills add soia-team/soia-open-dev-coding-skills -g -a '*' -s soia-dev-github-ops -y

Configuration conventions:

~/.config/soia-skills/soia-dev-github-ops/config.yml
SOIA_DEV_GITHUB_OPS_CONFIG_FILE=<custom-config-path>
  • If this skill does not need private configuration, you may skip creating config.yml。
  • If an API key, cookie, session, provider home, or local path is needed, it can only go into private config.yml, the process environment, or the provider's own login state; it must not be written into the repository, vault body, or logs.
  • Strong dependencies, optional dependencies, and third-party skill relationships must be based on this SKILL.md and the subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, first supplement the description or ask the customer, and do not guess.
  • Third-party skills may only declare dependencies and installation methods; do not directly modify third-party skill files.

Logs and completion receipt

Every execution must let the client see the process and the result. Minimum receipt format:

完成:<一句话说明本次完成了什么>。

日志摘要:
- started: <检查到的输入/配置/依赖,不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化:
- <绝对路径或“未改动文件”>

验证:
- <运行过的检查、命令或人工核对点>

问题与下一步:
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令;没有则写“无”>

Safety Model

  • Read-only gh queries may run once the target repo is known.
  • Mutating operations require clear user intent in the current request.
  • High-impact operations require an explicit final confirmation before running: gh pr merge, gh release create, branch deletion, label deletion, workflow dispatch against production, granting/revoking a collaborator's permission, or any action that closes public work or changes who can write to a repo.
  • Collaborator permission changes are the single most sensitive operation this skill performs — more sensitive than gh pr merge. A bad merge affects one change; a wrong permission grant is a standing capability the person keeps using until someone notices and revokes it. Never infer the target repo, username, or permission level from prior conversation turns alone — restate all three and get explicit confirmation in the current exchange before the write call. See "Collaborator Access Management" below for the full gate.
  • Use gh auth status before operations. If auth is missing or expired, stop and tell the user what needs to be configured.
  • Never put GitHub tokens in SKILL.md, shell history, scripts, issue bodies, PR bodies, or comments. Use gh auth login for credentials; keep only non-token defaults in the skill-specific private config.

Repo Resolution

Resolve the target repository in this order:

  1. Explicit command argument: --repo <owner>/<repo>.
  2. Current git remote if the command runs inside a GitHub checkout.
  3. Environment variable: GITHUB_REPOSITORY=<owner>/<repo>.
  4. Optional private config: ~/.config/soia-skills/soia-dev-github-ops/config.yml.
  5. Ask the user if the repo is still ambiguous.

The optional config file is a user-owned YAML file with an env: mapping, for example:

env:
  GITHUB_REPOSITORY: "<owner>/<repo>"

Do not hardcode maintainer-specific repositories in reusable commands.

Query Patterns

Prefer --json and --jq for agent-readable output.

# Auth and repo sanity checks
gh auth status
gh repo view --json nameWithOwner,defaultBranchRef,isPrivate

# Open PRs
gh pr list --repo <owner>/<repo> --state open \
  --json number,title,state,author,headRefName,baseRefName,updatedAt

# Single PR status
gh pr view <number> --repo <owner>/<repo> \
  --json number,title,state,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName

# PR checks
gh pr checks <number> --repo <owner>/<repo> \
  --json name,state,bucket,startedAt,completedAt,link

# Issues
gh issue list --repo <owner>/<repo> --state open \
  --json number,title,state,labels,assignees,updatedAt

# Workflow runs
gh run list --repo <owner>/<repo> --limit 20 \
  --json databaseId,status,conclusion,workflowName,headBranch,createdAt,url

When reporting results, include:

  • repo: <owner>/<repo>
  • object: PR / issue / run / release
  • identifier: number, run id, or tag
  • status: open / closed / merged / passing / failing / cancelled
  • next action or blocker

PR Lifecycle

Create PRs with a concise body containing summary and verification evidence.

gh pr create --repo <owner>/<repo> \
  --base <base-branch> \
  --head <feature-branch> \
  --title "<type>: <short change>" \
  --body "$(cat <<'EOF'
## Summary
- <what changed>

## Verification
- <command>: <result>
EOF
)"

Review operations:

gh pr review <number> --repo <owner>/<repo> --approve --body "<review note>"
gh pr review <number> --repo <owner>/<repo> --request-changes --body "<required changes>"
gh pr comment <number> --repo <owner>/<repo> --body "<comment>"

Before merge:

gh pr view <number> --repo <owner>/<repo> \
  --json mergeable,mergeStateStatus,reviewDecision,statusCheckRollup \
  --jq '{mergeable, mergeStateStatus, reviewDecision, checks: .statusCheckRollup}'

Only merge after explicit confirmation:

gh pr merge <number> --repo <owner>/<repo> --squash --delete-branch

Pre-Merge Rule Review

Use for: "Review whether this PR should be merged" / "Does this PR comply with the rules, take a look for me" / a bare PR list URL the user wants reviewed / "review this <repo> 's pull/<n>".

The output of this procedure is advice, not a merge trigger. The user reviews the findings and decides. A request to review is not a request to merge — this holds even if the same message also pre-authorizes merging ("review PR 42, merge it if it's fine"). Pre-authorization is conditional on findings the user has not seen yet, so it cannot substitute for the confirmation Safety Model requires before gh pr merge. Always post the graded findings from Step 4 first, then treat the next message as the actual merge confirmation — never merge in the same turn the report is produced.

Step 0 — Resolve which PR

If the user gave a PR list URL or repo without a specific number, list the open PRs first and ask which one to review — do not guess:

gh pr list --repo <owner>/<repo> --state open \
  --json number,title,author,updatedAt

Step 1 — Pull the facts (read-only, no confirmation needed)

gh pr view <number> --repo <owner>/<repo> \
  --json title,body,author,baseRefName,headRefName,state,additions,deletions,changedFiles,labels,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup

gh pr diff <number> --repo <owner>/<repo>

gh pr checks <number> --repo <owner>/<repo> --json name,state,bucket

Step 2 — Find this repo's own rules (do not borrow another repo's)

These four are the common ones, but they aren't the full list for every repo — list the actual root directory and check for any *_SPEC.md/*.md rule file by name, not just these:

  • CLAUDE.md / AGENTS.md — agent behavior conventions
  • CONTRIBUTING.md
  • .github/PULL_REQUEST_TEMPLATE.md — if it has a checklist, the PR body should address each item
  • If the changed files live under a subdirectory that has its own AGENTS.md/README.md (common in this org's repos: "read the zone's own rules before touching it"), read that too

This org's skill repos in particular also carry SKILL_SPEC.md (skill authoring rules — version bump discipline, frontmatter requirements), DATA_STORAGE_SPEC.md (where credentials/config/cache may and may not live), and THIRD_PARTY_NOTICES.md (any new adapted code or dependency must be registered there) — check for these by name specifically when the PR's repo is one of the soia-*-skills repos, since a diff that skips registering a new third-party adaptation is a real, previously-seen failure mode here, not a hypothetical one.

If no rule file exists, say so plainly in the final report instead of inventing rules from memory of other repositories.

Step 3 — Hand off to soia-dev-review-panel for the actual cross-check

Do not re-derive a review checklist here. Use soia-dev-review-panel's code lens group (correctness/self-verification, security, test coverage & anti-fake-fix, scope & consistency) against the diff from Step 1, with the rule files from Step 2 as its "rules" input for the scope/consistency lens. That skill also owns the "open the real file, don't trust the diff snippet" discipline and the graded-confidence (seen/inferred/unconfirmed) finding format — this procedure doesn't maintain a second copy of either.

If soia-dev-review-panel isn't installed, stop and tell the user to install it (npx skills add soia-team/soia-open-dev-coding-skills -g -a '*' -s soia-dev-review-panel -y) rather than falling back to an ad-hoc checklist.

Step 4 — Report

Use soia-dev-review-panel's Step 5 output as the body of the reply (verdict first, findings by tier, coverage notes), plus these two additions that are specific to this GitHub procedure and not part of the generic methodology:

  • CI/mergeable status from Step 1 — report what was actually observed, don't re-guess it.
  • Explicit handoff: "the merge decision is yours" — never follow this report with gh pr merge in the same turn, even if the original request pre-authorized merging; wait for the user's next message after they have seen the findings.

Address Review Feedback (author side)

Use when the user is the PR author and hands you a review to act on: "Help me fix this PR" / "Change this review comment" / a PR or review URL with "modify according to the review" / "I've changed everything the reviewer asked me to". This is the mirror image of Pre-Merge Rule Review: that one produces advice for a reviewer; this one consumes a reviewer's advice and turns it into pushed fixes. It never merges — see Step 5.

Step 0 — Resolve the PR and pull the review as findings

From a PR URL, a review URL (.../pull/<n>#pullrequestreview-<id>), or a bare number, resolve <owner>/<repo> and <n>, then fetch the review text. The review body, inline diff comments, AND plain conversation-tab comments are all findings input — they live on three separate endpoints, so fetch all three (a reviewer's ask typed in the conversation box is an issue comment, not a PR review comment, and is easy to miss):

gh pr view <n> --repo <owner>/<repo> \
  --json number,title,headRefName,baseRefName,state,reviewDecision,url,isCrossRepository,headRepositoryOwner,maintainerCanModify
# review summaries (CHANGES_REQUESTED / COMMENTED / APPROVED), newest last:
gh api --paginate repos/<owner>/<repo>/pulls/<n>/reviews \
  --jq '.[] | {id, user: .user.login, state, body}'
# inline diff comments (file + line + body), often where the real detail is:
gh api --paginate repos/<owner>/<repo>/pulls/<n>/comments \
  --jq '.[] | {path, line, user: .user.login, body}'
# conversation-tab comments (no file/line) — a third, disjoint channel:
gh api --paginate repos/<owner>/<repo>/issues/<n>/comments \
  --jq '.[] | {user: .user.login, body}'

--paginate matters: without it gh api returns only the first 30 items, so a heavily-reviewed PR would silently drop later comments. Normalize every distinct point the reviewer raised into one finding with a stable id, severity (take the reviewer's tier if given), file:line, and the quoted ask. If a review URL was given, prioritize that specific review's body; still scan the other two channels, since detail and follow-up asks land there too.

Step 1 — Get onto the PR branch (do not fix on the wrong branch)

Precondition: you must be inside a local clone of <owner>/<repo> — gh pr checkout checks out into the current repo, it does not clone. If cwd is not a clone of that repo, cd into one or clone it first; running gh pr checkout from an unrelated repo silently checks the PR out against the wrong remote.

gh pr checkout <n> --repo <owner>/<repo>
git status -sb   # confirm you are on <headRefName>, clean tree

If the PR head is on a fork you cannot push to (isCrossRepository: true and maintainerCanModify: false when you are not the fork owner), stop and say so — the fix would have nowhere to go. If the local tree is dirty, stop and surface it rather than fixing on top of unrelated uncommitted work.

Step 2 — Hand the findings to soia-dev-fix-loop

Do not invent a fix procedure here. Pass the normalized findings from Step 0 to soia-dev-fix-loop, which runs the reproduce → decide (fix/reject/defer) → minimal-fix → regression + independent recheck → receipt loop, applying soia-dev-coding-protocol's anti-fake-fix discipline during the edits. This skill owns none of that — it only supplies the findings and the checked-out branch.

If soia-dev-fix-loop isn't installed, stop and tell the user to install it (npx skills add soia-team/soia-open-dev-coding-skills -g -a '*' -s soia-dev-fix-loop -y) rather than hand-rolling a fix loop.

A reviewer finding is a claim, not a verdict: fix-loop may legitimately reject one with evidence or defer it with a tracked follow-up. Do not silently skip any — every point the reviewer raised must end with a fix, reject, or defer that you can show.

Step 3 — Optional self-review before pushing

If the fixes are non-trivial, run soia-dev-review-panel over your own diff (git diff origin/<baseRefName>...HEAD — use the remote-tracking base ref, which is present after checkout, rather than a bare <baseRefName> that may not exist locally) with its code lens group + adversarial verification, so you catch your own regressions before the reviewer does. Higher first-pass acceptance, fewer round-trips.

Step 4 — Push back to the PR branch

Commit with a message that references which review points it addresses, then push — this updates the existing PR, never opens a new one:

git push

Use a bare git push, not git push origin <headRefName>: after gh pr checkout the branch is already configured to track the correct remote (the fork for a cross-repo PR, origin for a same-repo PR), and git push origin ... would push to the wrong repo for a fork PR — silently creating a stray branch on the base repo without updating the PR. Pushing to an open PR's branch is an externally visible update to shared work, so confirm the diff with the user before pushing if they haven't already told you to push in this exchange.

Step 5 — Request re-review, do NOT merge

The author does not merge their own PR that a reviewer marked CHANGES_REQUESTED — that bypasses the exact gate the reviewer just raised. After pushing, re-request review and hand back:

gh pr edit <n> --repo <owner>/<repo> --add-reviewer <reviewer-login>
# or leave a comment summarizing what was addressed:
gh pr comment <n> --repo <owner>/<repo> --body "<per-finding: fixed / rejected+why / deferred+where>"

Report: fix-loop's receipt (each finding → fixed/rejected/deferred with evidence), the push result, and that re-review has been requested. State explicitly that merging is the reviewer's call, not this procedure's — even if the author has write/admin permission and could merge. Only merge if the user, in a later message after seeing this report, explicitly says to.

CI Failure Triage

Use this order:

  1. Identify the failing run and job.
  2. Read the first actionable error in the failed log.
  3. Classify the failure.
  4. Reproduce locally only if the repo has enough context and the command is safe.
  5. Report the exact failing command, file, or external blocker.
gh run view <run-id> --repo <owner>/<repo> --json status,conclusion,workflowName,jobs,url
gh run view <run-id> --repo <owner>/<repo> --log-failed

Common classes:

Class Signal Next step
Compile compiler, typecheck, or lint error Read the first error and map to file/line
Test assertion failure or failing test name Reproduce that test locally if possible
Environment missing tool, package, or cache Check setup steps and runner image
Permission Resource not accessible or denied secret Check workflow permissions and fork context
Quota/timeout quota message or cancelled after timeout Report external limit or split work

Release Operations

Release creation is a publish action. Prepare the command, show the tag/name/body summary, and ask for explicit confirmation before running:

gh release create <tag> --repo <owner>/<repo> \
  --title "<release title>" \
  --notes-file <notes-file>

After release, verify:

gh release view <tag> --repo <owner>/<repo> \
  --json tagName,name,isDraft,isPrerelease,publishedAt,url

Collaborator Access Management

Use for: "Give <user> permission to submit PRs in <repo> " / "Add xxx to this repository" / "See what collaborators this repository currently has" / "Remove xxx from this repository".

Permission levels

GitHub collaborator permissions, narrowest to broadest:

Level Grants Typical fit
pull Read-only; can fork and open cross-fork PRs External contributor on a private repo — on a public repo, anyone can already fork and PR without being added at all
triage pull + manage issue/PR labels and assignees, no code writes Triage-only, no code access
push triage + push branches, open PRs from branches in the repo itself What "permission to submit PRs" usually means
maintain push + manage some repo settings (not sensitive ones, not collaborators) Needs to manage issue templates/wiki, not full admin
admin Full control: delete repo, manage collaborators, manage secrets Rare; treat as a distinct, higher-bar request

Default rule: when the user says "add permission to submit PRs" without naming a level, confirm whether the person is an internal collaborator (→ push) or an external contributor (→ usually no grant needed on a public repo; on a private repo, pull or triage is enough to see the repo and open PRs against it — push is more than they need). Do not default to push without asking when it's ambiguous which case this is. Never grant maintain/admin unless the user names that level explicitly.

Commands

# List current collaborators and their permission (read-only, always safe)
gh api repos/<owner>/<repo>/collaborators \
  --jq '.[] | {login: .login, permission: .role_name}'

# Look up one person's current permission (read-only)
gh api repos/<owner>/<repo>/collaborators/<username>/permission \
  --jq '{permission: .permission, role_name: .role_name}'

# Grant or change a collaborator's permission (write — see Safety Gate below)
gh api repos/<owner>/<repo>/collaborators/<username> \
  -X PUT -f permission=<pull|triage|push|maintain|admin>

# Remove a collaborator (write — same Safety Gate)
gh api repos/<owner>/<repo>/collaborators/<username> -X DELETE

Safety Gate

This is the one operation in this skill that never runs on inferred intent — restate and get explicit confirmation on all of the following in the current exchange before the write call:

  • Target repo: <owner>/<repo>
  • Target user: the actual GitHub username, not a display name or email — if you only have an email or display name, resolve the username first (gh api "search/users?q=<query>" — note the query goes in the URL so gh api stays a GET; passing it via -f would switch the call to a POST and fail — or ask the user) rather than guessing the spelling
  • Permission level: pull / triage / push / maintain / admin
  • If revoking: confirm this removes their direct collaborator access — it does not close their open PRs/branches (this skill does not cascade that cleanup), and it does not touch access granted through org Team membership, which is a separate permission path this call cannot revoke

Inviting someone to a private repo sends them a GitHub notification/email — an externally visible action — so the confirmation gate applies even when it feels like "just adding one person."

Verify after granting

gh api repos/<owner>/<repo>/collaborators/<username>/permission \
  --jq '.permission'

Confirm the returned value matches what was requested before reporting success. Do not treat a 2xx response alone as proof the grant took effect: GitHub's collaborator-add endpoint returns 201 when it creates a pending invitation (not in effect until the person accepts) versus 204 when it updates an existing collaborator (in effect immediately) — for a 201, say explicitly in the report that access is pending acceptance, not yet active.

Verify after revoking

gh api repos/<owner>/<repo>/collaborators/<username> --silent && echo "still a direct collaborator" || echo "removed as direct collaborator"

A successful DELETE (2xx) only means direct-collaborator access is gone — it is not proof the person has no access at all. If <owner> is an org (not a personal account), check whether a Team grants them access independently before reporting "access revoked" as a complete statement:

gh api orgs/<owner>/teams --jq '.[].slug' \
  | xargs -I{} gh api orgs/<owner>/teams/{}/repos/<owner>/<repo> --silent 2>/dev/null \
    && echo "a team still grants access to this repo — check its membership"

If any Team still has access to the repo, report both facts separately: direct-collaborator access removed, Team-based access (if applicable) unchanged — do not collapse them into one "access revoked" claim.

Output Checklist

Before final response:

  • State the resolved repo and how it was resolved.
  • Separate facts from inference when summarizing failures.
  • Include exact PR/issue/run/release identifiers.
  • For mutating operations, say what changed and include the resulting URL or id.
  • For blocked auth or permission, say which gh command failed and what the user must configure.