Skip to content

GitLab

Terraform module registry (FREE)

Introduced in GitLab 14.0.

Publish Terraform modules in your project's Infrastructure Registry, then reference them using GitLab as a Terraform module registry.

Authenticate to the Terraform module registry

To authenticate to the Terraform module registry, you need either:

Publish a Terraform Module

When you publish a Terraform Module, if it does not exist, it is created.

If a package with the same name and version already exists, it will not be created. It does not overwrite the existing package.

Prerequisites:

  • You need to authenticate with the API. If authenticating with a deploy token, it must be configured with the write_package_registry scope.
PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project.
module-name string yes The package name. It can contain only lowercase letters (a-z), uppercase letter (A-Z), numbers (0-9), or hyphens (-) and cannot exceed 64 characters.
module-system string yes The package system. It can contain only lowercase letters (a-z) and numbers (0-9), and cannot exceed 64 characters.
module-version string yes The package version. It must be valid according to the Semantic Versioning Specification.

Provide the file content in the request body.

As the following example shows, requests must end with /file. If you send a request ending with something else, it results in a 404 error {"error":"404 Not Found"}.

Example request using a personal access token:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --upload-file path/to/file.tgz \
     "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file"

Example response:

{
  "message":"201 Created"
}

Example request using a deploy token:

curl --header "DEPLOY-TOKEN: <deploy_token>" \
     --upload-file path/to/file.tgz \
     "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file"

Example response:

{
  "message":"201 Created"
}

Reference a Terraform Module

Prerequisites:

  • You need to authenticate with the API. If authenticating with a personal access token, it must be configured with the read_api scope.

Authentication tokens (Job Token or Personal Access Token) can be provided for terraform in your ~/.terraformrc file:

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

Where gitlab.com can be replaced with the hostname of your self-managed GitLab instance.

You can then reference your Terraform Module from a downstream Terraform project:

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

Publish a Terraform module by using CI/CD

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

For example:

image: curlimages/curl:latest

stages:
  - upload

upload:
  stage: upload
  script:
    - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.tgz "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/my-module/my-system/0.0.1/file"'

Example projects

For examples of the Terraform module registry, check the projects below: