モノレポの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の技術実装だけでなく、承認と振り返りの運用ルールをセットにして初めて、自動リリースは安定運用に乗ります。

CI/CD の事故は、ビルドが失敗することより「漏えいしても気づけない鍵」が残り続けることのほうが深刻です。特に AWS_ACCESS_KEY_ID のような長期シークレットを GitHub Secrets に保存し続ける運用は、便利ですがリスクが高いです。

本記事では、GitHub Actions の OIDC（OpenID Connect）連携を使って、長期鍵を使わずに AWS へデプロイする実践手順をまとめます。単なる設定紹介ではなく、最小権限・ブランチ制限・監査ログ設計まで含めて、明日から本番投入できる形で説明します。

1. まず何が危険なのか：長期シークレット運用の限界

従来構成では、次のような問題が起きます。

• Secret が漏れても検知が遅い（CIログ、誤コミット、権限の広いメンバー）
• ローテーションが後回しになる
• 1つの鍵で複数環境へアクセスできてしまう
• 「誰のどの workflow 実行が何をしたか」が追いにくい

OIDC 連携では、GitHub が発行する短命トークンを信頼し、AWS 側で一時認証情報を払い出します。つまり、保管する鍵そのものを減らすのが最大の価値です。

2. 全体アーキテクチャ

基本フローは以下です。

1. GitHub Actions ジョブが OIDC トークンを取得
2. AWS IAM の OIDC プロバイダとロール信頼ポリシーで検証
3. 条件に一致したジョブだけ AssumeRoleWithWebIdentity
4. 一時クレデンシャルで S3/CloudFront/ECR/ECS へデプロイ

ポイントは「GitHub 側の workflow 制御」だけでなく、AWS 側で repo・branch・workflow を強制することです。

3. AWS 側の初期設定（OIDC Provider + IAM Role）

3.1 OIDC Provider を作成

CLI 例（すでに存在する場合はスキップ）:

1
2
3
4

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1

3.2 信頼ポリシーを厳密化する

以下のように sub と aud を必ず絞ります。

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

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:your-org/your-repo:ref:refs/heads/main"
        }
      }
    }
  ]
}

sub を repo:org/repo:* のように広く取りすぎると、意図しない workflow からも引き受ける可能性があり危険です。

3.3 デプロイ権限ポリシーを分離する

「ロール1個に全部盛り」は避けます。

• deploy-web-prod-role: S3同期 + CloudFront invalidation
• deploy-api-prod-role: ECR push + ECS update
• read-only-audit-role: CloudWatch Logs / Describe 系のみ

環境別（dev/stg/prod）にロールを分離すると、誤デプロイ時の被害半径が大きく減ります。

4. GitHub Actions workflow 実装

最小サンプル:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

name: deploy-web
on:
  push:
    branches: ["main"]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::<ACCOUNT_ID>:role/deploy-web-prod-role
          aws-region: ap-northeast-1

      - name: Build
        run: |
          npm ci
          npm run build

      - name: Upload to S3
        run: aws s3 sync ./dist s3://example-prod-web --delete

      - name: Invalidate CloudFront
        run: aws cloudfront create-invalidation --distribution-id E123456 --paths "/*"

重要なのは permissions.id-token: write を明示する点です。これがないと OIDC トークンを取得できません。

5. 事故を防ぐための実務ルール

5.1 branch protection と environment protection を組み合わせる

• main 直push禁止
• 必ず PR + 1 approval
• production environment には Required reviewers を設定
• 夜間デプロイを禁止したい場合は手動承認ステップを入れる

5.2 workflow ファイル改変の監査

.github/workflows/*.yml の変更は CODEOWNERS で必ずレビュアー固定にします。

1

.github/workflows/*  @platform-team

5.3 self-hosted runner の扱い

OIDC を導入しても、runner 自体が侵害されると意味が薄れます。

• runner をプロジェクト共有にしない（専用化）
• ジョブ後にワークディレクトリをクリーン
• egress 制限をかける
• runner グループを環境ごとに分離

6. トラブルシューティング

症状1: Not authorized to perform sts:AssumeRoleWithWebIdentity

確認ポイント:

1. aud が sts.amazonaws.com になっているか
2. sub が実際の実行 ref と一致しているか（タグ実行でハマりやすい）
3. permissions.id-token: write が設定されているか
4. Role ARN の typo がないか

症状2: main 以外で偶発的にデプロイされた

• workflow の on.push.branches 見直し
• IAM 信頼ポリシー sub を main 固定へ
• 環境保護ルール（Required reviewers）追加

症状3: デプロイは通るが操作が一部失敗

これは IAM 権限不足の可能性が高いです。CloudTrail の eventName と errorCode を見て、必要最小限のアクションだけ追加します。闇雲に * を付けないこと。

7. 段階的な移行計画（既存運用からの切替）

実務では一気に切り替えず、以下の順が安全です。

1. OIDC ロールを作成（既存シークレットは残す）
2. staging workflow だけ OIDC に切替
3. 1週間監視（失敗率・デプロイ時間・CloudTrail）
4. production を OIDC 化
5. 最後に長期シークレットを削除

削除前に「どの workflow がどの secret を参照しているか」を grep で確認しておくと事故が減ります。

1

git grep -n "AWS_ACCESS_KEY_ID\|AWS_SECRET_ACCESS_KEY" .github/workflows

8. 監査ログ設計：何を見れば安全性が上がるか

最低限、次をダッシュボード化すると運用しやすいです。

• AssumeRoleWithWebIdentity 実行回数（日次）
• 失敗イベント数（権限エラー/条件不一致）
• production deploy 実行者（workflow + sha + actor）
• 1回のデプロイで変更された主要リソース数

CloudTrail + CloudWatch Logs Insights での簡易クエリ例:

1
2
3
4
5

fields @timestamp, userIdentity.sessionContext.sessionIssuer.userName, eventName, errorCode
| filter eventSource = "sts.amazonaws.com"
| filter eventName = "AssumeRoleWithWebIdentity"
| sort @timestamp desc
| limit 50

まとめ

OIDC は「設定が新しいから導入する」ものではなく、長期鍵を削減して事故確率を下げるための運用設計です。導入時にやるべきことはシンプルで、次の3つに集約できます。

1. IAM 信頼ポリシーを repo/branch 単位で厳密化する
2. workflow 側で id-token 権限と環境保護を設定する
3. CloudTrail で AssumeRole の監査を継続する

ここまで実施すれば、CI/CD のセキュリティは「頑張って守る」状態から、「漏えいしにくい仕組みで守る」状態へ進化します。まずは staging 1本から置き換えるのがおすすめです。

GitHub Actions は便利ですが、プロジェクトが成長すると「遅い」「不安定」「原因が分かりにくい」という三重苦になりがちです。特に monorepo や複数ランタイム対応（Node/Python/Go など）では、ワークフローの設計次第で CI 時間が 2〜3 倍変わります。

本記事では、実行時間を短くしながら失敗時の調査コストも下げるために、matrix 設計・キャッシュ設計・障害時の確認順序を具体的に整理します。

1. まず「何を並列化するか」を決める

Actions の高速化は、いきなりキャッシュ最適化から入るより、先にジョブ分解を決める方が効きます。原則は次の通りです。

• 並列化すべき: 独立テスト（OS/バージョン別、サービス別）
• 直列にすべき: デプロイ、DB マイグレーション、本番反映
• 依存を分ける: lint/typecheck/test/build を一つに詰め込まない

悪い例は、1ジョブに全部詰め込み、失敗時に最初から再実行するパターンです。良い設計では「lint は通るが test だけ失敗」のように切り分けできます。

2. matrix を作るときの実践ルール

matrix は便利ですが、組み合わせ爆発で逆に遅くなることがあります。例えば os x runtime x db をすべて直積にすると、不要なジョブが大量発生します。そこで include/exclude を活用します。

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

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [20, 22]
    include:
      - os: ubuntu-latest
        node: 22
        coverage: true
    exclude:
      - os: macos-latest
        node: 20

ポイントは次です。

1. 基準環境を1つ決める（例: ubuntu + latest）
2. カバレッジ計測や重い E2E は基準環境だけで実施
3. 互換性確認は軽量テスト中心にする

この設計にすると、品質を落とさずに全体時間を短縮できます。

3. キャッシュは「鍵設計」が9割

actions/cache や setup-node / setup-python のキャッシュを入れても、キー設計が甘いとヒット率が低く、逆に復元時間だけ増えます。

Node.js の例:

1
2
3
4
5
6
7

- uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node }}
    cache: 'npm'
    cache-dependency-path: |
      package-lock.json
      packages/*/package-lock.json

Python (pip) の例:

1
2
3
4
5
6
7

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'
    cache-dependency-path: |
      requirements.txt
      requirements-dev.txt

実務で効くコツ:

• lockfile をキーに含める（依存変化に追従）
• OS・ランタイムバージョンをキーに含める
• monorepo は対象サブディレクトリ単位でキー分割
• restore-keys を入れすぎない（古いキャッシュ復元で不整合）

4. concurrency で「古い実行を止める」

PR に連続 push されると、古い CI が残り続けてランナー枯渇を起こします。concurrency を入れて、最新コミットだけ走らせる構成にします。

1
2
3

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

これだけで無駄実行を大きく減らせます。特にレビュー中に細かい修正を重ねるチームほど効果が高いです。

5. paths-filter で不要ジョブを起動しない

ドキュメント更新だけなのに全テストが走る、という状態はよくあります。dorny/paths-filter で変更範囲に応じてジョブを分岐します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

- uses: dorny/paths-filter@v3
  id: changes
  with:
    filters: |
      backend:
        - 'backend/**'
      frontend:
        - 'frontend/**'

# 例: backend が変わった時だけ実行
if: steps.changes.outputs.backend == 'true'

これにより、実行時間だけでなくランナーコストも下げられます。

6. 失敗時の調査を速くするログ設計

CI が遅い組織は、だいたい「失敗調査も遅い」です。改善するには、次の3点を標準化します。

• 失敗したジョブで artifact（ログ、スクリーンショット、coverage）を必ず保存
• 重要ステップに ::group:: を付けてログを畳む
• flaky テスト検出用に rerun 情報を残す

artifact 例:

1
2
3
4
5
6
7
8

- name: Upload test reports
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: test-report-${{ matrix.os }}-${{ matrix.node }}
    path: |
      reports/
      coverage/

if: always() を忘れると、失敗時ほど証跡が残らないので注意です。

7. self-hosted runner を使う場合の注意点

高速化目的で self-hosted runner を導入する場合、運用事故が増えやすい領域です。

• 毎回クリーンワークスペース化（残骸で再現不能バグ）
• シークレットを runner に永続化しない
• パッチ適用・再起動の定期メンテをスケジュール化
• runner ラベルを用途別に分離（deploy と test を混在させない）

また、デプロイ権限を持つ runner と、PR 由来コードを実行する runner は分離するのが基本です。

8. 実際の改善ステップ（2週間）

Day 1-2: 現状計測

• 平均実行時間、p95 実行時間、失敗率を取得
• 一番遅いジョブ上位3つを特定

Day 3-5: ジョブ分割と matrix 整理

• lint/typecheck/test/build を分離
• matrix の組み合わせを include/exclude で整理

Day 6-8: キャッシュ最適化

• lockfile ベースキーへ統一
• キャッシュヒット率を可視化

Day 9-10: 無駄実行削減

• concurrency + cancel-in-progress
• paths-filter で対象限定

Day 11-14: 運用ルール化

• 失敗時 artifact を全ジョブ標準化
• flaky テスト記録のテンプレート化

この手順で進めると、速度改善だけでなく再発防止まで一気に整います。

9. よくある失敗パターン

パターンA: キャッシュを入れたのに遅い

原因:

• キーが細かすぎて毎回ミスヒット
• 圧縮/復元コストが大きいディレクトリを丸ごとキャッシュ

対処:

• 依存に限定してキャッシュ
• キーに lockfile ハッシュを利用

パターンB: matrix 失敗がノイズ化

原因:

• fail-fast: true で他環境の情報が取れない
• ログ命名が統一されず比較困難

対処:

• fail-fast: false
• artifact 命名規則を統一

パターンC: PR の待ち時間が長い

原因:

• 古いコミットの CI が走り続ける
• 変更範囲に関係ないジョブが常時起動

対処:

• concurrency で古い実行を停止
• paths-filter 導入

10. 運用チェックリスト

• ジョブは責務別に分離されている
• matrix は必要最小限に絞られている
• 依存キャッシュのキーに lockfile が含まれる
• concurrency で古い実行をキャンセルしている
• 変更範囲に応じたジョブ起動制御がある
• 失敗時 artifact が必ず残る

GitHub Actions は「機能を使う」だけでは速くなりません。実行単位の設計、キャッシュ鍵設計、無駄実行抑制、証跡設計をセットで行うと、初めて安定した CI 基盤になります。

複数リポジトリを運用していると、ほぼ同じ CI 設定を各リポジトリにコピーし続ける状態になりがちです。最初は早く見えますが、半年後には「どこに正解があるのかわからない」状態になります。セキュリティパッチを当てたいだけなのに 20 リポジトリを横断修正し、1つだけ取りこぼして監査で指摘される、というのは珍しくありません。

この問題に効くのが GitHub Actions の workflow_call を使った再利用ワークフローです。ただし、単に共通化するだけでは逆に運用事故が増えることがあります。重要なのは、共通化の粒度、権限境界、変更リリース方法を最初に設計することです。

本記事では、実運用で詰まりやすいポイントを中心に、導入から定着までを具体的に解説します。

1. 再利用ワークフローの基本方針

まず押さえるべき方針は次の 3 つです。

1. 再利用ワークフローは「プラットフォーム製品」として扱う
2. 呼び出し側（各アプリ repo）は薄く保つ
3. 破壊的変更はバージョンを切って段階移行する

「共通化＝1ファイルに全部詰め込む」ではありません。lint, test, build, deploy を1個にまとめると、対象外プロジェクトまで影響します。まずは小さく分割し、必要なものだけ組み合わせられる構造にします。

2. 推奨ディレクトリ構成

共通ワークフローを専用 repo に分離しておくと、監査や変更履歴の管理が容易になります。

1
2
3
4
5
6
7
8
9

org-ci-workflows/
  .github/workflows/
    ci-node.yml
    ci-python.yml
    security-scan.yml
    release-tag.yml
  docs/
    onboarding.md
    migration-checklist.md

呼び出し側は以下のように最小化します。

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

name: ci
on:
  pull_request:
  push:
    branches: [main]

jobs:
  node-ci:
    uses: your-org/org-ci-workflows/.github/workflows/ci-node.yml@v1
    with:
      node-version: "22"
      run-e2e: false
    secrets: inherit

この形の利点は、アプリチームが理解すべき YAML が減ることです。CI の標準知識が全員に伝播し、レビューも速くなります。

3. 実務で効く入力設計（inputs）

inputs は API 設計だと考えるべきです。曖昧な真偽値が増えると、挙動が読めなくなります。

悪い例

• enable_special_mode: true
• quick: true

良い例

• test-scope: unit|integration|full
• build-target: web|api|worker
• upload-artifact: true|false

再利用ワークフロー側では型とデフォルト値を明示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

on:
  workflow_call:
    inputs:
      test-scope:
        required: false
        type: string
        default: "unit"
      upload-artifact:
        required: false
        type: boolean
        default: true

入力名を自然言語に寄せすぎないのがコツです。将来の運用者が見て意味がぶれない命名に寄せます。

4. セキュリティ設計：permissions を最小化する

再利用ワークフローの導入後に増える事故が「権限過剰」です。permissions: write-all を残したまま運用すると、意図しないトークン利用で供給網リスクが高まります。

推奨はジョブ単位での最小権限化です。

1
2
3
4

permissions:
  contents: read
  pull-requests: write
  actions: read

デプロイやタグ作成など書き込みが必要な処理だけ、専用ジョブに分離して contents: write を付与します。CI と CD の境界を分けるだけで、攻撃面積をかなり削減できます。

5. キャッシュ設計でハマらないための実践

Actions の高速化でよく使う actions/cache は、キー設計を誤ると逆効果になります。

• キーが粗い: 依存不整合で不安定化
• キーが細かすぎる: キャッシュヒット率低下

Node の例:

1
2
3
4
5
6
7

- uses: actions/setup-node@v4
  with:
    node-version: ${{ inputs.node-version }}
    cache: npm

- run: npm ci
- run: npm test

まずは setup-* の組み込みキャッシュを優先し、複雑な手動キャッシュは必要になってから追加する方が安全です。

6. 導入手順（3週間での現実的移行）

Week 1: 現状分析

1. 全 repo の workflow を収集
2. 共通ジョブを抽出（lint/test/build/security）
3. 失敗率の高い処理を特定

Week 2: 共通 repo 構築

1. org-ci-workflows を作成
2. 2〜3 種類の再利用ワークフローを作る
3. テンプレート repo で先行検証

Week 3: 段階移行

1. 低リスク repo から順次移行
2. 失敗ログを収集し API（inputs）を微調整
3. v1 タグを固定し、全体展開

重要なのは、一気に全 repo を置き換えないことです。先行導入で「どの入力が不足しているか」を把握し、後続 repo の移行コストを下げます。

7. 変更管理：main 直参照を禁止する

呼び出し側で @main を使うと、共通 repo の更新が即時反映されます。これは便利ですが、本番では危険です。事故時に「いつ壊れたか」が追跡しづらくなります。

実運用では次を推奨します。

• 呼び出しは @v1 などのタグ固定
• 破壊的変更は v2 を新規発行
• 重大修正のみ v1.x に backport

さらに、変更通知テンプレートを用意しておくと移行が速くなります。

1
2
3
4
5
6

[CI Workflow Update]
- Target: ci-node.yml
- Change: npm audit step added
- Impact: build time +20-40 sec
- Action Required: none (v1.3.0 auto pickup)
- Rollback: use v1.2.4

8. 監視指標（導入効果を数字で見る）

再利用ワークフローを入れたら、以下を最低でも計測します。

• CI 平均実行時間
• PR あたり失敗回数
• ワークフロー設定変更に伴う障害件数
• セキュリティ警告検出率

導入後 1 か月で、設定差分の削減 と 障害切り分け時間の短縮 が見えてくるはずです。数字が出ない場合は、共通化の粒度が粗すぎる可能性があります。

9. よくある失敗と対策

失敗1: 共通化しすぎて柔軟性が消える

対策: 80%共通 + 20%ローカル上書きの構造にする。例外を許容する。

失敗2: 例外入力が増えて API が壊れる

対策: 四半期ごとに inputs を棚卸し。未使用入力を削除し、破壊的変更はメジャーバージョンへ。

失敗3: Platform Team しか触れない

対策: docs/onboarding.md を整備し、アプリチームが PR で改善できる運用にする。

10. そのまま使える導入チェックリスト

• 共通 repo を作成し、責任者を明確化した
• workflow_call の入力仕様を文書化した
• permissions を最小権限に設定した
• 呼び出し側でタグ固定（@v1）を徹底した
• 先行 repo で 1 週間運用検証した
• ロールバック手順を README に記載した

まとめ

GitHub Actions の再利用ワークフローは、単なる YAML 共通化ではなく、組織の開発基盤を製品として運用する取り組みです。導入の成否は、技術よりも運用設計に左右されます。

• 入力仕様を API として設計する
• 権限を最小化し事故半径を縮小する
• バージョン固定で変更を可観測にする

この3点を守るだけで、CI/CD は「壊れやすい魔法」から「改善可能な仕組み」に変わります。まずは 1 つの再利用ワークフローから始め、3 週間で小さく成功を作るのが最短ルートです。

セルフホストランナーは高速で柔軟です。特定ツールチェーンや社内ネットワーク接続が必要な環境では、ほぼ必須といえます。一方で、設定を誤ると CI/CD が攻撃経路になります。

近年のインシデントでは、依存パッケージ汚染だけでなく「Actions workflow の権限過多」「fork 由来PRでの秘密情報流出」「ランナー残存データ」が問題化しています。

本記事では、セルフホストランナーを安全に運用するための防衛策を、設計レイヤごとに整理します。

脅威モデルを先に定義する

まず守る対象を明確にします。

• リポジトリのソースコード
• Secrets（クラウド鍵、署名鍵、トークン）
• 配布物の完全性（改ざん防止）
• 社内ネットワーク接続経路

攻撃経路は主に次です。

1. 悪意ある PR が workflow を悪用
2. Marketplace Action の supply chain 汚染
3. ランナー上に残る credential / build artifact
4. 過剰な GITHUB_TOKEN 権限

この4点を潰す設計が防御の中心になります。

1. ランナーは「使い捨て」を前提にする

長寿命ランナーは便利ですが、攻撃後の残留リスクが高いです。可能ならジョブ単位で破棄できる ephemeral 構成を採用します。

• Kubernetes + Actions Runner Controller
• VMテンプレートから都度起動
• ジョブ終了後に完全破棄

少なくとも /tmp と workspace を確実に消去し、Docker layer cache の共有範囲を制御してください。

2. workflow 権限を最小化する

permissions: write-all は禁止レベルです。workflowごとに最小権限を明記します。

1
2
3
4

permissions:
  contents: read
  pull-requests: write
  id-token: write

特に id-token: write は OIDC 連携に必要ですが、不要ジョブで許可しないこと。権限漏れがクラウド侵害に直結します。

3. fork PR の実行ポリシーを分離する

外部 fork からの PR で secrets を使うジョブを実行しない設計が必須です。

推奨:

• pull_request イベント: テストのみ、secrets 無し
• pull_request_target: 原則禁止、必要なら厳格レビュー
• デプロイ系は push（保護ブランチ）だけ

また、workflow_run を使って「検証済み成果物だけを次段へ渡す」2段構成にすると安全性が上がります。

4. Action の固定と検証

uses: actions/checkout@v4 のようなタグ指定だけでは、将来更新の影響を受けます。高リスク工程では commit SHA 固定を検討します。

1

- uses: actions/checkout@8ade135a... # SHA pin

加えて、許可済み Action の allowlist を組織ポリシー化します。無制限に Marketplace Action を使わせると監査不能になります。

5. Secrets 管理は OIDC 中心へ

長期固定鍵を GitHub Secrets に置く運用は、漏洩時の被害が大きいです。クラウド連携は OIDC フェデレーションに移行し、短命トークンを発行します。

利点:

• 鍵配布不要
• 期限短い
• リポジトリ/ブランチ条件で絞れる

AWS なら role trust policy に sub 条件を入れ、「main ブランチの release workflow だけ許可」といった制御が可能です。

6. ネットワーク分離と出口制御

セルフホストランナーが社内フラットネットワークに直結している構成は危険です。ランナー専用サブネットを作り、次を実施します。

• egress allowlist（必要ドメインのみ）
• 社内DBへの直接接続禁止
• 管理プレーンと実行プレーン分離

「CIだから社内に近いほど便利」は短期的発想です。侵害前提で最小到達範囲に設計します。

7. 監査ログと改ざん検知

必要なログ:

• workflow 実行者
• 使用ランナーID
• 取得したクラウド権限
• 成果物ハッシュ

さらに、リリース成果物に SBOM と署名（cosign / sigstore）を付与し、配布前検証を自動化します。これで supply chain の追跡性が大きく向上します。

8. 実装チェックリスト（そのまま使える）

• セルフホストランナーは ephemeral 運用
• workflow permissions を最小権限化
• fork PR と deploy workflow を分離
• 高リスク Action は SHA pin
• OIDC による短命認証へ移行
• ネットワーク egress 制限
• artifact 署名と SBOM 生成
• 監査ログを90日以上保持

9. 段階導入プラン（4週間）

• Week1: 権限棚卸し、write-all 排除
• Week2: fork PR ポリシー分離、allowlist導入
• Week3: OIDC移行、固定鍵削減
• Week4: ephemeral runner 化、署名/SBOM実装

一気に変えると運用停止リスクがあるため、週単位で区切るのが現実的です。

まとめ

セルフホストランナーは強力ですが、セキュリティ設計を誤ると CI/CD が最も危険な入口になります。ポイントは「最小権限」「使い捨て」「短命認証」「監査可能性」の4つです。

まずは permissions の最小化と fork PR 分離から始めてください。ここを押さえるだけでも、供給網リスクは大幅に下げられます。

実運用での検知ルール例（SIEM連携）

防御策を実装しても、検知が弱いと侵害を見逃します。次のイベントを SIEM 側で高優先度アラート化してください。

• 深夜帯の workflow 権限変更
• 普段使わないランナーラベルでのジョブ実行
• release workflow で未知の Action 呼び出し
• OIDC 経由で想定外クラウドロールを取得

検知時には自動で repository dispatch を使い、該当リポジトリのデプロイを一時停止する仕組みを入れると被害拡大を防げます。

インシデント対応Runbookの最小構成

供給網インシデントは初動が遅れると致命傷になります。Runbook には最低限次を含めます。

1. 影響範囲特定（対象リポジトリ、workflow、artifact）
2. 該当 Secrets/Role の無効化
3. ランナー群の全廃棄と再構築
4. 直近リリース成果物のハッシュ再検証
5. 監査ログ保全と関係者通知

この手順を平時に演習しておくことで、実際の障害時に迷いを減らせます。

組織導入で効くポリシー

• 新規 workflow はセキュリティレビュー必須
• Action 追加時はリスク評価テンプレート提出
• 重要リポジトリは branch protection + required review を強制
• セルフホストランナーの管理責任者を明確化

技術対策だけでは継続しません。責任分界とレビュー手順を運用ルール化することが、防御の持続性を高めます。

まとめ（運用視点）

最終的に重要なのは「侵害されないこと」ではなく「侵害されても被害を限定し、速く復旧できること」です。セルフホストランナーを使うなら、最初からゼロトラスト前提で設計し、検知・対応まで含めた体制を整えてください。

最後に

現場では「便利だから後で固める」が最も危険です。セルフホストランナーは導入初日から最小権限と隔離を前提に設計し、定期監査で逸脱を戻す運用を続けてください。

追加の運用Tip

新しいリポジトリを作るたびに同じ議論をしないため、テンプレートリポジトリへ安全な workflow 雛形を同梱しておくと効果的です。初期状態を安全側に固定するだけで、運用負荷と事故率の両方を下げられます。

継続的な棚卸しを習慣化してください。