gh-setup

GitHub のセットアップ

GitHub を、リポジトリにすでに存在するビルド、検証、リリース、デプロイの契約を強制する基盤にします。

スコープと進め方

リポジトリのガイダンスと、依頼された変更を担うファイルおよびコマンドから確認を始めます。参照資料を読み込む前に、以下から該当する進め方を選んでください。

• コラボレーション用ファイル： 対象のファイルと、適用されるオーナーのデフォルト設定を確認します。
• ワークフローの修正： 影響を受けるジョブ、その入力、権限、依存関係、必須チェックの動作を確認します。無関係なデリバリーポリシーは変更しないでください。
• 設定またはデリバリーポリシー： 影響を受けるライブ設定と関係者を確認します。ブランチルールまたは必須チェックを変更する場合は、デフォルトブランチへの書き込み権限を持つユーザーも含めます。許可された変更を行う前に、変更前の状態とロールバック手順を記録します。
• リリースまたはデプロイ： 担当するスクリプトとランブックを確認してから、対応するリリースまたはデプロイの進め方に従います。どちらの場合も、不変のペイロードを 1 つ公開し、再ビルドせずにそのペイロードをデプロイします。

ローカルでの修正に、ライブポリシーの全項目を確認する必要はありません。依存関係または変更された信頼境界によって必要となる場合に限り、確認範囲を広げてください。

リポジトリ内のコマンドを正とします。申告されたデリバリー範囲を再現可能な形でビルド、検証、パッケージ化、監視、ロールバックできない場合は、その前提条件の不足を報告し、ワークフロー YAML に隠さないでください。

共通契約

• プルリクエストでは、読み取り専用の認証情報を使って信頼できないコードを実行します。
• 信頼されたリリースおよびデプロイのジョブでは、検証と入力または参照の検証が完了してから認証情報を読み込みます。
• ワークフローの権限は、デフォルトで読み取り専用または {} とし、ジョブごとに必要な権限を追加します。
• 信頼度の高いリモート Actions は、レビュー済みの不変なピンを使用し、更新経路を用意します。
• 環境のシークレットとポリシーは、リリースまたはデプロイの影響範囲に合わせます。
• リリース、公開、署名、昇格、デプロイの重要な処理は、キャンセル不可とし、状態を照合できるようにします。
• 検証済みのペイロード 1 つを、ビルド、テスト、公開、デプロイの各境界で受け渡します。
• マトリックス、条件付きレーン、または何もしない経路によって個々のジョブの結果が不安定になる場合、必須チェックには安定した最終結果を使用します。
• このタスクで変更したライブ設定と下流の状態は、変更後に読み戻して確認する必要があります。ワークフローが成功しただけでは、変更が反映された証明になりません。

スキャン、必須チェック、スケジュール、またはリポジトリのセキュリティ機能を追加または変更する場合は、セキュリティのベースラインを参照してください。

ワークフローを追加する場合、またはコード実行、認証情報、公開、署名、デプロイの境界を変更する場合は、Actions のセキュリティを参照してください。

トリガー、ランナー、並行実行、高コストなジョブの選択、または必須チェックの所要時間を設定する場合は、ランナーのコストを参照してください。 新しいリリースまたはデプロイの仕組みを導入する場合は、最も近い保守対象の実装を出発点にしてください。ローカルでの修正では、リポジトリのコードだけで実装上の疑問を解消できない場合に限り、例を参照してください。文字どおりのバージョン、ID、プロバイダーの詳細ではなく、その契約を適用してください。

リポジトリポリシー

マージ方法、ルールセット、必須チェック、署名付きコミット、タグ、Actions ポリシー、Environments、コストに配慮した組織セキュリティのベースライン、CodeQL の体制、リポジトリのメタデータを変更する場合は、リポジトリ設定を確認してください。

要求された変更が対象とする場合を除き、既存の承認、アクター、署名付きコミット、タグ、ステータスチェックのルールを維持してください。チェックを実行することと、チェックを必須にすることは別の操作です。プルリクエストまたはチェックを必須にする前に、リリースボット、依存関係ボット、生成された書き戻し、デフォルトブランチに引き続き書き込むメンテナーを洗い出してください。

デフォルトでプルリクエストを必須にしないでください。リポジトリポリシーが直接更新を許可しており、再現可能なローカルゲートがデフォルトブランチの CI によって標準で再現される場合は、検証済みのファストフォワードプッシュを許可してください。プルリクエストを必須にするのは、マージ前のレビュー、信頼できないコントリビューション、マージキュー、デフォルトブランチが更新される前に合格する必要があるチェック、または所有者による明示的なポリシーがある場合に限ります。プッシュ後の CI はブランチの更新後にリグレッションを検出するため、プッシュ前にローカルゲートを実行し、CI が完了するまで監視してください。

コラボレーション用ファイル

プルリクエストテンプレート、Issue フォーム、SECURITY.md、CONTRIBUTING.md、または共有コミュニティのデフォルトを追加または調整する場合は、テンプレートを確認してください。

• すべてのリポジトリに当てはまるポリシーに限り、公開されるオーナーレベルのデフォルトを優先してください。
• テンプレートは簡潔で、証拠を重視したものにしてください。形だけのチェックリストは避けてください。
• 公開するセキュリティガイダンスには、機能する非公開報告経路が必要です。非公開リポジトリでは、既存の非公開メンテナーチャネルを使用してください。
• Dependabot または Renovate を追加または移行する前に、依存関係の更新を確認してください。リポジトリごとにボットは 1 つだけ使用してください。Dependabot alerts は有効のままにし、Renovate のもとでは Dependabot security updates を無効のままにしてください。Renovate は独自の脆弱性対応プルリクエストを作成します。

リリースとデプロイの経路

リリース作業では、次を使用します。

• 信頼性、公開、署名付き書き戻し、不変のリリース、復旧、完了の証明については、リリースワークフロー
• npm、Swift/CocoaPods、Go、Rust、GitHub Actions、Homebrew、モノレポについては、公開ターゲット
• 選択したツールがそのツールである場合に限り、semantic-release
• 具体的な障害または不整合な永続状態が発生した場合に限り、リリースのトラブルシューティング

デプロイ作業では、次を使用します。

• トリガー、レーン検出、検証済みペイロード、並行実行、監視への引き継ぎについては、デプロイワークフロー
• ターゲットの選択、保護、OIDC、またはプロバイダーの境界を変更する場合は、Environments
• シークレットの所有者またはログ記録を変更する場合は、認証情報
• 具体的な障害が発生した場合に限り、デプロイのトラブルシューティング

検証と完了

ワークフローを変更した場合は、リポジトリのゲートに加えて actionlint と zizmor を実行してください。ライブ配信が対象範囲に含まれ、許可されている場合は、最も範囲の狭い安全な方法でその証明を行ってください。ワークフローのみの変更は、リリースまたはデプロイを許可するものではありません。ライブ環境での証明ができない場合も、許可されたローカル作業は続行し、その未完了部分を報告してください。ドライランや静的検査では、不変の公開、署名付き書き戻し、レジストリまたはタップとの整合性、デプロイ、監視、ロールバックを証明できません。

許可されたライブ変更の後は、対象範囲に含まれるすべての設定、Environment、ルール、リリース、レジストリ、タグ、デプロイ、下流のポインターを読み戻して確認してください。一部失敗した場合は、再試行する前に永続状態を整合させてください。ワークフローを成功させるためだけに、新しいバージョンを作成したり、不変のリリースを変更したりしてはいけません。

出力

files: changed GitHub and documentation surfaces
settings: live changes and readback, or not checked
delivery: target and immutable payload boundary
evidence: local, workflow, and live proof actually exercised
risks: remaining authority, recovery, or downstream gaps