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.1.0" tofu-tools image tag.
stage string apply GitLab CI stage.
job_name string "tofu-apply" Name of the generated job (and of its internal .<job_name>--plan--job/--ref hidden jobs). Override to include the component more than once in one pipeline (one apply per stack) without a collision; pair with a tofu-plan whose job_name this apply's plan_job points at.
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.
environment_mode string (none|record|stoppable) "none" none: no GitLab environment (prior behaviour). record: record a deployment to environment_name/deployment_tier and assign resource_group. stoppable: additionally wire environment:on_stop to the job named by on_stop — a tofu-stop job in this pipeline. Selects a hidden-job variant, like plan_source.
environment_name string "" GitLab environment to record. Required for any mode but none.
deployment_tier string "" The environment's tier (production, staging, testing, development, other). Required for any mode but none.
on_stop string "" The stop job's name. Required for stoppable; ignored otherwise.
resource_group string "" Serializes this apply with other jobs deploying the same target (set the paired tofu-stop to the same group). Required for any mode but none.

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

Recording a stoppable environment (a trunk-deployed dev that the Environments-page Stop button strips to baseline — see tofu-stop):

include:
  - component: gitlab.com/phpboyscout/cicd/tofu-apply@<version>
    inputs:
      role_arn: "arn:aws:iam::<account>:role/phpboyscout-automation"
      apply_when: on_success
      environment_mode: stoppable
      environment_name: dev
      deployment_tier: development
      on_stop: tofu-stop
      resource_group: src/dev
  - component: gitlab.com/phpboyscout/cicd/tofu-stop@<version>
    inputs:
      role_arn: "arn:aws:iam::<account>:role/phpboyscout-automation"
      working_directory: src
      var_file: ../env/dev/src.tfvars
      stop_var_file: ../env/dev/stop.tfvars
      environment_name: dev
      deployment_tier: development
      resource_group: src/dev

See also