増えすぎた GitHub Actions を「3層アーキテクチャ」でリファクタリング

長期的にメンテナンス、理解がしやすくなるよう、以下のような 責務を分離した 3 層アーキテクチャ で構成しました。

各層の役割と実装

1. Trigger 層 (トリガー層)

責務: 外部イベントを受け取り、環境固有のパラメータを設定する

Trigger 層は、GitHub のイベント (release, push, workflow_dispatch) を受け取るエントリーポイントです。デプロイロジックは一切含まず、パラメータの定義のみ を行います。

環境別トリガーの固定化

各環境で使用するトリガーを固定することで、一貫性を確保します。環境とトリガーとの対応は GitHub Flow をベースにしています。

実装例: stg 環境の Trigger 層

name: "[app1/stg] Build & Deploy"

on:
  push:
    branches:
      - main
    paths:
      - "services/app1/**"

env:
  SERVICE: app1
  ENVIRONMENT: stg

jobs:
  vars:
    runs-on: ubuntu-latest
    outputs:
      env: ${{ env.ENVIRONMENT }}
      account_id: ${{ steps.get_account_config.outputs.account_id }}
      deploy_role: ${{ steps.get_account_config.outputs.deploy_role }}
    steps:
      - uses: actions/checkout@v5
      - id: get_account_config
        uses: ./.github/actions/get_account_config
        with:
          service: ${{ env.SERVICE }}
          env: ${{ env.ENVIRONMENT }}

  deploy_app:
    needs: vars
    uses: ./.github/workflows/_deploy-app1.yml
    with:
      env: ${{ needs.vars.outputs.env }} # Reusable Workflow では inputs に環境変数を受け取れないため、前ジョブの出力にして渡している
      account_id: ${{ needs.vars.outputs.account_id }}
      deploy_role: ${{ needs.vars.outputs.deploy_role }}

ポイント:

• 環境固有の情報 (SERVICE, ENVIRONMENT) のみを定義
• Reusable Workflow への呼び出しに徹する
• デプロイロジックは一切含まない

2. Reusable Workflow 層 (再利用ワークフロー層)

責務: ビジネスロジックの実装と、差分チェックやビルド・デプロイのオーケストレーション

この層では、workflow_call で呼び出される再利用可能なワークフローを定義します。複数の環境から共通して利用されるため、環境に依存しない汎用的な実装 が重要です。

実装例: Reusable Workflow

name: "[app1] Build & Deploy (Reusable Workflow)"

on:
  workflow_call:
    inputs:
      env:
        required: true
        type: string
        description: "Environment name"
      account_id:
        required: true
        type: string
        description: "Account ID for deployment"
      deploy_role:
        required: true
        type: string
        description: "IAM role ARN for deploy app1"
      deploy_all:
        required: false
        type: boolean
        default: false
        description: "Deploy all components regardless of diff"

jobs:
  check_diff:
    runs-on: ubuntu-latest
    outputs:
      diff_backend: ${{ steps.diff_backend.outputs.changed_files }}
      diff_frontend: ${{ steps.diff_frontend.outputs.changed_files }}
    steps:
      - uses: actions/checkout@v5

      # バックエンドの差分チェック
      - id: diff_backend
        if: ${{ !inputs.deploy_all }}
        uses: ./.github/actions/get_diff
        with:
          file_patterns: |
            services/backend/**
          ignore_file_patterns: |
            services/backend/**/*.md

      # フロントエンドの差分チェック
      - id: diff_frontend
        if: ${{ !inputs.deploy_all }}
        uses: ./.github/actions/get_diff
        with:
          file_patterns: |
            services/frontend/**
          ignore_file_patterns: |
            services/frontend/**/*.md

  # 差分がある場合のみバックエンドをデプロイ
  deploy_backend:
    needs: check_diff
    # 前ジョブの一部がキャンセルされても実行できるように !(failure() || cancelled()) を指定
    if: ${{ ! (failure() || cancelled()) && (needs.check_diff.outputs.diff_backend != '' || inputs.deploy_all) }}
    uses: ./.github/workflows/_deploy_backend.yml
    with:
      env: ${{ inputs.env }}
      account_id: ${{ inputs.account_id }}

  # 差分がある場合のみフロントエンドをデプロイ
  deploy_frontend:
    needs: check_diff
    if: ${{ ! (failure() || cancelled()) && (needs.check_diff.outputs.diff_frontend != '' || inputs.deploy_all) }}
    uses: ./.github/workflows/_deploy_frontend.yml
    with:
      env: ${{ inputs.env }}
      account_id: ${{ inputs.account_id }}

ポイント:

• 標準的な入力パラメータ (env, account_id, deploy_all など) を受け取る
• 差分チェックの結果に基づいてデプロイを制御
• 環境に依存しない汎用的な実装

3. Composite Action 層 (コンポジットアクション層)

責務: 基本的な操作を組み合わせた再利用可能なアクションの提供

この層では、.github/actions/ 配下に配置される共通処理を Composite action として定義します。実装例については OSS として様々な action が提供されているため本記事では割愛します。

実装のポイント

1. 命名規則の統一

ワークフローファイルは、トリガー種別に応じたプレフィックスを付与します。

この命名規則により、ファイル名から 役割とトリガーが一目で分かる ようになります。

2. 標準インターフェースの定義

Reusable Workflow は、以下の標準的な入力パラメータを受け取ります。AWS を対象としているため、アカウントや IAM, ARN といった用語は AWS のそれと対応しています。

on:
  workflow_call:
    inputs:
      env:
        required: true
        type: string
        description: "Environment name"
      account_id:
        required: true
        type: string
        description: "Account ID for deployment"
      deploy_role:
        required: true
        type: string
        description: "IAM role ARN for deploy app1"
      deploy_all:
        required: false
        type: boolean
        default: false
        description: "Deploy all components regardless of diff"

この標準化により、新規サービス追加時のパターンが明確 になります。

3. ドキュメントの充実

ここまでの内容を開発ガイドラインとしてまとめ、チームメンバーに共有します。

• 3 層アーキテクチャの概要と各層の責務
• 環境別トリガー管理の方針
• 命名規則
• 差分ベースデプロイの仕組み
• 標準インターフェース
• 新規サービス追加方法
• 検証方法

これにより、チーム全体で 一貫した実装方針を共有 できます。