Infrastructure-as-Code Pipelines, Terraform/OpenTofu Workflows, Plan Reviews, State Safety, and Drift Controls: Configuration, Design Choices, and Tradeoffs

1. Design starts with the mutation domain

Before debating YAML, identify the thing that must not receive conflicting mutations: a state name/workspace, a cloud account/region, a Kubernetes cluster namespace, a DNS zone, or another provider-side control plane. That identity drives backend separation, resource_group keys, authorization and rollback scope.

2. Plan on every MR or only trusted branches?

An MR plan is useful feedback only if the MR job is allowed to execute safely. Do not expose production write credentials merely to make a plan widget appear.

3. Saved plan versus re-plan after merge

A saved plan gives strong identity: the apply job consumes the exact reviewed change set. But a plan can become stale when state changes. Re-planning after merge uses fresher state and the merged source, but it creates a different plan from the one reviewed in the MR.

Never describe these as equivalent. If policy says “two people reviewed the MR plan,” it does not automatically mean “two people approved a newly generated production plan.”

4. Automatic apply versus explicit gate

Automatic apply can be appropriate for low-blast-radius, reversible, continuously reconciled environments. Production changes with destructive actions, weak rollback, regulatory obligations or shared state usually deserve a manual/approval control. The gate is not there to compensate for poor automation; it exists to authorize a known mutation after machine evidence is complete.

5. Centralized state versus per-environment state

State should follow ownership and mutation boundaries, not merely repository folders.

6. GitLab-managed state: current role and permission model

GitLab-managed OpenTofu/Terraform state is available on all tiers. Current documentation separates reading state from lock/write operations. For CI, CI_JOB_TOKEN can authenticate supported backend operations, and GitLab’s OpenTofu tooling handles the HTTP backend flow. Use the narrowest project role/job context that supports the required operation.

State is encrypted at rest by GitLab, but that does not make state harmless to readers. Avoid copying it into artifacts or logs.

7. Do not bake job credentials into a saved plan

GitLab documents a failure mode where passing HTTP backend credentials through -backend-config=password=$CI_JOB_TOKEN can persist job-specific configuration into a saved plan. A later apply job has a different token and may fail to lock state. Prefer the supported environment-variable/component configuration so each job authenticates at runtime rather than embedding the previous job’s token.

8. Current reusable pipeline direction: OpenTofu CI/CD component

The removed Terraform CI/CD templates are not a safe 2026 starting point. Pin a released OpenTofu component. Current release 4.8.1 is compatible with a documented set of OpenTofu versions including 1.12.5.

include:
  - component: gitlab.com/components/opentofu/validate-plan-apply@4.8.1
    inputs:
      version: 4.8.1
      opentofu_version: 1.12.5
      root_dir: infra/
      state_name: production

stages: [validate, build, deploy]

For higher assurance, verify the release page, use the component’s signed image support/digest input where practical, and record the resolved component/image identity in the evidence packet.

9. MR plan reports improve review but need a security model

artifacts:reports:terraform can render create/update/delete counts in a merge request. The report artifact is Free-tier available. GitLab also warns that plan data may contain secrets. Treat report generation as a presentation layer: sanitize the report, restrict artifact access, keep the authoritative plan identity separate, and retain only as long as needed.

10. Artifact access and retention are part of IaC design

Current GitLab supports artifacts:access values including developer, and newer releases also support maintainer. Use the narrowest role compatible with your team and remember that job-token access/visibility has separate controls.

artifacts:
  access: maintainer
  expire_in: 12 hours
  paths:
    - plan.cache
    - plan.sha256
    - evidence/plan-metadata.txt

Whether maintainer is appropriate depends on your GitLab version; it was introduced in GitLab 18.4. If you must support older versions, use a compatible access setting plus project/CI visibility controls.

11. Resource-group process mode is an ordering policy, not a lock replacement

Use one resource-group key per state/mutation domain. The default mode is unordered. oldest_first can preserve commit progression; newest_first and newest_ready_first can discard stale ordering assumptions but require idempotent jobs. Change process mode only when you understand how plan freshness and state history interact.

For IaC applies, blindly choosing “newest first” is risky if an older pipeline contains a reviewed prerequisite migration. Ordering must reflect your release model.

12. Drift schedule: detect, classify, then reconcile

A scheduled pipeline can run a read-only plan with -detailed-exitcode. It should retain the exact source, state/backend identity and provider set used for detection. Code 2 creates an issue/alert/review signal. Automatic apply should be a separate, explicit policy for only those resources where the team accepts that behavior.

13. OpenTofu versus Terraform in this GitLab course

Both tools share much of the workflow model, but GitLab’s maintained integration direction is OpenTofu. Terraform remains usable with your own images/templates and backend configuration. Do not assume a GitLab OpenTofu component is also a promise about every Terraform version or license. When a team uses Terraform, record its exact CLI/provider versions and own the pipeline maintenance explicitly.

14. Worked scenario: three environments, one platform team

A team manages dev, staging and prod. Developers need fast MR feedback; only platform maintainers may mutate prod.

15. Decision table

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-12. GitLab-managed OpenTofu/Terraform state and merge-request plan integration are available on Free, Premium, and Ultimate. GitLab’s legacy Terraform CI/CD templates were removed in GitLab 18.0; current guidance is the versioned OpenTofu CI/CD component. GitLab-managed OpenTofu/Terraform state support in the current CLI flow was introduced in GitLab 18.3 and requires glab 1.66+. Plan files are not encrypted by GitLab or OpenTofu and can contain credentials or sensitive values; restrict artifact access and never treat plan output as safe by default. The current released OpenTofu component used for optional examples is 4.8.1; that release supports OpenTofu 1.12.5 and publishes signed rootless images. The standalone local lab pins OpenTofu 1.12.6 (latest stable on the verification date) and hashicorp/local 2.9.0. The component version and supported OpenTofu versions are release-specific. Re-check the selected component release before updating a production pipeline.

• Infrastructure as Code with OpenTofu and GitLab — official reference.
• GitLab-managed Terraform/OpenTofu state — official reference.
• OpenTofu integration in merge requests — official reference.
• CI/CD artifacts reports — terraform — official reference.
• CI/CD YAML syntax — resource_group and artifacts access — official reference.
• Resource groups — official reference.
• GitLab IaC troubleshooting — official reference.
• GitLab OpenTofu CI/CD component — official reference.
• GitLab deprecations and removals — official reference.
• glab opentofu state — official reference.
• OpenTofu 1.12 documentation — official reference.
• OpenTofu releases — official reference.
• HashiCorp local provider — official reference.

Current assumptions used in this chapter: Version-sensitive YAML, Runner/executor behavior, APIs, security features, policy controls, tiers, and deprecations must be verified against the exact GitLab, GitLab Runner, tool, and external-system versions used in production. Preserve the exact project/ref/SHA, compiled configuration, pipeline/job IDs, runner/tool versions, and external target evidence used for reproducible work.