Terraform Cloud のVCS連携 実務ガイド: GitHub・GitLab との接続と試験対策

Terraform Cloud/Enterprise はVCS連携を前提に設計されたプラットフォームで、プラン/アプライの自動トリガー、PRコメント、コミットステータス連携が標準機能として提供される。

本稿は GitHub・GitLab 連携の実務と試験で問われやすい論点（連携方式の選択、ワークスペースの紐づけ、トリガー条件、セキュリティ境界）に絞って整理する。

VCS連携の全体像と選択肢

VCS連携は組織（Organization）単位でVCS接続を作成し、各ワークスペースで対象リポジトリ（identifier = 組織/リポジトリ）とブランチを選ぶのが基本である。以後のプラン/アプライはVCSイベントにより自動で駆動される（VCS駆動ワークフロー）。

GitHub では GitHub App 連携が推奨。より細かい権限範囲とリポジトリ単位のインストール制御ができ、PRコメントやコミットステータス更新が安定する。GitLab ではOAuthアプリ連携が一般的で、指定ブランチやディレクトリ配下の変更のみをトリガーにできる。

• VCS駆動とCLI駆動は排他ではないが、同一ワークスペースでの混在は運用を複雑化するため避けるのが定石。
• ワークスペースはブランチ単位に分割するのが基本（例: main=本番、develop=検証）。
• Monorepoでは working_directory と file_triggers/trigger_prefixes を使って影響範囲を限定する。
• PR作成/更新では Speculative Plan（試行プラン）が走り、デフォルトブランチへのマージ後に本プラン/アプライが起動する（auto_applyの有無で自動適用か承認待ちかが変わる）。

VCS駆動ワークフロー（概念）

GitHub 連携（GitHub Appが第一候補）

GitHub では GitHub App 連携が推奨。組織管理者がTerraform Cloud側でGitHub App接続を追加し、GitHub上でアプリを対象リポジトリにインストールする。以降、選択したリポジトリとブランチを各ワークスペースに割り当てるだけでPRコメント・コミットステータス・トリガーが機能する。

試験では、細粒度なリポジトリ選択、最小権限、PRでのSpeculative Plan、デフォルトブランチへのマージで本プラン/適用、という流れを説明できることが重要。既存のOAuth接続があっても、新規ではGitHub Appを優先的に選ぶ前提が問われやすい。

• インストール対象を限定できるため最小権限の原則に合致。
• フォークからのPRは、権限やセキュリティ設定によりイベントが制限される場合があるため、組織ポリシーに合わせて運用を決める。
• PRコメントにはリソース変更要約とplanの要点が掲載され、詳細はTerraform CloudのRunログで確認する。

GitLab 連携（OAuthアプリ）

GitLab ではOAuthアプリを作成し、Terraform Cloud 側のVCSプロバイダ作成画面で指示されるリダイレクト/コールバック設定をGitLabに登録する。接続が確立したら、ワークスペース作成時に対象リポジトリを検索して紐づける。

GitLab連携もPR/MRコメント・コミットステータス・Speculative Planをサポートする。Monorepo の場合は working_directory と trigger_prefixes を設定し、無関係な変更でRunが起動しないようにする。

• 必要なスコープはGitLab側のドキュメントに従い最小限を付与する（一般にAPI/リポジトリアクセス）。
• CI/CD等の他システムと同時利用時はイベント重複に注意し、Terraformの適用はTerraform Cloud側に集約するのが無難。
• 自己ホスト型GitLab（CE/EE）も同様の流れで接続可能。Terraform Enterprise でも原理は同じ。

ワークスペースとブランチ/ディレクトリ設計

VCS連携の単位はワークスペース。一般に環境・境界ごとに分割する（例: app-prod, app-stg）。ブランチは該当環境のソース・オブ・トゥルースに合わせる（例: mainをprod、developをstgに対応）。

Monorepo では working_directory を指定し、file_triggers_enabled と trigger_prefixes を使って変更検知を限定する。これにより、巨大リポジトリでも不要なRunの氾濫を抑えられる。

• working_directory: リポジトリ直下以外にコードがある場合に必須。
• trigger_prefixes: 指定パス配下の変更のみでRunを起動。複数指定可。
• ingress_submodules: trueでGitサブモジュールもクローン（モジュールやポリシーをサブモジュール管理している場合に有効）。
• auto_apply: 本番は通常false（承認必須）、検証環境はtrueも選択肢。

イベント連携とセキュリティの要点

PR/MR作成・更新時はSpeculative Planが走り、結果はPRコメントやコミットステータスで可視化される。デフォルトブランチへのマージが行われると、対象ワークスペースの本プラン/アプライが起動する。ブランチフィルタを設定していれば、そのブランチ以外のpushではRunは起動しない。

セキュリティ上、VCS接続のクレデンシャルはTerraform Cloudの組織スコープで安全に保管され、Run環境へは直接露出しない。クラウドプロバイダの認証情報や機密はワークスペースの環境変数/機密変数で管理し、VCSにコミットしない。

• PRコメントとコミットステータスで「誰が/何を/どこに」適用しようとしているかを可視化。
• フォークからのPRは、接続方式や組織のセキュリティ設定によりイベントが制限されることがある。
• Terraform CloudのIPは公開SaaSであり、通常はVCSからのイベントを受け取れる。エンタープライズ環境ではアウトバウンド/インバウンドの到達性を事前検証する。

IaCとしてVCS連携を管理（tfeプロバイダ）

VCS連携そのものもコードで管理できる。ハッシュコープ公式のtfeプロバイダを用いれば、ワークスペース作成と同時にVCSリポジトリ、ブランチ、作業ディレクトリ、トリガー設定を宣言できる。OAuth/GitHub Appなど組織側の接続作成はUI/APIで先に行い、その識別子（例: oauth_token_id）を参照する。

試験では、tfe_workspace の vcs_repo.identifier は org/repo 形式、working_directory で配下ディレクトリを指定、file_triggers_enabled と trigger_prefixes でMonorepoの不要トリガーを避ける、というポイントが問われやすい。

• ワークスペース命名規則とブランチの対応をコードで固定化。
• auto_apply の既定値を環境別に明示。
• 組織接続ID（例: oauth_token_id）はUIやAPIで払い出し、機密変数として渡す。

tfeプロバイダでワークスペースとVCS連携を作成する例

# tfeプロバイダでTerraform Cloud/Enterpriseを管理
terraform {
  required_providers {
    tfe = {
      source = "hashicorp/tfe"
    }
  }
}

provider "tfe" {
  # Terraform Cloud (SaaS) は hostname 省略可。Terraform Enterprise はホスト名を指定。
  token = var.tfe_token
}

variable "tfe_token" { type = string }
variable "organization" { type = string }
variable "oauth_token_id" { type = string } # 組織のVCS接続（OAuth等）ID

resource "tfe_workspace" "app_prod" {
  name         = "app-prod"
  organization = var.organization

  # Monorepoの一部のみをターゲット
  working_directory     = "infra/terraform"
  file_triggers_enabled = true
  trigger_prefixes      = ["infra/terraform/"]

  # 本番は通常、手動承認にする
  auto_apply = false

  # VCSリポジトリとの紐づけ
  vcs_repo {
    identifier         = "my-org/app-infra"   # org/repo 形式
    branch             = "main"               # 対象ブランチ
    oauth_token_id     = var.oauth_token_id   # 組織のVCS接続ID
    ingress_submodules = true                 # サブモジュールを取得
  }
}

問題で確認

よくある質問