Terraform Module Registry API

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

Use this API to interact with the Terraform CLI.

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.

List available versions for a specific module

List all available versions for a specified 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>" \
  --url "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"
    }
  ]
}

Retrieve latest version for a module

Retrieve information about the latest version for a specified 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>" \
  --url "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"
  ]
}

Retrieve a specific version for a module

Retrieve information about a specific version for a specified 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>" \
  --url "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"
  ]
}

Retrieve download URL for latest module version

Retrieve the download URL for the latest module version in the 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>" \
  --url "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

Retrieve download URL for a specific module version

Retrieve the download URL for a specified module version in the 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>" \
  --url "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>" \
  --url "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>" \
  --url "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 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	no	Specific module version to download. If omitted, the latest version is downloaded.

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

Upload module

Upload a module for a specified project.

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"
}