CI が自動で本番デプロイまで走る設定では、予期しないリリースが起きるリスクがあります。承認フローを自前スクリプトで実装することもできますが、承認者の記録が残らず、承認できるメンバーの管理も複雑になります。
CircleCI の type: approval を使うと、ワークフローに手動承認ゲートを宣言的に設定できます。本記事では、type: approval の基本的な使い方と、restricted context を組み合わせた承認者の制限方法を解説します。
CircleCIのtype: approval とは？
type: approval を設定したジョブは、手動承認が行われるまでワークフローを on_hold 状態で停止させます。承認されると後続ジョブが実行され、キャンセルされると後続ジョブは実行されません。
approval ジョブは jobs セクションへの定義が不要で、workflows セクション内で直接宣言できます。
version: 2.1
jobs:
build:
docker:
- image: cimg/node:22.16
steps:
- checkout
- run: npm run build
test:
docker:
- image: cimg/node:22.16
steps:
- checkout
- run: npm test
deploy:
docker:
- image: cimg/node:22.16
steps:
- checkout
- run: npm run deploy
workflows:
build-test-deploy:
jobs:
- build
- test:
requires:
- build
- hold: # approval ジョブの宣言
type: approval
requires:
- test
- deploy:
requires:
- hold # hold が承認された場合のみ deploy を実行
hold という名前は任意です。wait・pause・approve-deploy など、意図が伝わる名前を付けられます。approval ジョブの後続ジョブは必ず requires に type: approval を設定したジョブの名前を指定してください。
承認・キャンセルの操作方法
ワークフローが on_hold 状態になると、CircleCI の Web UI でワークフローグラフに承認待ちの表示が出ます。
承認するには hold ジョブをクリックし、表示されるダイアログで Approve job を選択します。
Cancel を選択すると、後続ジョブは実行されずワークフローがキャンセルされます。
API 経由で承認する場合は、次のエンドポイントを使います。
POST /api/v2/workflow/{workflow-id}/approve/{approval-request-id}
デフォルトでは、リポジトリへの write 権限を持つすべてのメンバーが承認操作を行えます。承認者を特定のグループに制限する方法については、次のセクションで解説します。
承認ジョブ名の衝突に注意
approval ジョブには任意の名前を付けられますが、jobs セクションに定義した既存のジョブと同じ名前を使うと、approval ジョブとして動作しません。approval ジョブ名が既存の jobs 定義と衝突しないように、ユニークな名前を付けてください。
# NG: jobs セクションに同名の build ジョブが存在する
jobs:
build:
docker:
- image: cimg/node:22.16
steps:
- run: npm run build
workflows:
example:
jobs:
- build:
type: approval # build という名前は jobs セクションで定義済みのため無効
まとめ
type: approval を使うことで、ワークフローに手動承認ゲートを宣言的に設定できます。承認者・承認タイムスタンプは CircleCI に記録されるため、自前スクリプトでの承認フロー実装が不要になります。restricted context と組み合わせると、承認できるメンバーをセキュリティグループで制限できます。本番環境へのデプロイ権限を適切に管理する際は、Organization Admin の扱いも含めて権限設計を確認しておくことをお勧めします。
参考リンク