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 gitlab_group_share_group resources 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 existing resource.

For example, consider the following group/subgroup configuration:

parent-group
├── subgroup-A
└── subgroup-B

Where:

User user-1 creates parent-group, subgroup-A, and subgroup-B.
subgroup-A is shared with subgroup-B.
User terraform-user is member of parent-group with inherited owner access 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 details of 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:

The terraform-user creates all subgroup resources.
Grant Maintainer or Owner role to the terraform-user user on subgroup-B.
The terraform-user inherited access to subgroup-B and subgroup-B contains 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 latest template.
On GitLab 15.0 and later, using any version of the template.

For example:

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 two 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 .init.
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, .apply became .terraform:apply. To fix this error, you can update the base job names. For example:
```
  my-terraform-job:
-   extends: .apply
+   extends: .terraform:apply
```

Troubleshooting Terraform state

Unable to lock Terraform state files in CI jobs for `terraform apply` using a plan created in a previous job

When passing -backend-config= to terraform init, Terraform persists these values inside the plan cache file. This includes the password value.

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 -backend-config=password=$CI_JOB_TOKEN. This happens because the value of $CI_JOB_TOKEN is only valid for the duration of the current job.

As a workaround, use http backend configuration variables in your CI job, which is what happens behind the scenes when following the Get started using GitLab CI instructions.

Error: "address": required field is not set

By default, we set TF_ADDRESS to ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}. If you don't set TF_STATE_NAME or 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_ADDRESS or TF_STATE_NAME is accessible in the job that returned the error:

Configure the CI/CD environment scope for the job.
Set the job's environment, matching the environment scope from the previous step.