GitHub Actions: Matrixで複数環境を並列実行する

1. 概要

• GitHub Actionsのmatrix strategyとは
• Terraformで複数環境・複数リージョンを並列実行する構成
• matrixで変数を渡してTerraformのworkspace・backend・変数を切り替える
• 失敗した環境だけ再実行する方法

GitHub Actionsのmatrix strategyを使うと、同一ジョブを異なるパラメータで並列実行できます。Terraformでは「複数環境を同時にplanする」「複数リージョンに並列デプロイする」用途に使います。

---

2. 基本的なmatrix構成

# .github/workflows/terraform-matrix.yml
name: Terraform Matrix

on:
  pull_request:
    branches: [main]

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

jobs:
  terraform-plan:
    name: Plan (${{ matrix.environment }})
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false    # 1つ失敗しても他の環境は続ける
      matrix:
        include:
          - environment: dev
            aws_account_id: "123456789001"
            tf_dir: environments/dev
          - environment: stg
            aws_account_id: "123456789002"
            tf_dir: environments/stg
          - environment: prd
            aws_account_id: "123456789003"
            tf_dir: environments/prd

    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ matrix.aws_account_id }}:role/GitHubActionsRole
          aws-region: ap-northeast-1

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "~> 1.9"

      - name: Terraform Init
        run: terraform init -backend-config="bucket=my-tfstate-${{ matrix.environment }}"
        working-directory: ${{ matrix.tf_dir }}

      - name: Terraform Plan
        run: terraform plan -no-color -var="environment=${{ matrix.environment }}"
        working-directory: ${{ matrix.tf_dir }}

---

3. matrixで渡せる変数の例

strategy:
  matrix:
    include:
      # 環境 × リージョンの組み合わせ
      - environment: dev
        region: ap-northeast-1
        instance_type: t3.micro
      - environment: stg
        region: ap-northeast-1
        instance_type: t3.small
      - environment: prd
        region: ap-northeast-1
        instance_type: t3.medium
      - environment: prd-dr
        region: ap-southeast-1    # DR用にシンガポールリージョン
        instance_type: t3.medium

---

4. Terraform側のコード

# environments/dev/main.tf（環境ディレクトリごとに配置）
terraform {
  required_version = ">= 1.9"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  backend "s3" {
    # bucket等はinitの-backend-configで渡す
    key    = "app/terraform.tfstate"
    region = "ap-northeast-1"
  }
}

provider "aws" {
  region = "ap-northeast-1"
}

variable "environment" {
  description = "環境名"
  type        = string
  default     = "dev"
}

data "aws_ami" "amazon_linux_2023" {
  most_recent = true
  owners      = ["amazon"]
  filter {
    name   = "name"
    values = ["al2023-ami-*-x86_64"]
  }
}

resource "aws_instance" "web" {
  ami           = data.aws_ami.amazon_linux_2023.id
  instance_type = "t3.micro"

  root_block_device {
    volume_size = 20
    volume_type = "gp3"
    encrypted   = true
  }

  tags = {
    Name        = "${var.environment}-web"
    Environment = var.environment
    ManagedBy   = "terraform"
  }
}

---

5. apply時のmatrix（順次 vs 並列）

planは全環境を並列で問題ありませんが、applyは環境の依存関係によって順次にすることもあります。

# 並列apply（環境間に依存関係がない場合）
jobs:
  apply:
    strategy:
      matrix:
        environment: [dev, stg, prd]
      fail-fast: false

# 順次apply（dev→stg→prdの順にしたい場合はmatrixより needsチェーンが適切）
# → github_actions_multi_account の構成を参照

---

6. 失敗した環境だけ再実行

GitHub Actionsの “Re-run failed jobs” 機能を使うと、matrix中で失敗した環境のジョブだけを再実行できます。fail-fast: falseを設定しておくことで、1環境が失敗しても他の環境のジョブが続行します。

---

7. 関連記事

• GitHub ActionsでTerraformを実行する方法 — 基本ワークフロー
• GitHub Actions: 複数AWSアカウントへのデプロイ — マルチアカウント
• GitHub Actions: PR時にterraform planをコメントで返す — PRコメント
• Terraform CI/CDのブランチ戦略 — 環境ごとのapply戦略
• モノレポ vs マルチリポ — リポジトリ設計 — monorepo構成
• Terragrunt vs Terraform Workspaces — DRY化の2択 — 環境管理

---

8. まとめ

• matrix strategyで複数環境・リージョンのTerraform planを並列実行できる
• include形式で環境ごとにアカウントID・ディレクトリ・変数を定義するのが扱いやすい
• fail-fast: falseを設定すると1環境失敗でも他の環境は続行する
• 並列planは全環境OK。並列applyは環境間に依存がない場合のみ
• dev→stg→prdの順次デプロイにしたい場合はmatrixではなくneedsチェーン（multi-accountパターン）が適切

---

対象バージョン: Terraform >= 1.9 / GitHub Actions (2024) 公式ドキュメント: https://docs.github.com/ja/actions/using-jobs/using-a-matrix-for-your-jobs

---