terraform-gitlab-drift

terraform-gitlab-drift

Detect GitLab resources not managed by Terraform and generate Terraform code to bring them under management.

Uses the GitLab Terraform Provider resource definitions.

Features

• 🔍 Drift Detection: Scan GitLab groups and projects to identify resources not managed by Terraform
• 📝 Code Generation: Automatically generate Terraform code for unmanaged resources
• 🔄 Diff Comparison: Show differences between existing and generated Terraform configurations
• 📦 Import Commands: Generate terraform import commands for new resources
• 🔀 Merge Request Creation: Automatically create or update GitLab MRs with generated .tf files
• 🐳 Docker-ready: Designed for CI/CD pipelines

Quick Start

Local Installation

go install github.com/xMoelletschi/terraform-gitlab-drift@latest
terraform-gitlab-drift scan --group my-group

GitLab CI Usage

Basic Drift Check

drift-check:
  image: ghcr.io/xmoelletschi/terraform-gitlab-drift:latest
  script:
    - terraform-gitlab-drift scan --group $CI_PROJECT_ROOT_NAMESPACE

Auto-create MR on Drift

drift-remediation:
  image: ghcr.io/xmoelletschi/terraform-gitlab-drift:latest
  script:
    - terraform-gitlab-drift scan --group $CI_PROJECT_ROOT_NAMESPACE --create-mr --show-diff=false

When drift is detected, this creates (or updates) a merge request in the current repository with the generated .tf files. The target repo is auto-detected from the git remote; use --target-repo to override.

Configuration

Command-line Flags

Directory Structure

The tool generates one .tf file per GitLab namespace, using normalized names (lowercase, / and - replaced with _). Your Terraform directory should follow this structure to get accurate drift detection:

terraform/
├── backend.tf
├── providers.tf
├── my_group.tf             # generated: top-level group + its projects
├── my_group_sub_group.tf   # generated: sub-group + its projects
├── group_membership.tf     # generated: variable with group → user memberships
├── project_membership.tf   # generated: variable with project → shared groups
├── group_labels.tf         # generated: variable with group → labels
├── project_labels.tf       # generated: variable with project → labels
└── ...

Important: The drift check only compares files that match the generated filenames. If you have resources defined in differently named files (e.g. main.tf, projects.tf), they will not be detected and the tool will report those resources as unmanaged.

To fix this, move your resource definitions into the files matching the generated naming convention, or use --overwrite to let the tool manage the file structure for you.

Supported Resources

• ✅ GitLab Groups (gitlab_group)
• ✅ GitLab Group Memberships (gitlab_group_membership)
• ✅ GitLab Projects (gitlab_project)
• ✅ GitLab Project Share Groups (gitlab_project_share_group)
• ✅ GitLab Group Labels (gitlab_group_label)
• ✅ GitLab Project Labels (gitlab_project_label)
• 🚧 More resources coming soon

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Push to the branch (git push origin feature/amazing-feature)
4. Open a Pull Request

Please make sure to:

• Add tests for new features
• Update documentation as needed
• Ensure CI checks pass

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

Built with:

• Cobra - CLI framework
• GitLab Go SDK - GitLab API client
• HCL - Terraform configuration parsing

Note: This tool is not affiliated with HashiCorp or GitLab.