GitHub と接続する
組織の owner / admin が GitHub App を接続し、申請の対象にするリポジトリを登録します。接続する人には、GitHub 側でも対象組織の管理者権限が必要です。まず接続と登録を進め、ブランチ保護を確認してください。自前配備の運営者向けの App 作成手順は末尾にあります。
GitHub App をインストールする
Section titled “GitHub App をインストールする”- 「設定」の「組織の設定」にある「連携」で、GitHub カードの「GitHub App を接続」を押します。
- GitHub で対象の組織を選びます。
- Only select repositories を選び、対象リポジトリだけを指定します。
- Install を押し、ユーザーの認可を完了して Actagate に戻ります。
- GitHub カードに接続した組織が表示されることを確認します。
標準の製品 App は Actagate(slug actagate、bot 名 actagate[bot])です。運営者が1つの App を持ち、fv もこの App を使います。自前配備の組織だけが自分の App を作ります。
リポジトリを登録する
Section titled “リポジトリを登録する”設定の「GitHub リポジトリ」を開き、接続した組織のリポジトリを読み込みます。対象を選び、設定を入力して登録します。インストール時に選ばなかったリポジトリは、先に GitHub 側で App の対象に追加してください。
| 項目 | 設定する内容 |
|---|---|
| 保護ブランチ | 申請を受け付ける PR の取り込み先。既定は main。複数行で指定 |
| 承認経路 | JSON で指定。null は上長。manager / user / usergroup を使用 |
| マージの仕方 | アプリがマージする方式、または承認チェックだけの方式 |
| マージ方式 | リポジトリの既定、merge、squash、rebase |
| 事前チェック | なし、または Terraform。コメントの投稿者と見出し、または check run の名前を指定 |
| 見守るワークフロー | マージ後の結果を確認するワークフローのファイル名。未設定なら見守りなし |
| 見守りの上限 | 分単位。既定は30分 |
| コピー対応の手順 | API が使えないときに担当者が行う作業 |
| 危険の判定 | paths に対象パスを指定。Terraform は destroy / replace も対象 |
保存すると設定と承認経路が置き換わります。変更前の値を残したい項目も含めて保存してください。設定変更と登録解除は監査に残ります。
ブランチ保護を確認する
Section titled “ブランチ保護を確認する”登録リポジトリの「ブランチ保護の設定を確認する」を押します。保護ブランチごとに保護の有無と必須チェックが表示されます。release/* などのパターンを登録している場合は、GitHub で個々のブランチの保護も確認してください。
ブランチ保護を使えるリポジトリでは、GitHub のリポジトリ設定で対象ブランチの保護を編集し、Require status checks to pass before merging を有効にします。承認チェック Actagate / approval を必須にして保存します。自前の App は、その配備で使うアプリ表示名の承認チェックを選んでください。チェックが一覧にない場合は、申請でチェックが作られてから再確認します。
GitHub が403を返すと、保護を使えない旨が表示されます。契約上の制限だけでなく App の Administration 権限も確認してください。取得に失敗した場合は、GitHub の設定画面で直接確認します。
ブランチ保護を使えない場合のワークフロー
Section titled “ブランチ保護を使えない場合のワークフロー”マージの仕方をアプリがマージする方式にし、適用するジョブの先頭で投稿者を確認します。標準 App の例です。自前の App では bot 名を変更してください。
on: push: branches: [main] workflow_dispatch: inputs: request_id: description: 'Approval request ID' required: true type: stringjobs: apply: runs-on: ubuntu-latest steps: - name: Require approved merge if: github.event_name == 'push' && github.actor != 'actagate[bot]' run: exit 1 - name: Record manual request if: github.event_name == 'workflow_dispatch' run: | REQUEST_ID=$(jq -er '.inputs.request_id' "$GITHUB_EVENT_PATH") test -n "$REQUEST_ID" printf 'Approval request %s\n' "$REQUEST_ID" # Place checkout, validation and deployment steps here.push の判定条件は if: github.actor != 'actagate[bot]' です。例では手動実行の経路を分けるため、イベント名の条件も付けています。人が直接 main へ push すると、このジョブは失敗します。ただし変更自体は main に残り、次に承認されたマージでまとめて適用されます。直接 push とマージを防ぐ保護にはなりません。
コピー対応で人がマージした場合は、承認済みの head SHA と PR を照合します。workflow_dispatch を手動で実行するときは申請 ID を入力し、マージコミットの SHA と run の URL を申請の証跡に記録します。入力欄が必須でも、入力した申請が承認済みかを GitHub が検証するわけではありません。担当者が申請と SHA を確認してください。
自前配備の運営者が App を作る
Section titled “自前配備の運営者が App を作る”GitHub の Developer settings で GitHub App を作ります。
- 名前を決め、Homepage URL に配備先の公開 URL を指定します。
- Callback URL は
https://<app host>/api/settings/github/callbackの1件だけを登録します。Setup URL は使いません。 - Request user authorization (OAuth) during installation をオンにします。Webhook はオフにします。
- インストール先を Any account にします。
- Repository permissions を次の7項目に設定します。
| Repository permission | Access |
|---|---|
| Metadata | Read |
| Contents | Read and write |
| Pull requests | Read and write |
| Checks | Read and write |
| Actions | Read |
| Commit statuses | Read |
| Administration | Read |
Client secret と秘密鍵を生成し、配備環境へ次の5変数を設定します。秘密値をリポジトリや申請の証跡に貼り付けないでください。
| 環境変数 | 値 |
|---|---|
GITHUB_APP_ID |
App ID |
GITHUB_APP_CLIENT_ID |
Client ID |
GITHUB_APP_CLIENT_SECRET |
Client secret |
GITHUB_APP_PRIVATE_KEY |
PEM 形式の秘密鍵。改行または \n を使用 |
GITHUB_APP_SLUG |
App の slug |
設定後に本ページのインストール手順を実施します。戻れない場合は Callback URL と公開 URL、OAuth on install の設定を運営者と確認してください。