github-ops

1仕組みと動作原理

全体を貫く第一原則：成功したように見えるコマンドではなく「要求されたGitHubの状態」を届ける。2xxレスポンスはGitHubがリクエストを受理した証明に過ぎず、フィールドの変更、招待の受諾、非同期タスクの完了、または業務上の成果達成を証明するものではない。

SKILL.md本体は厳密な「ハードコントラクト＋ルーティングテーブル」であり、操作ドメインに応じてタスクを8つのリファレンスに振り分け、約95KBのナレッジの一括読み込みを避けて現在のタスクに必要な1つのみを読み込むよう要求する。

ステップ1でまずリクエストを分類（読み取り専用／指定状態変更／破壊的・公開・クレデンシャル関連・本番トリガー・対外コミュニケーション）し、分類によって認可範囲および書き込み前に停止すべきかを決定する。

ステップ2では最初の書き込み前にID・ホスト・ターゲットをバインド：アクティブアカウント（--hostname HOST）を検証した上で完全修飾ターゲットを解決し、複数GitHubインスタンス環境では明示的なHOST指定を強制する。

ステップ3は（古いローカル参照や記憶ではなく）GitHubホスト上の状態の読み取りを要求し、影響を伴う書き込みの前に「Target / Current / Requested / Blast radius / Recovery / Readback」からなる6行の影響プレビューの明記を義務付ける。

ステップ4は「入力規約がその変更を真にサポートしている」インターフェースの選択を要求し、優先順位は専用ghサブコマンド → ドキュメント化されたREST → GraphQL（GraphQL専用または関連データの結合時のみ）→ UI限定設定と固定する。核心となる落とし穴は「レスポンスのフィールドは書き込み可能フィールドと一致しない」点にある。

ステップ5は冪等性の原則：ピン留め可能な項目（リポジトリ/番号/ブランチ/run ID/ユーザー名/期待SHA）をすべて固定し、非冪等な書き込みではタイムアウトや5xxエラー発生後に再送の可否を判断するためまずリードバックを行う。

ステップ6では「変更レスポンスもキャッシュされたrefも信用しない」新規リードバックによる検収を実施し、変更タイプごとの検証エビデンス表（PRマージ/ブランチ削除/Issue・コメント・レビュー/リポジトリ作成・編集・可視性/コラボレーターおよびチーム権限/Org設定/2FA/workflow/secret）を提供する。

ステップ7は4つの誠実な状態（changed and verified / already satisfied / pending / failed-no-op or partial）のいずれかに着地させ、失敗ステータスには復旧手段と未解決リスクの付記を義務付ける。

高リスクな境界は独立セクションとして明記：リポジトリ作成にはOWNER/REPOと可視性の明示が必須、可視性変更には影響承諾フラグが必要、削除/移譲/Org権限/2FA/シークレットローテーションはそれぞれ専用リファレンスに従う。

隣接スキルとの境界画定：ローカルGitの修復（ダーティな作業ツリー、bundle、失われたコミット）はgit-safety-netが担当し、本スキルはGitHubホスト上の状態のみを所掌する。

高リスク操作はリファレンスごとに専用フローに分離：リポジトリ移譲のRESTは非同期処理であり202は単なるpendingであるため、新しい完全修飾名をポーリングしてコラボレーター/チーム/保護/Pages/シークレットを再監査する必要がある。削除は対話的な完全名確認を維持し、原則として--yesを付与しない。

Organization単位の変更も同様に専用フローを適用：まず有効権限（effective permission）の付与元（リポジトリ/チーム/ベース権限/Orgオーナーシップ/Enterpriseポリシー）を特定し、UI限定フィールドを判定した上で初めて書き込みを行う。2FA強制は単なるチェックボックスではなく組織レベルのアクセス権変更として扱う。

Issueの作成/コメント/移譲/クローズは明示的に「外部アクション」として定義され、実行前に正確なリポジトリとコンテンツにバインドしなければならない。一括Issue管理は凍結リスト＋1件ずつのリードバック手順を踏む。

2コア機能

3外部依存関係

4推奨統制措置と判定根拠

5二重目の独立検証

• [ok] external_deps 逐条反查调用点是否真实存在 — 10 条依赖全部在文件内定位到调用点：gh（SKILL.md 步骤 2 命令块与全篇）、git（pr_operations.md 的 'git rev-parse '<candidate>^{tree}'' 与远端分支退役小节的 '--force-with-lease="refs/heads/{branch/path}:$expected_sha"'）、jq（best_practices.md 的 'gh api rate_limit --jq ...' 与多处 '| jq'）、curl（workflow_operations.md 匿名回读两行）、unzip（'unzip -tq RUN_ID.zip'）、REST（api_reference.md 全篇 gh api repos/...）、GraphQL（'gh api graphql -f query='）、企业主机（best_practices.md 的 'gh api --hostname github.example.com user --jq '.login''）、webhook 目标（api_reference.md 的 config[url]=https://example.com/webhook）、文档链接（api_reference.md 末尾三条 https 链接）。无虚构条目；也未漏登记第三方包——全目录不存在 package.json / requirements.txt / go.mod / Gemfile 等依赖清单。
• [ok] 文件清单 glob + git ls-files 全量核对 — github-ops/ 下恰好 9 个文件：SKILL.md + references/{api_reference,best_practices,branch_protection,issue_operations,organization_access_and_settings,pr_operations,repository_operations,workflow_operations}.md；无 scripts/、无模板/数据文件、无隐藏文件、无 symlink；find 与 git ls-files 结果一致；目录内无 LICENSE（LICENSE 在仓库根，MIT，Copyright (c) 2025 daymade，与固定取值相符）。工作副本 HEAD = d5c4678cb5d4fd6acc9c922690df035dbd33d247，与 pin 一致。
• [ok] 指令中记载的 gh 子命令与 flag 真实性核验（本机 gh 2.100.0） — 对 41 组子命令/flag 跑 gh <cmd> --help 校验，缺失 0：含 --accept-visibility-change-consequences、--match-head-commit、--auto/--squash/--rebase、--paginate/--slurp/--input/-X/-f/-F/-i、--hostname、--show-token、repo create --source/--remote/--internal、secret/variable/run/workflow 全族、issue pin/unpin/transfer、pr ready --undo、pr edit --add-project、run rerun --failed/--debug、run download --name/--dir、config set、repo set-default。--json 字段名另用负控验证（'--json bogusfieldxyz' 报 'Unknown JSON field'），说明 gh 会先做客户端校验，本 skill 用到的 issue/pr/run/repo/workflow --json 字段集全部通过校验。
• [discrepancy] 安全结论反例①：是否有未登记的网络外发 — 发现两条第一遍未单独点名的外发路径，本稿已补登记：(a) curl 直连 api.github.com 的匿名回读（不是走 gh 的通道，用于运行历史清除验收）；(b) 创建 webhook 后仓库事件会持续外发到 config[url] 指定地址（示例为 example.com 占位，替换为真实 URL 后即形成长期数据出口）。其余外发（gh/git/文档链接）与第一遍一致。混淆载荷反查：base64/eval/xxd/加密串在目录内零命中。
• [ok] 安全结论反例②：凭证读取/泄露面 — grep 'token|TOKEN|secret|SECRET|show-token|GH_TOKEN|env|api_key' 的全部命中均为纪律条款或 API 字段名，无一处读取、打印、写盘或作为参数内联：'Never use `gh auth status --show-token`'、'never inline or echo the value'、'keep secrets out of command arguments.'、'token literal in a command, document, process argument, log, or committed environment file.'、'Never copy another environment's credential as a fallback.'、'Use only that host's existing authorized login; do not copy tokens,'。gh secret set 走隐藏交互提示或 stdin 重定向，并明确 'GitHub intentionally does not return the secret value.'。
• [discrepancy] 安全结论反例③：是否有未声明的破坏性/绕过行为 — 两处需在展示层点名的能力（非漏洞）：(a) workflow_operations.md 的 '## Purging Public Run History' 提供真实 DELETE（gh api -X DELETE 'repos/OWNER/REPO/actions/runs/RUN_ID' 与 deployment 删除），runs 不可恢复，文档要求先全量备份并匿名回读验收；(b) 同文件含 'gh secret delete SECRET_NAME'、gh variable delete、gh workflow disable 等可令生产流程停摆的操作。SKILL.md 的高危边界清单只列 '- Merges, branch deletions, repository creation/deletion/transfer/visibility changes,' 一行覆盖范围，未把「运行历史清除」纳入该清单（仅路由表以 purge 覆盖），属边界清单与 reference 能力的轻微不同步——用户需知晓删除历史同样不可逆。
• [ok] 实现原理是否夸大：description 声明 vs 实际文档能力 — description 列出的各域逐一有承载：PR（pr_operations.md）、issues（issue_operations.md）、Actions（workflow_operations.md）、repositories（repository_operations.md）、collaborators/teams/base permissions/2FA（organization_access_and_settings.md）、branch protection（branch_protection.md）、API automation 与 public/enterprise GitHub（api_reference.md + best_practices.md）、parallel or superseded PR convergence（pr_operations.md 收敛五步）、「write 返回成功但状态没变」（SKILL.md 第 4/6 步 + 组织设置的静默 no-op 节）、「某设置只能 CLI/REST/GraphQL/UI 哪种能改」（SKILL.md 第 4 步 + UI-only 小节）。七步契约标题在正文以 '### 1.'…'### 7.' 实际存在。反面检查：全文没有自动完成/保证成功式措辞，反而反复要求报 pending/failed/no-op，未夸大。
• [discrepancy] 内部一致性：小标题与内容、示例与边界清单是否自洽 — 一处小标题窄于内容：workflow_operations.md 的小节标题为 '### Managing Secrets (via API)'，其下同时给出 gh api repos/{owner}/{repo}/actions/secrets（API）与 gh secret set/list/delete（gh CLI 子命令）——命令本身可执行，仅标题措辞与命令族不完全对应。另一处见上一条（路由表 purge vs 高危边界清单）。其余抽检一致：可见性变更在 SKILL.md 与 repository_operations.md 用同一旗标与读回要求；2FA 在 SKILL.md 验收表与 organization_access_and_settings.md 的流程互相对应。

6結論