Infrastructure as Code with Terraform and GitLab

DETAILS: Tier: Free, Premium, Ultimate Offering: SaaS, self-managed

To manage your infrastructure with GitLab, you can use the integration with Terraform to define resources that you can version, reuse, and share:

• Manage low-level components like compute, storage, and networking resources.
• Manage high-level components like DNS entries and SaaS features.
• Incorporate GitOps deployments and Infrastructure-as-Code (IaC) workflows.
• Use GitLab as a Terraform state storage.
• Store and use Terraform modules to simplify common and complex infrastructure patterns.

Watch a video overview of the features GitLab provides with the integration with Terraform.

Terraform and OpenTofu support

GitLab integrates with both Terraform and OpenTofu. Most features are fully compatible, including:

• GitLab-managed Terraform state
• Terraform integration in merge requests
• Terraform Module Registry

For simplicity, the GitLab documentation refers primarily to Terraform. However, differences between the Terraform and OpenTofu integration are documented.

Integrate your project with Terraform

• IaC Scanning was introduced in GitLab 14.6.

WARNING: The Terraform CI/CD templates are deprecated and will be removed in GitLab 18.0. See the deprecation announcement for more information.

The integration with GitLab and Terraform happens through GitLab CI/CD. Use an include attribute to add the Terraform template to your project and customize from there.

To get started, choose the template that best suits your needs:

• Latest template
• Stable template and advanced template

All templates:

• Use the GitLab-managed Terraform state as the Terraform state storage backend.
• Trigger four pipeline stages: test, validate, build, and deploy.
• Run Terraform commands: test, validate, plan, and plan-json. It also runs the apply only on the default branch.
• Check for security problems using IaC Scanning.

Latest Terraform template (deprecated)

The latest template is compatible with the most recent GitLab version. It provides the most recent GitLab features, but can potentially include breaking changes.

You can safely use the latest Terraform template:

• If you use GitLab.com.
• If you use a self-managed instance updated with every new GitLab release.

Stable and advanced Terraform templates (deprecated)

If you use earlier versions of GitLab, you might face incompatibility errors between the GitLab version and the template version. In this case, you can opt to use one of these templates:

• The stable template with a skeleton that you can built on top of.
• The advanced template to fully customize your setup.

NOTE: In each GitLab major release (for example, 15.0), the latest templates replace the older ones. This process can introduce breaking changes. You can use an older version of the template if you need to.

Use a Terraform template (deprecated)

To use a Terraform template:

1. On the left sidebar, select Search or go to and find your project you want to integrate with Terraform.

2. Select Code > Repository.

3. Edit your .gitlab-ci.yml file, use the include attribute to fetch the Terraform template:

   include:
    # To fetch the latest template, use:
     - template: Terraform.latest.gitlab-ci.yml
    # To fetch the advanced latest template, use:
     - template: Terraform/Base.latest.gitlab-ci.yml
    # To fetch the stable template, use:
     - template: Terraform.gitlab-ci.yml
    # To fetch the advanced stable template, use:
     - template: Terraform/Base.gitlab-ci.yml

4. Add the variables as described below:

   variables:
     TF_STATE_NAME: default
     # If your terraform files are in a subdirectory, set TF_ROOT accordingly. For example:
     # TF_ROOT: terraform/production

5. Optional. Override in your .gitlab-ci.yml file the attributes present in the template you fetched to customize your configuration.

Build and host your own Terraform CI/CD templates

Although GitLab no longer distributes the Terraform CI/CD templates and terraform-images (the underlying job images, including terraform), you can still use Terraform in GitLab pipelines.

To learn how to build and host your own templates and images, see the Terraform Images project.

Terraform template recipes

For GitLab-curated template recipes, see Terraform template recipes.

Integrate your project with OpenTofu

OpenTofu can integrate with all Terraform-specific GitLab features with the GitLab OpenTofu CI/CD component.

You can add a validate, plan, and apply workflow to your pipeline by including the component:

include:
  - component: gitlab.com/components/opentofu/validate-plan-apply@<VERSION>
    inputs:
      version: <VERSION>
      opentofu_version: <OPENTOFU_VERSION>
      root_dir: terraform/
      state_name: production

stages: [validate, build, deploy]

See the OpenTofu CI/CD component README for detailed information about the usage of the component and all available templates and inputs.

Related topics

• View the images that contain the gitlab-terraform shell script.
• Use GitLab as a Terraform Module Registry.
• To store state files in local storage or in a remote store, use the GitLab-managed Terraform state.
• To collaborate on Terraform code changes and Infrastructure-as-Code workflows, use the Terraform integration in merge requests.
• To manage GitLab resources like users, groups, and projects, use the GitLab Terraform provider. The GitLab Terraform provider documentation is available on the Terraform docs site.
• Create a new cluster on Amazon Elastic Kubernetes Service (EKS).
• Create a new cluster on Google Kubernetes Engine (GKE).
• Troubleshoot issues with GitLab and Terraform.