GitHub Actionsでモノレポを安全に自動リリースする設計: 変更検知・段階配布・失敗復旧

モノレポのCI/CDは、単一リポジトリだから楽になる一方で、リリース設計を誤ると一気に難しくなります。

  • 1つの変更で全サービスを再デプロイしてしまう
  • 並列ジョブが増えてキュー渋滞する
  • どのコミットがどのサービスへ反映されたか追跡できない
  • 一部失敗時のロールバックが曖昧

本記事では、GitHub Actionsでモノレポを運用しているチーム向けに、実務で耐えるリリース自動化の構成を具体的に説明します。

1. モノレポCI/CDで先に決める設計原則

最初に次の原則を明文化します。

  1. 変更のないサービスはデプロイしない
  2. リリース対象は機械的に決定する
  3. 本番反映は段階的（canary/割合配布）
  4. 失敗時の復旧手順を自動化する
  5. 監査ログ（誰が何をいつ）を残す

この5つがないと、運用が属人化し、障害時対応が遅れます。

2. 変更検知をワークフローの入口に置く

モノレポでは「どのディレクトリが変わったか」を最初に判定し、対象サービスだけを処理します。

2.1 changed-filesの例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: changed
        uses: tj-actions/changed-files@v45
        with:
          files_yaml: |
            api:
              - services/api/**
            web:
              - services/web/**
            worker:
              - services/worker/**
      - id: set-matrix
        run: |
          python .github/scripts/build_matrix.py '${{ toJson(steps.changed.outputs) }}'

ここでmatrixを作り、後続ジョブを fromJson で動的展開します。

3. reusable workflowで共通化する

各サービスごとにworkflowを複製すると、保守コストが急上昇します。workflow_call で共通化します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# .github/workflows/release-service.yml
on:
  workflow_call:
    inputs:
      service:
        required: true
        type: string
      environment:
        required: true
        type: string

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/release.sh ${{ inputs.service }} ${{ inputs.environment }}

呼び出し側はサービス名だけ渡せばよくなり、ガバナンスが効きます。

4. 同時実行制御（concurrency）で事故防止

同一サービスへの並列デプロイは事故のもとです。concurrency を必ず設定します。

1
2
3

concurrency:
  group: release-${{ github.ref }}-${{ matrix.service }}
  cancel-in-progress: false

cancel-in-progress は本番では通常 false が安全です。途中キャンセルで半端状態を作らないためです。

5. 環境ごとの保護ルールを使う

GitHub Environmentsを使えば、本番前レビューやシークレット分離を標準機能で実装できます。

  • staging: 自動デプロイ
  • production: 承認必須
  • 緊急時のみ管理者がoverride

加えて、OIDCでクラウド認証し、長期鍵（固定アクセスキー）を排除します。

6. 段階リリース（Canary）を組み込む

本番へ一気に100%展開は避け、段階配布をワークフローに組み込みます。

例:

  1. 10%トラフィックへ5分
  2. エラーレート確認
  3. 問題なければ50%
  4. 最終的に100%

疑似コード例:

1
2
3
4
5
6
7
8
9

deploy --service api --traffic 10
sleep 300
check_slo api || rollback api

deploy --service api --traffic 50
sleep 300
check_slo api || rollback api

deploy --service api --traffic 100

check_slo はp95レイテンシ・5xx率・ビジネスKPIを含めるのが理想です。

7. 失敗復旧を「手順」ではなく「機能」にする

運用で強いチームは、ロールバックを手作業Runbookではなくワークフロー化しています。

7.1 rollback workflow例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

on:
  workflow_dispatch:
    inputs:
      service:
        required: true
      target_sha:
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/rollback.sh ${{ github.event.inputs.service }} ${{ github.event.inputs.target_sha }}

「事故時はこのボタンを押す」で復旧できる状態を目指してください。

8. リリース証跡の自動生成

監査対応やトラブル解析で必須になるのが証跡です。

最低限、以下をアーティファクト化します。

  • 対象サービス一覧
  • 対象コミットSHA
  • 実行者
  • 実行時刻
  • 結果（成功/失敗）
  • ロールバック有無

さらにSlack/Discord通知で、サービス単位の反映結果を即時共有すると現場が安定します。

9. コスト最適化も同時に行う

モノレポCIは規模が大きくなるほどコストが効いてきます。

  • キャッシュ（依存/ビルド成果物）を徹底
  • 変更のないサービスはskip
  • 夜間バッチと競合しない時間帯に重いjobを寄せる
  • 自己ホストランナーはautoscaling前提で運用

「全サービス毎回build」は最初は簡単ですが、半年後に必ず負債化します。

10. 導入チェックリスト

  • 変更検知のmatrix生成がある
  • reusable workflowに統一されている
  • concurrency制御がサービス単位で設定済み
  • production環境に承認ルールあり
  • canary + 自動SLO判定がある
  • rollback workflowが存在する
  • リリース証跡を保存している
  • 通知連携（Slack/Discord）が整備されている

まとめ

GitHub Actionsでのモノレポ自動リリースは、単にworkflowを書く作業ではありません。変更検知・段階配布・復旧自動化・監査 を含む運用設計です。

  • デプロイ対象を最小化する
  • 本番反映は必ず段階化する
  • 失敗時の復旧を自動化する
  • 証跡を残して再現性を確保する

この設計を最初に固めると、サービス数が増えても運用は破綻しません。まずは「変更検知 + reusable workflow + rollback workflow」の3点から着手するのが実装コストと効果のバランスが良いです。

付録: 失敗しにくい運用設計テンプレート

最後に、運用へ落とし込むときに有効なテンプレートを示します。実際にはこの3点をチーム標準にするだけで、リリース事故率が下がります。

  • PRテンプレートに「影響サービス」欄を必須化
    • service-a, service-b のように宣言させ、変更検知結果と突合する
  • デプロイ承認時の確認項目を固定化
    • 監視グラフURL、ロールバック手順URL、オンコール担当を毎回入力
  • 失敗後レビューのフォーマット統一
    • 失敗原因、検知時刻、復旧時刻、再発防止策を必ず残す

特にモノレポでは「誰がどこに責任を持つか」が曖昧になりやすいです。workflowの技術実装だけでなく、承認と振り返りの運用ルールをセットにして初めて、自動リリースは安定運用に乗ります。