Skip to content

tofu-apply

OIDC-authenticated tofu apply against AWS, applying a binary plan produced by tofu-plan. tofu rejects a stale plan if state moved in between — fail-safe. Manual-gated by default (apply_when: "manual"); set "on_success" to apply automatically.

The plan is retrieved one of two ways, selected by plan_source:

plan_source Retrieval Runs on
job (default) Same pipeline — needs: restores the tfplan.cache artifact from the tofu-plan job in this pipeline. The default branch, where plan + apply co-occur.
ref Cross pipeline — downloads the latest tfplan.cache for plan_job on plan_ref via the GitLab jobs-artifacts API, authenticated with plan_token. Release tags matching tag_pattern — the tag-gated apply model, where a main pipeline banked the plan and the tag pipeline applies it.

The retrieval mode and the trigger are one decision: needs: and rules: both live in a per-mode hidden job that tofu-apply extends — neither can be conditionally interpolated inline. See Explanation: OpenTofu state and caching.

Provider config requirement

The stack's aws provider must not hardcode a profile.

GitLab Free and plan_token

On GitLab Free, plan_token must be overridden with a personal or group access token (Job Artifact → Read) — CI_JOB_TOKEN cannot authenticate the jobs-artifacts API there.

Jobs

Job What it runs
tofu-apply job mode: applies the needs:-restored plan directly. ref mode: downloads the plan via the jobs-artifacts API (curl + unzip), then applies. Both: OIDC token → AWS env vars, tofu init -input=false, tofu apply -input=false tfplan.cache.

Inputs

Input Type Default Description
image_version string "v0.3.0" infra-tools image tag.
stage string apply GitLab CI stage.
working_directory string "." Must match the tofu-plan job's working_directory.
role_arn string (required) ARN of the AWS IAM role to assume via OIDC.
aws_region string "eu-west-2" AWS region.
aud string "sts.amazonaws.com" OIDC audience claim.
apply_when string (manual|on_success) "manual" Gate behind a UI click, or apply automatically once the rule fires.
plan_source string (job|ref) "job" Same-pipeline needs: vs. cross-pipeline jobs-artifacts download.
plan_ref string "" Ref whose latest plan_job artifact to download. Required when plan_source: ref.
plan_job string "tofu-plan" Name of the plan job.
plan_token string "$CI_JOB_TOKEN" Token for the jobs-artifacts API download in ref mode. GitLab Free needs a PAT — see note above. Ignored when plan_source: job.
tag_pattern string '^v[0-9]+\.[0-9]+\.[0-9]+$' RE2 pattern a tag must match for ref-mode apply to run. Ignored when plan_source: job.
state_token string "$CI_JOB_TOKEN" Token for the GitLab HTTP state backend.

Usage

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]
    inputs:
      role_arn: "arn:aws:iam::<account>:role/phpboyscout-automation"
      plan_source: ref
      plan_ref: main
      plan_token: $TF_ARTIFACT_PAT

See also