Terraform Images

This product is not officially supported by GitLab. We provide it on a community-support basis to allow Terraform users to continue using Terraform with GitLab.

🚨 This repository won't upgrade to any new Terraform releases with the BSL license. Please follow this issue for updates.

We'd like to advise you to use the new OpenTofu CI/CD component.

Alternatively, you may build this project with the latest Terraform release yourself and host it in your own registry.

The OpenTofu support in this repository has been removed in favor of the aforementioned new OpenTofu CI/CD component.

This repository provides a docker image which contains the gitlab-terraform shell script. This script is a thin wrapper around the terraform binary. Its main purpose is to support Infrastructure as code with Terraform and GitLab , by extracting some of the standard configuration a user would need to set up to use the Terraform backend on GitLab as well as the Terraform merge request integration.

Build and host the image and template yourself for up-to-date Terraform

Due to the HashiCorp Terraform license change to BSL, GitLab is no longer legally allowed to distribute Terraform as part of its products. Therefore, this project and the associated Terraform CI/CD templates are deprecated and will not receive regular updates. The following guide explains how you can host and build a container image containing an up-to-date Terraform version and the gitlab-terraform script and deploy it alongside the Terraform CI/CD templates in your own GitLab project.

To build, host, and deploy with Terraform:

1. Mirror this project using a pull mirror. (On GitLab self-managed, you cannot fork from GitLab.com.) You can also:
   • Use a fork on GitLab.com to control the updates from this canonical repository.
   • Use a fork in combination with the pull mirror, so that the pull mirror on the self-managed instance is always up-to-date. Use a fork of the pull mirror to control when to roll out the updates.
2. Change the .terraform-versions matrix in the .gitlab-ci.yml file to the Terraform versions you want to build.
3. Tag the project to trigger a release pipeline. Make sure it succeeds.
4. Include the template in a project on your instance:

include:
  - project: "<path-to-your-mirror-project>"
    file: "/templates/Terraform.gitlab-ci.yml"

default:
  image:
    # The image name is required. The template doesn't set it.
    name: $CI_REGISTRY_HOST/<path-to-your-mirror-project>/releases/<Terraform-version>:<project-version>"

How to use the provided CI templates

Once you built your own image and included the template to your target project, you can further configure the jobs with environment variables.

Required Environment Variables

The wrapper expects three environment variables to be set:

TF_ADDRESS (default: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/default)

Should be the backend URL. For the GitLab backend it will be something like:

"<GITLAB_API_URL>/projects/<PROJECT_ID>/terraform/state/<STATE_NAME>"

• GITLAB_API_URL is the URL of your GitLab API (you can use $CI_API_V4_URL in GitLab CI/CD).
• PROJECT_ID is the id of the project you're using as your infrastructure as code (you can use $CI_PROJECT_ID in GitLab CI/CD)
• STATE_NAME can be arbitrarily defined to the Terraform state name that you create.

TF_USERNAME (default: $GITLAB_USER_LOGIN)

Is your user login name, which must have maintainer access.

TF_PASSWORD (default: $CI_JOB_TOKEN)

An access token created for the above maintainer with the api scope. If this is unset, it will default to the value of CI_JOB_TOKEN and override the TF_USERNAME to match.

Support for GitLab CI Environment Variables

gitlab-terraform exposes the following GitLab CI Environment Variables as TF_VAR inputs

• CI_JOB_ID

• CI_COMMIT_SHA

• TF_VAR_CI_JOB_STAGE

• CI_PROJECT_ID

• CI_PROJECT_NAME

• CI_PROJECT_NAMESPACE

• CI_PROJECT_PATH

• CI_PROJECT_URL

You can use these in your Terraform files in the following way

variable "CI_PROJECT_NAME" {
  type    = string
}

Terraform lockfile handling

If you commit the .terraform.lock.hcl file to your repository we recommend setting TF_INIT_FLAGS to -lockfile=readonly to prevent changes to the lockfile.