Terraform Module Registry API

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

This is the API documentation for the Terraform Module Registry.

{{< alert type=”warning” >}}

This API is used by the Terraform CLI and is generally not meant for manual consumption. Undocumented authentication methods might be removed in the future.

{{< /alert >}}

For instructions on how to upload and install Terraform modules from the GitLab Terraform Module Registry, see the Terraform Module Registry documentation.

List available versions for a specific module

Get a list of available versions for a specific module. 

GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/versions
Attribute Type Required Description
module_namespace string yes The top-level group (namespace) to which Terraform module’s project or subgroup belongs.
module_name string yes The module name.
module_system string yes The name of the module system or provider. 
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/versions"

Example response: 

{
  "modules": [
    {
      "versions": [
        {
          "version": "1.0.0",
          "submodules": [],
          "root": {
            "dependencies": [],
            "providers": [
              {
                "name": "local",
                "version":""
              }
            ]
          }
        },
        {
          "version": "0.9.3",
          "submodules": [],
          "root": {
            "dependencies": [],
            "providers": [
              {
                "name": "local",
                "version":""
              }
            ]
          }
        }
      ],
      "source": "https://gitlab.example.com/group/hello-world"
    }
  ]
}

Latest version for a specific module

Get information about the latest version for a given module. 

GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system
Attribute Type Required Description
module_namespace string yes The group to which Terraform module’s project belongs.
module_name string yes The module name.
module_system string yes The name of the module system or provider. 
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local"

Example response: 

{
  "name": "hello-world/local",
  "provider": "local",
  "providers": [
    "local"
  ],
  "root": {
    "dependencies": []
  },
  "source": "https://gitlab.example.com/group/hello-world",
  "submodules": [],
  "version": "1.0.0",
  "versions": [
    "1.0.0"
  ]
}

Get specific version for a specific module

Get information about a specific version for a given module. 

GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/1.0.0
Attribute Type Required Description
module_namespace string yes The group to which Terraform module’s project belongs.
module_name string yes The module name.
module_system string yes The name of the module system or provider. 
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0"

Example response: 

{
  "name": "hello-world/local",
  "provider": "local",
  "providers": [
    "local"
  ],
  "root": {
    "dependencies": []
  },
  "source": "https://gitlab.example.com/group/hello-world",
  "submodules": [],
  "version": "1.0.0",
  "versions": [
    "1.0.0"
  ]
}

Get URL for downloading latest module version

Get the download URL for latest module version in X-Terraform-Get header 

GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/download
Attribute Type Required Description
module_namespace string yes The group to which Terraform module’s project belongs.
module_name string yes The module name.
module_system string yes The name of the module system or provider. 
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/download"

Example response: 

HTTP/1.1 204 No Content
Content-Length: 0
X-Terraform-Get: /api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/file?token=&archive=tgz

Under the hood, this API endpoint redirects to packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/:module_version/download

Get URL for downloading specific module version

Get the download URL for a specific module version in X-Terraform-Get header 

GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/:module_version/download
Attribute Type Required Description
module_namespace string yes The group to which Terraform module’s project belongs.
module_name string yes The module name.
module_system string yes The name of the module system or provider.
module_version string yes Specific module version to download. 
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/download"

Example response: 

HTTP/1.1 204 No Content
Content-Length: 0
X-Terraform-Get: /api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/file?token=&archive=tgz

Download module

From a namespace 

GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/:module_version/file
Attribute Type Required Description
module_namespace string yes The group to which Terraform module’s project belongs.
module_name string yes The module name.
module_system string yes The name of the module system or provider.
module_version string yes Specific module version to download. 
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/file"

To write the output to file: 

curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/file" --output hello-world-local.tgz

From a project 

GET /projects/:id/packages/terraform/modules/:module_name/:module_system/:module_version
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project.
module_name string yes The module name.
module_system string yes The name of the module system or provider.
module_version string no Specific module version to download. If omitted, the latest version is downloaded. 
curl --user "<username>:<personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/terraform/modules/hello-world/local/1.0.0"

To write the output to file: 

curl --user "<username>:<personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/terraform/modules/hello-world/local/1.0.0" --output hello-world-local.tgz

Upload module 

PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project.
module-name string yes The module name.
module-system string yes The name of the module system or provider.
module-version string yes Specific module version to upload. 
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/my-module/my-system/0.0.1/file"

Tokens that can be used to authenticate:

Header Value
PRIVATE-TOKEN A personal access token with api scope.
DEPLOY-TOKEN A deploy token with write_package_registry scope.
JOB-TOKEN A job token.

Example response: 

{
  "message": "201 Created"
}