Terraform Module Registry

With the Terraform Module Registry, you can:

• Use GitLab projects as a private registry for Terraform modules.
• Create and publish modules with GitLab CI/CD, which can then be consumed from other private projects.

Authenticate to the Terraform Module Registry

To authenticate to the Terraform Module Registry, you need either:

• A personal access token with at least the read_api scope.
• A CI/CD job token.
• A deploy token with the read_package_registry or write_package_registry scope, or both.

When using the API:

• If you authenticate with a deploy token, you must apply the write_package_registry scope to publish a module. To download a module, apply the read_package_registry scope.
• If you authenticate with a personal access token, you must configure it with at least the read_api scope.

Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future.

Prerequisites

To publish a Terraform module:

• You must have at least the Developer role.

To delete a module:

• You must have at least the Maintainer role.

Publish a Terraform module

Publishing a Terraform module creates it if it does not exist.

After you publish a Terraform module, you can view it in the Terraform Module Registry page.

With the API

Publish Terraform modules by using the Terraform Module Registry API.

PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file

Provide the file content in the request body.

Requests must end with /file. If you send a request ending with something else, it results in a 404 Not Found error.

curl --fail-with-body --header "PRIVATE-TOKEN: <your_access_token>" \
     --upload-file path/to/file.tgz \
     --url "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/<your_module>/<your_system>/0.0.1/file"

curl --fail-with-body --header "DEPLOY-TOKEN: <deploy_token>" \
     --upload-file path/to/file.tgz \
     --url "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/<your_module>/<your_system>/0.0.1/file"

Example response:

{
  "message":"201 Created"
}

With a CI/CD template (recommended)

You can use the Terraform-Module.gitlab-ci.yml or the advanced Terraform/Module-Base.gitlab-ci.yml CI/CD template to publish a Terraform module to the GitLab Terraform Module Registry:

include:
  template: Terraform-Module.gitlab-ci.yml

The pipeline contains the following jobs:

• fmt: Validates the formatting of the Terraform module
• kics-iac-sast: Tests the Terraform module for security issues
• deploy: Deploys the Terraform module to the Terraform Module Registry (for tag pipelines only)

Use pipeline variables

Configure the pipeline with the following variables:

Configure CI/CD manually

To work with Terraform modules in GitLab CI/CD, use a CI_JOB_TOKEN in place of the personal access token in your commands.

For example, this job uploads a new module for the local system provider and uses the module version from the Git commit tag:

stages:
  - deploy

upload:
  stage: deploy
  image: curlimages/curl:latest
  variables:
    TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR}    # The relative path to the root directory of the Terraform project.
    TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME}  # The name of your Terraform module, must not have any spaces or underscores (will be translated to hyphens).
    TERRAFORM_MODULE_SYSTEM: local             # The system or provider your Terraform module targets (ex. local, aws, google).
    TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # The version - it's recommended to follow SemVer for Terraform Module Versioning.
  script:
    - TERRAFORM_MODULE_NAME=$(echo "${TERRAFORM_MODULE_NAME}" | tr " _" -) # module-name must not have spaces or underscores, so translate them to hyphens
    - tar -vczf /tmp/${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git .
    - 'curl --fail-with-body --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}"
         --upload-file /tmp/${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz
         ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/${TERRAFORM_MODULE_NAME}/${TERRAFORM_MODULE_SYSTEM}/${TERRAFORM_MODULE_VERSION}/file'
  rules:
    - if: $CI_COMMIT_TAG

To trigger this upload job, add a Git tag to your commit. Ensure the tag follows the required semantic versioning specification for Terraform. The rules:if: $CI_COMMIT_TAG ensures that only tagged commits to your repository trigger the module upload job.

For other ways to control jobs in your CI/CD pipeline, see the CI/CD YAML syntax reference.

Module resolution workflow

When you upload a new module, GitLab generates a path for the module. For example:

• https://gitlab.example.com/parent-group/my-infra-package

This path conforms with the Terraform Module Registry Protocol, where:

• gitlab.example.com is the hostname.
• parent-group is the unique, top-level namespace of the Terraform Module Registry.
• my-infra-package is the name of the module.

If duplicates are not allowed, the module name and version must be unique in all groups, subgroups, and projects under parent-group. Otherwise, you receive the following error:

• {"message":"A module with the same name already exists in the namespace."}

If duplicates are allowed, module resolution is based on the most recently published module.

For example, if:

• The project is gitlab.example.com/parent-group/subgroup/my-project.
• The Terraform module is my-infra-package. If duplicates are allowed, my-infra-package is a valid module. If duplicates are not allowed, the module name must be unique in all projects in all groups under parent-group.

When you name a module, keep these naming conventions in mind:

• Your project and group names must not include a dot (.). For example, source = "gitlab.example.com/my.group/project.name" is invalid.
• Module versions should follow the semantic versioning specification.

Allow duplicate Terraform modules

By default, the Terraform Module Registry enforces uniqueness for module names in the same namespace.

To allow publishing duplicate module names:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > Packages and registries.
3. In the Terraform module row of the Duplicate packages table, turn off the Allow duplicates toggle.
4. Optional. In the Exceptions text box, enter a regular expression that matches the names of modules to allow.

Your changes are automatically saved.

You can also allow publishing duplicate names by enabling terraform_module_duplicates_allowed in the GraphQL API.

To allow duplicates with specific names:

1. Ensure terraform_module_duplicates_allowed is disabled.
2. Use terraform_module_duplicate_exception_regex to define a regex pattern for the module names you want to allow duplicates for.

The top-level namespace setting takes precedence over the child namespace settings. For example, if you enable terraform_module_duplicates_allowed for a group, and disable it for a subgroup, duplicates are allowed for all projects in the group and its subgroups.

For more information on module resolution, see module resolution workflow

View Terraform modules

To view Terraform modules in your project or group:

1. On the left sidebar, select Search or go to and find your project or group.
2. Select Operate > Terraform modules.

You can search, sort, and filter modules on this page.

To view a module’s README file:

1. From the Terraform Module Registry page, select a Terraform module.
2. Select README.

Reference a Terraform module

Reference a module from a group or project.

From a namespace

You can provide authentication tokens (job tokens, personal access tokens, or deploy tokens) for terraform in environment variables.

You should add the prefix TF_TOKEN_ to the domain name of environment variables, with periods encoded as underscores. For more information, see Environment Variable Credentials.

For example, the value of a variable named TF_TOKEN_gitlab_com is used as a deploy token when the CLI makes service requests to the hostname gitlab.com:

export TF_TOKEN_gitlab_com='glpat-<deploy_token>'

This method is preferred for enterprise implementations. For local or temporary environments, you might want to create a ~/.terraformrc or %APPDATA%/terraform.rc file:

credentials "<gitlab.com>" {
  token = "<TOKEN>"
}

Where gitlab.com can be replaced with the hostname of your GitLab Self-Managed instance.

You can then refer to your Terraform module from a downstream Terraform project:

module "<module>" {
  source = "gitlab.com/<namespace>/<module-name>/<module-system>"
}

From a project

To reference a Terraform module using a project source, use the fetching archives over HTTP source type provided by Terraform.

You can provide authentication tokens (job tokens, personal access tokens, or deploy tokens) for terraform in your ~/.netrc file:

machine <gitlab.com>
login <USERNAME>
password <TOKEN>

Where gitlab.com can be replaced with the hostname of your GitLab Self-Managed instance, and <USERNAME> is your token username.

You can refer to your Terraform module from a downstream Terraform project:

module "<module>" {
  source = "https://gitlab.com/api/v4/projects/<project-id>/packages/terraform/modules/<module-name>/<module-system>/<module-version>"
}

If you need to reference the latest version of a module, you can omit the <module-version> from the source URL. To prevent future issues, you should reference a specific version if possible.

If there are duplicate module names in the same namespace, referencing the module from the namespace level installs the recently published module. To reference a specific version of a duplicate module, use the project-level source type.

Download a Terraform module

To download a Terraform module:

1. On the left sidebar, select Operate > Terraform modules.
2. Select the name of the module you want to download.
3. From the Assets table, select the module you want to download.

Delete a Terraform module

You cannot edit a Terraform module after you publish it in the Terraform Module Registry. Instead, you must delete and recreate it.

You can delete modules by using the packages API or the UI.

To delete a module in the UI, from your project:

1. On the left sidebar, select Operate > Terraform modules.
2. Find the name of the package you want to delete.
3. Select Delete.

The package is permanently deleted.

Disable the Terraform Module Registry

The Terraform Module Registry is automatically enabled.

For GitLab Self-Managed instances, a GitLab administrator can disable Packages and registries, which removes this menu item from the sidebar.

You can also remove the Terraform Module Registry for a specific project:

1. In your project, go to Settings > General.
2. Expand the Visibility, project features, permissions section and toggle Packages off.
3. Select Save changes.

Example projects

For examples of the Terraform Module Registry, check the projects below:

• The GitLab local file project creates a minimal Terraform module and uploads it into the Terraform Module Registry using GitLab CI/CD.
• The Terraform module test project uses the module from the previous example.