コンテンツにスキップ

GitHub と接続する

組織の owner / admin が GitHub App を接続し、申請の対象にするリポジトリを登録します。接続する人には、GitHub 側でも対象組織の管理者権限が必要です。まず接続と登録を進め、ブランチ保護を確認してください。自前配備の運営者向けの App 作成手順は末尾にあります。

  1. 「設定」の「組織の設定」にある「連携」で、GitHub カードの「GitHub App を接続」を押します。
  2. GitHub で対象の組織を選びます。
  3. Only select repositories を選び、対象リポジトリだけを指定します。
  4. Install を押し、ユーザーの認可を完了して Actagate に戻ります。
  5. GitHub カードに接続した組織が表示されることを確認します。

標準の製品 App は Actagate(slug actagate、bot 名 actagate[bot])です。運営者が1つの App を持ち、fv もこの App を使います。自前配備の組織だけが自分の App を作ります。

設定の「GitHub リポジトリ」を開き、接続した組織のリポジトリを読み込みます。対象を選び、設定を入力して登録します。インストール時に選ばなかったリポジトリは、先に GitHub 側で App の対象に追加してください。

項目 設定する内容
保護ブランチ 申請を受け付ける PR の取り込み先。既定は main。複数行で指定
承認経路 JSON で指定。null は上長。manager / user / usergroup を使用
マージの仕方 アプリがマージする方式、または承認チェックだけの方式
マージ方式 リポジトリの既定、merge、squash、rebase
事前チェック なし、または Terraform。コメントの投稿者と見出し、または check run の名前を指定
見守るワークフロー マージ後の結果を確認するワークフローのファイル名。未設定なら見守りなし
見守りの上限 分単位。既定は30分
コピー対応の手順 API が使えないときに担当者が行う作業
危険の判定 paths に対象パスを指定。Terraform は destroy / replace も対象

保存すると設定と承認経路が置き換わります。変更前の値を残したい項目も含めて保存してください。設定変更と登録解除は監査に残ります。

登録リポジトリの「ブランチ保護の設定を確認する」を押します。保護ブランチごとに保護の有無と必須チェックが表示されます。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: string
jobs:
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 を確認してください。

GitHub の Developer settings で GitHub App を作ります。

  1. 名前を決め、Homepage URL に配備先の公開 URL を指定します。
  2. Callback URL は https://<app host>/api/settings/github/callback の1件だけを登録します。Setup URL は使いません。
  3. Request user authorization (OAuth) during installation をオンにします。Webhook はオフにします。
  4. インストール先を Any account にします。
  5. 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 の設定を運営者と確認してください。