GitLab Terraform Integration: Provider, State, CI/CD and Module Management

Using GitLab with Terraform creates an end-to-end infrastructure as code workflow where version control, state storage, module distribution, and resource management for GitLab itself all operate inside a single platform. The integration relies on the gitlabhq/gitlab Terraform provider, GitLab’s native HTTP state backend, a private module registry, and CI/CD pipelines that can validate, plan, and apply Terraform changes with approval gates and OIDC-based cloud authentication.

Terraform Provider for GitLab

The gitlabhq/gitlab Terraform provider lets you manage GitLab as code, codifying repository settings, group structures, permissions, and security policies for consistency and auditing. With the gitlabhq/gitlab provider you can manage GitLab resources using an Infrastructure as Code approach to define, version, and automate the configuration of your GitLab environment.

Authentication uses access tokens. For local development a Personal Access Token with api and readapi scopes is used. For production CI/CD automation the predefined CIJOB_TOKEN is used.

Core resources you can define include groups and subgroups, projects, and group memberships with specific access levels like developer or maintainer.

The provider project has been migrated to GitLab and can be found here gitlab-org/terraform-provider-gitlab. Project on GitLab Documentation Issues Discord Server Terraform Provider Office Hour Call.

Core provider capabilities

The GitLab Terraform provider documentation is available on the Terraform docs site.

Managing GitLab Resources with Terraform

Managing GitLab resources with Terraform starts with provider configuration and authentication.

```hcl
terraform {
required_providers {
gitlab = {
source = "gitlabhq/gitlab"
}
}
}

provider "gitlab" {
token = var.gitlab_token
}
```

The guide covers using the Terraform provider for GitLab to configure, authenticate, create core resources like groups & projects, and use the Terraform state backend and module registry.

Recommended next steps include codifying branch protection rules, building a full plan/apply CI/CD pipeline, and managing secrets with protected and masked CI/CD variables.

GitLab as a Version Control System for Terraform

It starts with version control. Keeping your *.tf and *.tfvars files in a GitLab project gives you the usual benefits:

• Every change to your infrastructure definition lands as a Git commit, so you get a clear audit trail of who changed what, when, and why
• Several people can work on the same Terraform configuration at once using feature branches
• Because GitLab keeps the full history, you can review past changes or roll back to a known-good version of your Terraform files whenever something breaks

The rest is about workflow:

Branching and Merging: Use Git branching strategies e.g., Gitflow, GitLab Flow to manage new features, bug fixes, or environment-specific configurations

Terraform State Management in GitLab

GitLab can store Terraform state remotely via its built-in HTTP backend, with encryption, versioning, and automatic state locking to prevent concurrent modifications.

GitLab includes a built-in HTTP Terraform state backend, so you can store state files directly in a GitLab project without an external service like S3. State is scoped per project and protected by GitLab’s access controls. You configure it by pointing the Terraform backend block to your GitLab instance URL with a personal or CI/CD job token for authentication.

GitLab provides native Terraform support through an HTTP state backend with locking and a private module registry for publishing and sharing modules.

State backend configuration example:

hcl terraform { backend "http" { address = "https://gitlab.example.com/api/v4/terraform/state" lock_address = "https://gitlab.example.com/api/v4/terraform/state/lock" unlock_address = "https://gitlab.example.com/api/v4/terraform/state/unlock" } }

How does GitLab manage Terraform state?

• State files are stored in the GitLab project
• Access is controlled by GitLab permissions
• Locking prevents concurrent modifications
• Encryption and versioning are provided by the backend

CI/CD Pipelines for Terraform Automation

GitLab CI/CD pipelines can validate, plan, and apply Terraform, and OIDC lets CI jobs obtain short-lived cloud credentials instead of hardcoding static access keys.

GitLab offers native Terraform integration through its CI/CD pipelines, letting teams plan, validate, and apply infrastructure changes alongside application code in a single platform. It includes a built-in Terraform state backend, merge request diff views for plan output, and access controls that enforce approval workflows before any apply runs.

GitLab CI/CD is a fully integrated pipeline system built into GitLab, with native support for Terraform via a managed terraform CI component and built-in state management through the GitLab Terraform HTTP backend. GitHub Actions is a workflow automation platform for GitHub repos, requiring third-party actions and external state storage.

Pipeline stages typically include:

• Validate
• Plan
• Apply with manual approval

OIDC integration allows CI jobs to obtain short-lived cloud credentials instead of hardcoding static access keys.

Terraform Module Registry

GitLab provides a private Terraform module registry for publishing and consuming versioned modules, and the GitLab Terraform provider can manage GitLab itself.

GitLab provides a private Terraform module registry for publishing and sharing modules.

GitLab can store Terraform state remotely via its built-in HTTP backend, with encryption, versioning, and automatic state locking to prevent concurrent modifications.

Module registry workflow:

Security Best Practices for Terraform and GitLab

The post lists 7 security best practices, including securing state, using OIDC, securing plan artifacts, least privilege, and IaC code scanning with tools like tfsec or checkov.

This guide covers the main ways GitLab and Terraform work together, along with the security and maintenance habits that go with them.

Key practices:

• Secure Terraform state via the HTTP backend with access controls
• Use OIDC for cloud authentication instead of long-lived keys
• Secure plan artifacts in merge requests
• Apply least privilege for CI job tokens and personal access tokens
• Scan IaC code with tools like tfsec or checkov

Recommended next steps also include managing secrets with protected and masked CI/CD variables.

GitLab Terraform CI/CD Template and OpenTofu

The official GitLab Terraform CI/CD template Terraform/Base.gitlab-ci.yml was deprecated following HashiCorp’s license change and was fully removed in GitLab 18.0. If your pipeline still references it, you have two options: pin to a specific older GitLab release e.g., ref: ‘v17.0.0-ee’ to keep using the Terraform-based template, or migrate to GitLab’s OpenTofu CI/CD component, which is the officially recommended path going forward.

OpenTofu is an open-source version of Terraform that expands on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.

GitLab maintains a separate Terraform images repository gitlab-org/terraform-images that you can fork and self-host if you want to continue using Terraform without switching to OpenTofu.

Why use GitLab for Terraform?

• Native Terraform integration through CI/CD pipelines
• Plan, validate, and apply alongside application code
• Built-in Terraform state backend
• Merge request diff views for plan output
• Access controls that enforce approval workflows before any apply runs

Operational Tasks with GitLab and Terraform

The GitLab Terraform provider documentation is available on the Terraform docs site.

Operational examples include:

• Create a new cluster on Amazon Elastic Kubernetes Service EKS
• Troubleshoot issues with GitLab and Terraform
• View the images that contain the gitlab-terraform shell script

Automate Terraform deployments with Spacelift

Automate your infrastructure provisioning and build more complex workflows based on Terraform using policy as code, programmatic configuration, context sharing, drift detection, resource visualization, and many more.

Integration Summary

What We'll Cover:

• GitLab as a Version Control System VCS for your Terraform files
• Securely managing Terraform state files with GitLab's built-in HTTP backend
• Building GitLab CI/CD pipelines for Terraform automation, including OIDC for cloud authentication
• Using GitLab as a private Terraform Module Registry
• Using the GitLab Terraform Provider to manage GitLab resources
• 7 security best practices for your Terraform and GitLab workflows

By the end you'll have a Terraform workflow that runs entirely on GitLab, from version control through to applying changes.

This guide describes how to use Terraform with GitLab, covering CI/CD, State, Modules, and Security.

Conclusion

GitLab Terraform integration provides a complete infrastructure as code lifecycle inside GitLab. The gitlabhq/gitlab provider enables codified management of groups, subgroups, projects, and memberships with developer or maintainer access levels, using Personal Access Tokens with api and readapi scopes for local work and CIJOB_TOKEN for CI/CD automation. State is managed natively via GitLab’s HTTP backend with encryption, versioning, and automatic locking, eliminating external S3 dependencies while keeping state scoped per project and protected by GitLab access controls. CI/CD pipelines validate, plan, and apply Terraform with merge request diff views and approval gates, and OIDC replaces static cloud credentials with short-lived tokens. A private Terraform module registry enables versioned module publishing and consumption within GitLab, while security best practices cover state protection, OIDC, plan artifact security, least privilege, and IaC scanning with tfsec or checkov. The deprecation of the Terraform/Base.gitlab-ci.yml template in GitLab 18.0 and the shift toward OpenTofu as the officially recommended path reflects ongoing changes after HashiCorp’s license change, with the option to pin to v17.0.0-ee or self-host terraform images from gitlab-org/terraform-images. Together these capabilities let teams run an entire Terraform workflow on GitLab from version control through apply.

Sources

1. scalr.com/learning-center/how-to-manage-gitlab-with-terraform
2. spacelift.io/blog/gitlab-terraform
3. scalr.com/learning-center/using-terraform-with-gitlab
4. docs.gitlab.com/user/infrastructure/iac/
5. github.com/gitlabhq/terraform-provider-gitlab