Troubleshooting the Terraform integration with GitLab
When you are using the integration with Terraform and GitLab, you might experience issues you need to troubleshoot.
gitlab_group_share_group resources not detected when subgroup state is refreshed
The GitLab Terraform provider can fail to detect existing
due to the issue "User with permissions cannot retrieve
share_with_groups from the API".
This results in an error when running
terraform apply because Terraform attempts to recreate an
For example, consider the following group/subgroup configuration:
parent-group ├── subgroup-A └── subgroup-B
subgroup-Ais shared with
terraform-useris member of
owneraccess to both subgroups.
When the Terraform state is refreshed, the API query
GET /groups/:subgroup-A_id issued by the provider does not return the
subgroup-B in the
shared_with_groups array. This leads to the error.
To workaround this issue, make sure to apply one of the following conditions:
terraform-usercreates all subgroup resources.
- Grant Maintainer or Owner role to the
terraform-userinherited access to
subgroup-Bcontains at least one project.
Invalid CI/CD syntax error when using the base template
You might encounter a CI/CD syntax error when using the Terraform templates:
- On GitLab 14.2 and later, using the
- On GitLab 15.0 and later, using any version of the template.
include: # On 14.2 and later, when using either of the following: - template: Terraform/Base.latest.gitlab-ci.yml - template: Terraform.latest.gitlab-ci.yml # On 15.0 and later, the following templates have also been updated: - template: Terraform/Base.gitlab-ci.yml - template: Terraform.gitlab-ci.yml my-terraform-job: extends: .apply
There are three different causes for the error:
In the case of
.init, the error occurs because the init stage and jobs were removed from the templates, since they are no longer required. To resolve the syntax error, you can safely remove any jobs extending
For all other jobs, the reason for the failure is that the base jobs have been renamed: A
.terraform:prefix has been added to every job name. For example,
.terraform:apply. To fix this error, you can update the base job names. For example:
my-terraform-job: - extends: .apply + extends: .terraform:apply
Use an older version of the template
Breaking changes can occur during major releases. If you encounter a breaking change or want to use an older version of a template, you can update your
.gitlab-ci.yml to refer to an older one. For example:
include: remote: https://gitlab.com/gitlab-org/configure/template-archive/-/raw/main/14-10/Terraform.gitlab-ci.yml
View the template-archive to see which templates are available.
Troubleshooting Terraform state
Unable to lock Terraform state files in CI jobs for
terraform apply using a plan created in a previous job
terraform init, Terraform persists these values inside the plan
cache file. This includes the
As a result, to create a plan and later use the same plan in another CI job, you might get the error
Error: Error acquiring the state lock errors when using
This happens because the value of
$CI_JOB_TOKEN is only valid for the duration of the current job.
Error: "address": required field is not set
By default, we set
If you don't set
TF_ADDRESS in your job, the job fails with the error message
Error: "address": required field is not set.
To resolve this, ensure that either
TF_STATE_NAME is accessible in the
job that returned the error: