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
• 🐳 Docker-ready: Designed for CI/CD pipeline

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

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
└── ...

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)
• 🚧 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.