Terraform Module Registry API

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

This is the API documentation for the Terraform Module Registry.

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.

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

Docs

Edit this page to fix an error or add an improvement in a merge request.

Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.

Propose functionality by submitting a feature request.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.

Try GitLab for free with access to all features for 30 days.

Get help

If you didn't find what you were looking for, search the docs.

If you want help with something specific and could use community support, post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLab subscription).

Request support

Terraform Module Registry API

List available versions for a specific module

Latest version for a specific module

Get specific version for a specific module

Get URL for downloading latest module version

Get URL for downloading specific module version

Download module

From a namespace

From a project

Upload module

Help & feedback

Docs

Product

Feature availability and product trials

Get help