AtlantisでTerraformをPR運用する構成と権限設計｜採用条件を解説

Terraformのapplyを誰の端末からも打てる状態は、権限配布と実行順序の両方で無理が出ます。Atlantisは、その実行をプルリクエストのコメントへ集約するセルフホスト型のツールです。この記事では、autoplanが走るまでの流れ、設定が二層に分かれる理由、applyを止める3条件の値域、Atlantisホストへ資格情報が集まるという構造上のリスクを公式ドキュメントの記載に沿って整理し、3方式の比較で採用条件と見送る場面を切り分けます。

まとめ：Atlantis採用が効く条件とGitHub Actions方式を選ぶ分岐点

Atlantisは、webhookを受けてプルリクエスト上で terraform plan を自動実行し、コメントで apply を指示できるOSSです。最新リリースは v0.46.0（2026-06-30公開）で、.tofu と .tofu.json を見てOpenTofuの版も検出します。自前で常時稼働させる前提のため、稼働ホストとその資格情報の設計が導入判断の中心になります。

採用が効くのは、Terraformを置いたリポジトリが複数あり、applyできる人を絞りつつ同時変更を直列化したい体制です。リポジトリが1本で担当が2〜3名なら、GitHub ActionsとTerraformでAWSのCI/CDを構築する手順のOIDC方式のほうが、常時稼働ホストを持たずに済むぶん総コストが低くなります。運用主体を外に出したいならHCP Terraformが候補です。

設計で最も効くのは、applyを止める条件をサーバ側に固定し、リポジトリ側から緩められないようにする一手です。公式ドキュメントは、Atlantisが読む atlantis.yaml がmainブランチではなくプルリクエストのブランチのものだと明記しています。allowed_overrides を広く開けると、承認条件そのものをPRから外せる状態になります。

AtlantisがPRコメントからplanとapplyを実行する仕組みと構成要素

Atlantisの動作は、イベント受信とTerraform実行の2つに分けて捉えると誤解が減ります。

webhook受信からautoplan実行までの流れと4つの登場要素

構成要素は4つです。プルリクエストのイベントを送るVCS、webhookを受け取る常時稼働のAtlantisサーバ、terraformバイナリが動く実行環境、そして tfstate を置くバックエンド。

処理の流れはこうなります。プルリクエストが作られるとVCSがイベントをAtlantisのエンドポイントへ送り、Atlantisがリポジトリをcloneし、変更のあったディレクトリを判定して terraform plan を走らせ、結果をコメントとして書き戻す。この自動判定がautoplanで、対象の決め方は次章の設定に依存します。

atlantis planとatlantis applyというPRコメントの操作単位

手動で回すときは、プルリクエストのコメントに atlantis plan や atlantis apply と書きます。ディレクトリやワークスペース、プロジェクト名を引数で絞れるため、1つのプルリクエストが複数プロジェクトにまたがっても対象を限定できます。

注意が要るのは、applyがマージの前に走る点です。適用に成功してからマージするため、mainブランチは「これから適用する状態」ではなく「すでに適用された状態」を表します。automerge を有効にすると、apply成功後のマージまで自動で進みます。

リポジトリロックが同時applyを直列化する条件とmode指定

同一箇所への同時変更は、リポジトリロックで直列化されます。挙動は repo_locks の mode で決まり、値は on_plan、on_apply、disabled の3つ。on_plan ではplanの時点でロックがかかり、同じ対象の他のプルリクエストは待たされます。

ここは運用の性格で判断が割れます。並行して立つプルリクエストが多い体制で on_plan のままにすると、レビュー段階の待ちが慢性化する。on_apply に寄せると、古い前提で作られたplanが後から適用される余地が生まれます。ロックの単位はプロジェクト、つまりディレクトリとワークスペースの組であり、tfstateの構造とバックエンド設定とは別の層で効いています。

atlantis.yamlとrepos.yamlで決まる実行単位と設定の優先順位

Atlantisの設定は二層構造です。どちらに何を書けるかが、そのまま権限の境界になります。

version 3必須のatlantis.yamlとprojectsで切る実行単位

リポジトリ直下に置く atlantis.yaml のトップレベルキーは、version、automerge、autodiscover、delete_source_branch_on_merge、projects、workflows、allowed_regexp_prefixes です。version は必須で、公式ドキュメントは「must be set to 3」と値まで固定しています。省略した設定ファイルは読み込まれません。

projects 配下では dir が必須項目で、workspace、terraform_version、name、branch、execution_order_group、repo_locks、apply_requirements、plan_requirements、import_requirements を並べられます。terraform_version を個別に指定できるため、版の異なるディレクトリが同居していても実行を分けられる。autodiscover へ任せる選択肢もありますが、本番を含むリポジトリでは明示列挙をおすすめします。

when_modifiedによるautoplan発火条件の絞り込みと除外設定

autoplan は enabled と when_modified の2つで制御します。when_modified に列挙したパターンに合致するファイルが変更されたときだけ、そのプロジェクトのplanが自動で走る仕組みです。

実務で詰まりやすいのは、共通モジュールを別ディレクトリへ切り出したときです。参照元の when_modified にモジュール側のパスを含めておかないと、モジュールだけを直したプルリクエストでautoplanが動かず、差分が見えないまま進んでしまう。分割粒度と when_modified は合わせて決めます。

allowed_overridesが決めるサーバ設定とリポジトリ設定の境界

サーバ側の repos.yaml では、リポジトリ側から上書きしてよいキーを allowed_overrides で列挙します。指定できる値は apply_requirements、workflow、delete_source_branch_on_merge、repo_locking、repo_locks、custom_policy_check。ここに書かなかったキーは、リポジトリ側の atlantis.yaml に書いても効きません。

ワークフローも同じ考え方です。allow_custom_workflows を真にすればリポジトリ側で自由に定義でき、allowed_workflows ならサーバ定義の一覧から選ばせる形に絞れます。本番を含む構成で apply_requirements を allowed_overrides に入れるのは避けます。Atlantisが読むのはプルリクエストのブランチ側のファイルだからです。

apply_requirementsで組む承認ガードレールと権限集中への対処

誰でもapplyできる状態を避ける仕組みが requirements 系のキーです。値域は3つに限られ、防げる事故がそれぞれ異なります。

approved・mergeable・undivergedの3条件と使い分けの基準

plan_requirements、apply_requirements、import_requirements はいずれも approved、mergeable、undiverged を値に取ります。択一ではなく、必要なものを重ねて指定する形です。

見落とされがちなのは undiverged です。プルリクエストを立てた後にmainが先へ進むと、手元のplan結果は現状と食い違っている。その状態でapplyすると意図しない差し戻しや二重適用が起こります。terraform planの差分の読み方を踏まえ、本番相当には3つとも指定するのが安全側です。検証環境まで同じ厳しさにすると回転が落ちるため、プロジェクト単位で差をつけて構いません。

Atlantisホストへ強権限が集まる構造と実行ロールの分離策

Atlantisを入れると、個々のメンバーへapply可能な資格情報を配らずに済みます。ただし権限が消えたのではなく、Atlantisが動くホストへ集約されただけです。公式ドキュメントも、インフラへアクセスできる資格情報を持つサーバで動くため安全な配置が要ると明記しています。

対処は3つあります。環境ごとにAtlantisのインスタンスを分ける。ディレクトリごとにAssumeRoleで実行ロールを切り替え、1つのロールが全環境に届かないようにする。本番相当のプロジェクトだけ apply_requirements を厳しくする。ここは言い切ります。本番と検証を同一インスタンスの同一ロールで回す構成は採りません。侵害時の影響範囲が全環境に及び、権限を集約した利得を上回る損失になるためです。

policy_checkとConftestで機械的に止める変更の線引き

repos.yaml の policy_check を有効にすると、planとapplyの間にポリシー検査の工程が挟まります。既定ではConftestを使い、custom_policy_check を有効にすればConftest以外の検査ツールも組み込めます。

線引きの基準は「レビュアーが見落としても致命的か」で決めます。公開範囲を広げるセキュリティグループ、データストアの削除、IAMの権限追加は、人に委ねず機械側で止める。命名の一貫性は静的な検査に寄せる領域です。何でも止めようとすると例外申請の運用が肥大するため、対象は3〜5ルールに絞って始めます。

セルフホスト運用の防御設定とplan時の任意コード実行というリスク

AtlantisはHTTPエンドポイントを常時さらします。この前提から、防御設定は導入必須の工程です。

–repo-allowlistとwebhook secretで絞る受け付け範囲

公式が挙げる緩和策の第一が --repo-allowlist です。webhookを受け付けるリポジトリを組織配下へ限定し、無関係なイベントで実行が起きないようにします。あわせて webhook secret を環境変数として設定し、リクエストが本当にVCS由来かを検証させる。この2つを外して公開エンドポイントに置く構成は成立しません。

通信とUIの保護も同じ層です。HTTPS化は --ssl-cert-file と --ssl-key-file、Web UIは --web-basic-auth を有効にして利用者名とパスワードを与えます。UIにはロックの状態や実行履歴が並ぶため、開けたままにすると構成情報が外へ出ます。

plan時に外部データソースが動く前提と–allow-fork-prsの扱い

最も見落とされやすいのが、planの段階で任意のコードが動きうるという性質です。公式ドキュメントは、外部データソースやプロバイダを使えば terraform plan の実行中にコードを走らせられ、承認より手前で資格情報を持ち出せると説明しています。承認プロセスを厚くしても、planが承認前に走る以上この経路は閉じません。

さらに、Atlantisが実行する atlantis.yaml はmainブランチのものではなく、プルリクエストのブランチのものです。悪意ある変更は設定ファイルごと持ち込めます。--allow-fork-prs が既定でfalseなのはこのためで、公開リポジトリで有効にする構成は採りません。検討してよいのは、第三者がプルリクエストを立てられない私有リポジトリに限られます。

常時稼働ホスト・バージョン追随・SSL指定に要る運用コストの見積り

Atlantisの費用はライセンス費ではなく運用費として現れます。常時稼働のコンテナまたは仮想マシン、証明書の更新、webhookの到達性監視、本体の版追随。v0.46.0が2026-06-30に出ているようにリリースは継続しており、放置すれば脆弱性対応の遅れが前節のリスクに戻ってきます。

terraformバイナリ側の版管理も同居します。プロジェクトごとの terraform_version 指定に対応する版を実行環境へ用意する必要があり、リポジトリが増えるほど組み合わせが膨らむ。この常時稼働と版追随を引き受ける体制がないなら、導入は先送りしたほうが安全です。担い手を社内に置けない場合は、AWS・Google Cloud・Azureのインフラ構築として実行基盤ごと設計を委託する選択肢があります。

GitHub Actions方式・HCP Terraformとの比較で決める採用条件

Atlantisの採否は単体では決まりません。「applyを統制する」目的には3つの方式が並びます。

Atlantis・GitHub Actions・HCP Terraformの4軸比較表

判断を分けるのは、資格情報の置き場、承認の強制点、同時実行の直列化、運用主体の4点です。

決定的なのは1行目です。OIDC方式が短命の資格情報を都度発行するのに対し、Atlantisだけは常に触れる状態のホストが存在し続ける。この差が前章の分離設計の必要性を生んでいます。

Atlantisが効く条件：複数リポジトリと直列化が要る運用体制

Atlantisを採るべき条件を言い切ります。Terraformを置いたリポジトリが概ね5本以上あり、それぞれに同じ承認ルールを効かせたい。applyできる人を数名に絞りたいが、planは開発者全員がプルリクエスト上で見られるようにしたい。同一プロジェクトへ複数のプルリクエストが日常的に並ぶ。この3つが揃うなら、集約効果が運用コストを上回ります。

1つ目が効くのは、承認条件を repos.yaml へ一度書けば全リポジトリへ同じ規定が及ぶからです。GitHub Actions方式では、リポジトリごとにワークフロー定義を配り、変更のたび全リポジトリへ反映する作業が要る。数が二桁に届くあたりから、この差は無視できない量になります。

GitHub Actions方式で足りる条件とHCP Terraformへ寄せる条件

GitHub Actions方式で足りる条件は明快です。リポジトリが1〜2本で、applyの承認をブランチ保護と環境の承認機能で表現できるなら、Atlantisを立てる必要はありません。OIDCによる短命資格情報の発行と、S3バックエンド側のロックで直列化は成立します。組み方はGitHub ActionsとTerraformでAWSのCI/CDを構築する手順にまとめています。

HCP Terraformへ寄せる条件は、運用主体を社内に持ちたくない場合です。実行キュー、state管理、承認導線がSaaS側で完結し、常時稼働ホストを見る人員が不要になります。ただし費用は従量で積み上がり、実行環境の細かな制御も効きにくくなる。詳細はHCP Terraformの解説記事を参照してください。

Atlantisを見送るべき3条件と、導入前に固める設計項目の順序

導入の可否は、条件を先に列挙して照合するほうが速く決まります。

見送るべき3条件：単一リポジトリ・少人数体制・監査要件の厳しさ

次の3つのいずれかに当てはまるなら見送ります。第一に、Terraformのリポジトリが1本で担当が2〜3名の体制。集約すべき対象がなく、常時稼働ホストの運用費だけが残ります。

第二に、資格情報を常設で保持するサーバを置けない監査要件がある場合。短命資格情報の発行を要件化している組織では、Atlantisの構造そのものが衝突します。第三に、実行基盤を保守する担当を置けない場合です。版追随と証明書更新が滞れば、承認統制のために入れた仕組みが逆に攻撃面になる。この3条件は設定では回避できず、体制側の問題として判断すべきものです。

導入前に決める5項目と、既存CIパイプラインからの段階的な移行手順

採用を決めたら、コードを書く前に次の5項目を確定させます。

1. Atlantisインスタンスを環境ごとに分けるか、単一で実行ロールを切り替えるか
2. apply_requirements に何を指定し、そのうち何を allowed_overrides で開けるか
3. repo_locks の mode を on_plan と on_apply のどちらにするか
4. projects を明示列挙するか autodiscover へ任せるか
5. policy_check で機械的に止めるルールを何本から始めるか

移行は一気に切り替えず、検証環境のディレクトリ1つから始めます。既存のCIパイプラインは残したまま、Atlantis側でplanだけを走らせて結果を突き合わせる。差分の出方が一致してからapplyの権限を移し、最後に既存パイプラインのapply工程を落とします。terraform testによる検証を組んでいるなら、そのテスト実行をカスタムワークフローへ載せると、planの前段で落とせる問題が増えます。

よくある質問

導入検討で問い合わせの多い論点を、公式ドキュメントの記載に沿って整理します。

Atlantisの利用に費用はかかりますか？

Atlantis自体はOSSとして公開されており、ソフトウェアの利用料は発生しません。見積もるべきなのは、常時稼働させるコンテナや仮想マシンの稼働費、証明書やネットワーク周りの構成費、本体とterraformバイナリの版追随にかかる工数です。従量課金は生じませんが、固定的な運用費と保守の担い手が要ります。

applyはマージの前と後、どちらで実行されますか？

Atlantisの標準的な流れでは、applyはマージより前に実行されます。プルリクエスト上で terraform apply を走らせ、適用に成功してからマージする順序です。結果としてmainブランチは「適用済みの状態」を表し、マージ後に適用が失敗して差異が残る事態を避けられます。

OpenTofuを使っている場合でもAtlantisは利用できますか？

利用できます。v0.46.0（2026-06-30公開）で、.tofu および .tofu.json からOpenTofuの版を検出し、既定のautoplanとプロジェクト探索の対象に含める変更が入りました。それ以前の版では自動検出が働かないため、実行環境側でバイナリを揃えたうえでカスタムワークフローとして実行コマンドを定義する組み方になります。

fork元のリポジトリからのPRでもplanは動きますか？

既定では動きません。フォークからのプルリクエストを扱うかは --allow-fork-prs で制御し、この値は既定でfalseです。公開リポジトリで有効にすると、第三者が立てたプルリクエストでAtlantisの実行が起き、plan時の任意コード実行という経路と組み合わさって資格情報の持ち出しにつながります。公開リポジトリでの有効化は避けてください。

autoplanが走らないときは何を確認すればよいですか？

最初に確認するのは、変更したファイルが対象プロジェクトの when_modified のパターンに合致しているかです。共通モジュールを別ディレクトリへ切り出した構成では、参照元の when_modified にモジュール側のパスを含めていないと発火しません。次に atlantis.yaml の version が 3 か、autoplan の enabled が偽になっていないかを見ます。それでも動かなければ、webhookの到達状況をVCS側の配信履歴で確認します。

関連記事

• IaCとは？Infrastructure as Codeの仕組み・メリットと導入判断を解説：前提となるIaCの考え方と導入判断の基準。
• GitHub ActionsとTerraformでAWSのCI/CDを構築する手順：比較したOIDC方式の具体的な組み方。
• HCP Terraformとは？旧Terraform Cloudの機能・料金とHCPでの位置づけ：運用主体を外に出すSaaS型の選択肢。
• terraform planの差分の読み方｜init・apply・destroyの安全手順：PRコメントに返るplan結果を読む前提知識。
• terraform testの書き方｜unitとintegrationの分け方とCIコスト：ワークフローへ組み込む検証の設計。