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.

Copy to clipboard
GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/versions
AttributeTypeRequiredDescription
module_namespacestringyesThe top-level group (namespace) to which Terraform module’s project or subgroup belongs.
module_namestringyesThe module name.
module_systemstringyesThe name of the module system or provider.
Copy to clipboard
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/versions"

Example response:

Copy to clipboard
{
  "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.

Copy to clipboard
GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system
AttributeTypeRequiredDescription
module_namespacestringyesThe group to which Terraform module’s project belongs.
module_namestringyesThe module name.
module_systemstringyesThe name of the module system or provider.
Copy to clipboard
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local"

Example response:

Copy to clipboard
{
  "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.

Copy to clipboard
GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/1.0.0
AttributeTypeRequiredDescription
module_namespacestringyesThe group to which Terraform module’s project belongs.
module_namestringyesThe module name.
module_systemstringyesThe name of the module system or provider.
Copy to clipboard
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:

Copy to clipboard
{
  "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

Copy to clipboard
GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/download
AttributeTypeRequiredDescription
module_namespacestringyesThe group to which Terraform module’s project belongs.
module_namestringyesThe module name.
module_systemstringyesThe name of the module system or provider.
Copy to clipboard
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/download"

Example response:

Copy to clipboard
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

Copy to clipboard
GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/:module_version/download
AttributeTypeRequiredDescription
module_namespacestringyesThe group to which Terraform module’s project belongs.
module_namestringyesThe module name.
module_systemstringyesThe name of the module system or provider.
module_versionstringyesSpecific module version to download.
Copy to clipboard
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:

Copy to clipboard
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

Copy to clipboard
GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/:module_version/file
AttributeTypeRequiredDescription
module_namespacestringyesThe group to which Terraform module’s project belongs.
module_namestringyesThe module name.
module_systemstringyesThe name of the module system or provider.
module_versionstringyesSpecific module version to download.
Copy to clipboard
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:

Copy to clipboard
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

Copy to clipboard
GET /projects/:id/packages/terraform/modules/:module_name/:module_system/:module_version
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project.
module_namestringyesThe module name.
module_systemstringyesThe name of the module system or provider.
module_versionstringnoSpecific module version to download. If omitted, the latest version is downloaded.
Copy to clipboard
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:

Copy to clipboard
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

Copy to clipboard
PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file
AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the project.
module-namestringyesThe module name.
module-systemstringyesThe name of the module system or provider.
module-versionstringyesSpecific module version to upload.
Copy to clipboard
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:

HeaderValue
PRIVATE-TOKENA personal access token with api scope.
DEPLOY-TOKENA deploy token with write_package_registry scope.
JOB-TOKENA job token.

Example response:

Copy to clipboard
{
  "message": "201 Created"
}