gitタグのpushをトリガーにCodePipelineを構築するパターン

CodePipelineのデプロイトリガーを、ブランチへのpushではなくgitタグのpushにする構成です。「マージ = 即デプロイ」ではなく「タグを打った時だけデプロイされる」という、リリースタイミングを明示的に制御したい場合に向いた構成を整理します。

なぜタグトリガーにするのか

• リリースタイミングを人が制御できる:mainへのマージ後すぐにデプロイされず、任意のタイミングでv1.2.0のようなタグを打った時だけデプロイが走る
• リリース単位が明確になる:どのタグがどのバージョンとしてデプロイされたかがgit historyに残る
• ロールバックの起点が分かりやすい:問題が起きた際、直前のタグに戻すという操作がそのままロールバック手順になる

トレードオフとして、マージのたびに自動デプロイされる開発速度重視の運用はできません。検証環境はブランチpushトリガー、本番相当の環境はタグトリガー、というように環境ごとにトリガー方式を使い分けるのも一般的です。

構成要素

1. パイプラインタイプはV2を指定

タグトリガーはV2パイプラインでのみサポートされています。

resource "aws_codepipeline" "this" {
  name          = "${var.project}-${var.env}-pipeline"
  role_arn      = aws_iam_role.pipeline.arn
  pipeline_type = "V2"
  execution_mode = "QUEUED"

  artifact_store {
    location = aws_s3_bucket.artifacts.bucket
    type     = "S3"
  }

  # trigger ブロックは後述

  stage {
    name = "Source"
    action {
      name             = "GitHub_Source"
      category         = "Source"
      owner            = "AWS"
      provider         = "CodeStarSourceConnection"
      version          = "1"
      output_artifacts = ["source_output"]

      configuration = {
        ConnectionArn        = aws_codestarconnections_connection.github.arn
        FullRepositoryId     = var.github_repository
        BranchName           = var.github_branch
        OutputArtifactFormat = "CODE_ZIP"
        DetectChanges        = "false"
      }
    }
  }
  # Build / Deploy ステージは通常構成と同じ
}

BranchNameは、タグが指すコミットをクローンする際の基点として引き続き必要な項目です。DetectChangesは"false"にし、ブランチへのpush検知は行いません。

2. triggerブロックでタグを指定

resource "aws_codepipeline" "this" {
  # ...(上記に続けて)

  trigger {
    provider_type = "CodeStarSourceConnection"
    git_configuration {
      source_action_name = "GitHub_Source"
      push {
        tags {
          includes = ["v*"]
          excludes = ["v*-rc*"]
        }
      }
    }
  }
}

v*にマッチするタグ(v1.0.0、v2.3.1など)のpushだけがトリガーになります。リリース候補タグ(v1.0.0-rc1など)を除外したい場合はexcludesを併用します。

3. 実行モードはQUEUEDを選択

execution_mode = "QUEUED"

タグ運用は「意図したタイミングで1つずつデプロイする」という性質上、複数のタグを連続でpushした場合でも実行順序が保証されるQUEUEDが適しています。デフォルトのSUPERSEDEDだと、実行中に新しいタグがpushされた際に古い実行が打ち切られてしまい、意図しない実行順になる可能性があります。

運用フロー

タグの命名規則(例:セマンティックバージョニング)を決めた上で、リリースのたびに以下を実行します。

git checkout main
git pull

git tag v1.2.0
git push origin v1.2.0

タグをpushした時点でCodePipelineが起動し、Build(イメージビルド + Flywayマイグレーション)→ Deployが実行されます。buildspec.yml内の$CODEBUILD_RESOLVED_SOURCE_VERSIONはタグが指すコミットのSHAになるため、イメージタグの生成ロジック(コミットSHAの先頭8桁を使う、など)は変更なくそのまま使えます。

注意点

• Terraform側の既知の不具合:aws_codepipelineリソースのtriggerブロックの追加・削除自体をTerraformが検知しないケースが報告されています。terraform planで差分が出ない場合は、AWS CLI(aws codepipeline get-pipeline)で実際の設定を確認するか、リソースをterraform state rmしてから再作成する必要があります
• V2の課金体系:V2パイプラインは実行あたりの課金体系に変わります。個人開発の頻度であれば影響は軽微ですが、事前に料金ページで確認しておくと安心です
• ブランチpushと併用したい場合:pushブロックにbranchesとtagsを両方設定しようとすると、Terraform AWS providerでエラーになる既知の不具合が報告されています。ブランチ・タグ両方のトリガーを持たせたい場合は、挙動を検証しながら進めるのが安全です

まとめ

• タグトリガーの構成には、pipeline_type = "V2"、SourceアクションのDetectChanges = "false"、triggerブロックの3点が必要
• タグ運用にすることで、リリースタイミングを人が制御でき、デプロイ単位がgit historyに残る
• 実行モードはQUEUEDがタグ運用と相性が良い
• Terraform provider側の既知の不具合があるため、terraform planの差分が反映されない場合はAWS CLI側で実際の設定を確認する