github-ops

GitHub の操作

見た目上成功しているコマンドではなく、要求された GitHub の状態を実現してください。200、201、 202、204 の応答は、GitHub がリクエストを受け付けた証拠です。要求されたすべてのフィールドが変更されたこと、 招待が承諾されたこと、非同期ジョブが完了したこと、またはユーザーのビジネス上の目的が達成されたことを示すものではありません。

操作に応じた参照先

タスクに必要なリファレンスのみを参照してください。

タスク	リファレンス
PR の作成、レビュー、マージ、クローズ、比較、収束、承認済み PR 本文の改訂のクリア、リモート PR ブランチの整理	references/pr_operations.md
Issue の作成、編集、検索、移譲、クローズ、一括管理	references/issue_operations.md
リポジトリの確認、クローン、作成、編集、名前変更、アーカイブ、移譲、公開範囲の変更、削除	references/repository_operations.md
通常のアカウントをアクティブなまま維持しつつ、別のアカウントからアクセス可能なリポジトリをコピーし、プライベートコピーと上流同期を設定	references/multi_account_repository_sync.md
コラボレーター、チーム、基本権限、メンバー権限、組織の 2FA の確認または変更	references/organization_access_and_settings.md
コラボレーターが PR を通じて貢献できるようデフォルトブランチを保護する、アカウント全体の保護の不足箇所を洗い出す、多数のリポジトリにベースラインを適用する、実際のプッシュで適用を検証する	references/branch_protection.md
Actions の起動、確認、再実行、キャンセル、削除、シークレットまたは変数の管理	references/workflow_operations.md
CI メールの過多、Actions の利用枠超過、無関係なチェックや繰り返し実行を減らす、テンプレートまたは製品に実際に必要なものを判断する	ランナーや通知を変更する前に references/ci-demand-and-notifications.md を参照してください
Docker/OCI イメージをビルドして GitHub Container Registry（GHCR）に公開する	references/ghcr_publishing.md
REST/GraphQL エンドポイント、ページネーション、レート制限、Webhook、Enterprise ホストを使用する	references/api_reference.md
スクリプト、リトライ、一括操作、機械可読な出力を作成する	references/best_practices.md

ローカル Git の復旧、ダーティなワークツリー、バンドル、失われたコミットについては、git-safety-net を使用してください。 このスキルは GitHub 上の状態を担当します。 リポジトリのコピーでは、リモートごとの認証と同期の設定も行ってください。

共通の運用方針

1. GitHub に触れる前にリクエストを分類する

• **回答、調査、診断、レビュー：**読み取り専用です。PR、イシュー、コメント、招待、ワークフローの実行、設定変更を作成しないでください。
• **作成、変更、マージ、クローズ、権限付与、権限取り消し、公開、削除：**指定された状態変更が許可されています。対象と影響範囲を、そのリクエストの範囲内に収めてください。
• **破壊的な操作、公開操作、認証情報に関する操作、本番環境をトリガーする操作、外部への連絡：**正確な対象、結果、復旧方法を確認してください。リポジトリの所有者、公開範囲、メッセージの内容など、重要な選択肢をユーザーが指定していない場合は、書き込み操作の前に中止してください。

修正が明白に見えても、読み取り専用の調査を変更操作に変えないでください。 現在のタスクで許可されていない宛先や内容のコメント、レビュー、イシュー、招待を送信しないでください。

許可されたコントリビューターについては、今日の読み取りや同期コマンドだけでなく、継続的な貢献の役割に基づいてリポジトリへのアクセス権を評価してください。リポジトリへの書き込み権限と、デフォルトブランチを更新する権限は別の決定です。ユーザーが選択した貢献範囲に従い、コントリビューターの権限を暗黙に Read まで下げるのではなく、ブランチ保護と PR レビューによって統合を管理してください。診断だけでは、権限付与は許可されません。

2. ID、ホスト、対象を確定する

最初の書き込みの前に、アクティブなアカウントを確認し、完全修飾された対象を特定します。

gh auth status --hostname HOST
gh api --hostname HOST user --jq '.login'
gh repo view HOST/OWNER/REPO \
  --json nameWithOwner,visibility,isPrivate,viewerPermission,url

github.com では、OWNER/REPO で十分です。通常の診断に gh auth status --show-token を使用しないでください。また、トークンを表示、貼り付け、記録しないでください。

現在のセッションでリモートに初めてプッシュする前に、現在の公開範囲を読み取ります。

gh repo view OWNER/REPO \
  --json nameWithOwner,visibility,isPrivate,stargazerCount,forkCount,url

書き込みを実行するインターフェースにIDを結び付けます。CLIのIDによって、コネクター、ブラウザー、RESTクライアント、Git SSHのIDが確定するわけではありません。ユーザーが許可したタスクに基づいて、想定される実行者を特定します。リポジトリの所有者や利用可能な認証情報によって、実行者が自動的に選ばれることはありません。コネクターでは、その同じコネクターから読み取り専用の現在のユーザー操作を使用し、実行者を確認します。そのインターフェースで実行者を確認できない場合は、許可された書き込みに、すでに確認済みのCLI経路を使用してください。実行者を調べるためのテストコメントは投稿しないでください。

許可された gh API／ホスト状態への書き込みには、同梱の検証付き呼び出しを使用します。<github-ops-dir> をこのSKILL.mdを含むディレクトリに解決し、タスクの作業ディレクトリからそのパスでヘルパーを実行します。実行可能ファイルの引数と拒否の仕様は checked_gh.py を参照してください。

uv run python <github-ops-dir>/scripts/checked_gh.py --expected-login <EXPECTED_LOGIN> --host HOST
uv run python <github-ops-dir>/scripts/checked_gh.py --expected-login <EXPECTED_LOGIN> --host HOST -- pr edit <NUMBER> -R OWNER/REPO --title '<AUTHORIZED_TITLE>'

最初のコマンドは読み取り専用です。2つ目のコマンドは現在の認証情報を特定し、GET /user を確認したうえで、同じ認証情報を1つのコマンドに固定します。実行者が一致しない場合、または不明な場合は、実行前に終了します。これは gh のみを保護し、コネクター呼び出し、ブラウザー操作、Gitプッシュは保護しません。認証／設定コマンドは拒否されます。タスクの許可、正確な対象、独立した読み戻しは引き続き必要です。リポジトリを対象とするコマンドには -R OWNER/REPO を指定し、gh repo には明示的なリポジトリ引数を指定してください。ラッパーは確認済みのホストでその対象を修飾し、子プロセスから継承された GH_REPO と別のトークン変数を削除し、競合するホスト引数を拒否します。IDのみを読み取る場合は、コマンドを省略してください。組織のシークレット／変数操作では、代わりに明示的な --org スコープを使用します。個人のCodespacesシークレットには --user を使用します。本文／タイトル／フィールドの値は、フラグやURLに似ていても変更されません。公開APIの絶対URLには api.github.com を使用し、相対APIエンドポイントも引き続き使用できます。 アカウント、認証情報、ホスト、インターフェースを切り替えると、それ以前のID確認は無効になります。次の書き込みの前に再確認してください。以前のセッションでの合格を使い回さないでください。

参考例は、ネイティブな gh 操作の構文を示しています。ホスト状態の変更は、明示的なリポジトリまたはアカウントのスコープを指定し、これらの引数をヘルパーの -- の後に渡して実行します。単独の gh は、読み戻しや、別途許可された認証／設定に引き続き使用できます。組み込みコマンドで引数の形式が拒否された場合は、同じヘルパーを通じて、サポートされている明示的なREST／GraphQLの同等操作を使用してください。実行者チェックを回避しないでください。呼び出しに失敗した場合やタイムアウトした場合でも、変更が行われなかった証拠にはなりません。再試行する前に、正確な対象を読み取ってください。

インシデントの帰属を調べる際は、イベントID／時刻、実行者、インターフェースを、ChatGPTの実行アカウントとは分けて保持してください。コメント投稿者の login と performed_via_github_app から確認できるのはGitHubの実行者／アプリケーションであり、ChatGPTのメールアドレスではありません。セッションの作成者IDや今日の認証ファイルから、過去の実行アカウントを特定することはできません。不明な関連付けは不明のままにしてください。

3. 現在の権限を読み取り、差分をプレビューする

古いローカル参照や記憶している設定ではなく、GitHub上の状態を使用します。要求された変更を証明するために必要なフィールドのみを取得します。重要な書き込みの前に、次の計画を明確にします。

Target: fully qualified repository, organization, PR, issue, run, or account
Current: authoritative fields and immutable IDs/SHAs
Requested: exact field or state transition
Blast radius: people, repositories, forks, runs, or public surfaces affected
Recovery: exact inverse operation or explicit “not recoverable”
Readback: independent GET/CLI query and expected result

ユーザーがこの結果をすでに明確に許可している場合は、実行してください。形式的な2回目の確認を追加する必要はありません。対象、スコープ、公開範囲、削除、受信者、または復旧方法に曖昧さが残る場合は、書き込みの前に一時停止してください。

4. 変更内容を実際に受け付ける入力仕様のインターフェースを選択する

優先順位は次のとおりです。

1. 専用の gh サブコマンド。
2. 単一のリソースまたは権威ある読み戻しに対応する、文書化された REST エンドポイント。
3. 必要なミューテーション／クエリが GraphQL のみでサポートされる場合、または関連データを組み合わせる場合は GraphQL。
4. 設定にサポート対象の API 入力がない場合は、文書化された GitHub UI。

レスポンスのフィールドが自動的に書き込み可能なフィールドになるわけではありません。PATCH を使用する前に、GET が返す構造ではなく、操作で現在サポートされているリクエストボディのパラメーターと変更したいキーを照合してください。GitHub は、サポートされていないキーを無視しながら、成功レスポンスを返すことがあります。コマンドを実行可能にするためだけに、API ファミリーを切り替えないでください。

gh api ではメソッドを明示してください。-f または -F を追加すると、デフォルトのメソッドは POST に変わります。フィルター付きの GET リクエストには -X GET を含める必要があります。

5. 変更は一度だけ行い、結果が不明な場合に再試行しない

• 操作で指定できる場合は、リポジトリ、オブジェクト番号、ブランチ、実行 ID、ユーザー名、期待する SHA を固定してください。
• コメント、招待、ワークフローのディスパッチ、リリース、PR／issue の作成など、冪等でない書き込みを盲目的に再試行しないでください。タイムアウトまたは 5xx が発生した場合は、最初のリクエストが反映されたかどうかを確認するため、まず読み戻してください。
• 一括変更では、対象を有限のリストとして確定して表示し、その後、項目ごとの結果を確認しながら一件ずつ処理してください。レビューされていないライブクエリを、破壊的な xargs コマンドに直接パイプしないでください。
• リポジトリのフック、必須チェック、ブランチ保護、署名、公開範囲変更の影響確認を回避しないでください。

6. 独立した読み戻しで検証する

変更レスポンスやキャッシュされたローカル参照を信頼しない、新しい読み取りを実行してください。

変更	必須の受け入れ確認
PR のマージ／クローズ／編集	PR の状態と、取り込みが重要な場合は取得したベースでの期待どおりの動作
ブランチの削除	ホスト上のブランチ／ref が存在しないこと。ローカルのリモート追跡参照のクリーンアップは別途確認
issue／コメント／レビュー	意図した状態／内容で、対象オブジェクトが一度だけ存在すること
リポジトリの作成／編集／公開範囲	完全修飾リポジトリの読み戻しが、オーナー、公開範囲、要求されたフィールドと一致すること
コラボレーター／チームの権限	招待が保留中の場合は招待状態、その後に有効な権限。権限を取り消す場合は、残存する基本権限／チーム権限も特定すること
組織の設定	新しい組織／設定の読み取りで、要求されたすべてのフィールドが返されること。UI のみで設定する場合は、UI での読み戻しと、利用可能な API シグナルで確認すること
2FA 要件	影響を受けるアカウントの事前確認、UI での確認、API の読み戻し、メンバーシップ／外部コラボレーターの監査
ワークフローのディスパッチ／再実行／キャンセル	対象の実行 ID が期待する状態に達すること。コマンドの受け付けは完了を意味しない
シークレット／変数の変更	メタデータと利用側の動作。シークレット値は決して開示しないこと

非同期の状態では、期限を設定してポーリングし、終端状態が確認できなければ pending と報告してください。読み戻し結果が異なる場合は、不一致のフィールドを示して failed/no-op または partially applied と報告し、復旧手段を維持してください。書き込みの受領確認だけを根拠に「完了」と言わないでください。

7. 業務上の結果を報告する

最後に、次のうち誠実な状態を一つ報告してください。

• changed and verified — 要求された状態を独立して確認できた。
• already satisfied — 書き込みは不要だった。
• pending — 受け付けられたが、まだ終端状態ではない。次に確認すべき権威ある情報も示す。
• failed/no-op or partial — 要求された状態と確認された状態が異なる。復旧手段と未解決のリスクも示す。

8. 指定された書き込み操作にのみ認証する

認証の対象は許可された操作に限定されます。すでに許可された、正確に指定された書き込み操作をやり直す理由にはなりません。インタラクティブなブラウザー認証またはデバイス認証フローを開始する前に、GitHub アプリケーション、アクティブなアカウント、対象のホスト、追加または変更される権限を正確に説明してください。その説明の後、ブラウザーで完了できる手順を続けます。アクセスを確認ページは再認証のプロンプトです。見出しだけでは、ユーザー本人が物理的に操作する必要があるとは判断できません。確認済みのブラウザーアカウント、ホスト、正確な操作については、信頼できるページを通じて、すでに許可されている通常のパスワードマネージャーのワークフローを使用し、認証情報を取り出したり表示したりしないでください。未完了の最初の手順から再開し、その後、実際の操作の結果を独立して読み取ります。再認証が完了しても、書き込みが実行された証拠にはなりません。

実際の物理的な MFA またはハードウェアキーのチャレンジ、未解決のアカウント選択、または承認済みの認証情報取得手段を利用できない場合は、操作をユーザーに引き継ぎます。物理的なチャレンジを回避してはいけません。通常のフローがインタラクティブであるという理由だけで、より広いスコープ、別のアカウント、または無関係な承認を求めてはいけません。すでに許可された書き込み操作について、再度確認を求めてはいけません。

認証情報の値を、ターミナル出力、URL、引数、コミット済みファイル、レポートに露出させないでください。本番ホストのプル専用レジストリ認証情報は、公開する権限を与えるものではありません。正確な書き込み操作に使用できることを確認済みの、現在の承認済み認証情報を再利用してください。ローカルの一時的な Docker 設定を使用し、操作後にその設定を削除してください。GHCR への公開には独自の事前確認とダイジェストの読み戻しが必要です。イメージのビルドまたはプッシュの前に、references/ghcr_publishing.md を読み込んでください。

影響の大きい操作の境界

• リポジトリの作成には、明示的な OWNER/REPO と公開範囲の指定が必要です。一般的な例で --public を既定値にしてはいけません。公開はプロダクト上の判断です。
• リポジトリの公開範囲を変更すると、コード、Actions ログ、成果物、フォーク、履歴が公開される可能性があります。影響と対象リポジトリが明示的に許可された後に限り、gh repo edit --visibility ... --accept-visibility-change-consequences を使用し、その後、変更を読み戻して確認してください。
• マージ、ブランチの削除、リポジトリの作成・削除・移管・公開範囲の変更、組織全体の権限、2FA の強制、シークレットのローテーションには、それぞれの操作に固有のリファレンスが必要です。
• PR と issue のタイトル形式はリポジトリのポリシーに従います。テンプレート、コントリビューションガイド、チェック項目、または最近承認された例を確認してください。一般的な JIRA プレフィックスを独自に作ってはいけません。
• エンタープライズポリシーは、組織またはリポジトリの制御を上書きする場合があります。HOST を明示的に保持し、下位レイヤーで強制された状態を変更できない場合は、その旨を報告してください。

安全な読み取り専用クイックリファレンス

gh pr list -R OWNER/REPO --state open --json number,title,state,url
gh pr view 123 -R OWNER/REPO --json number,title,state,headRefOid,baseRefOid,url
gh issue list -R OWNER/REPO --state open --json number,title,state,url
gh workflow list -R OWNER/REPO
gh run list -R OWNER/REPO --limit 20 \
  --json databaseId,status,conclusion,headSha,url
gh api -X GET 'repos/OWNER/REPO/branches?per_page=100' --paginate --jq '.[].name'

判断には --json／--jq を使用してください。人が読むための整形済み出力を解析に使用してはいけません。