» Publishing Modules to the Terraform Enterprise Private Module Registry

Terraform Enterprise (TFE)'s private module registry lets you publish Terraform modules to be consumed by users across your organization. It works much like the public Terraform Registry, except that it uses your configured VCS integrations instead of requiring public GitHub repositories.

Only members of the "owners" team can publish new modules. Once a module is published, the ability to release new versions is managed by your VCS provider.

» Workflow Summary

The private module registry is designed to be be as automatic as possible, so it defers to your VCS provider for most management tasks. The only manual tasks are adding a new module and deleting versions.

After configuring at least one connection to a VCS provider, you can publish a new module by telling TFE which repository it lives in. The registry uses the name of the repo to determine the module's name and provider, and uses the repo's tags to identify the available versions. It also uses the README and configurations in the repo to format documentation for each version.

To release a new version of an existing module, push a new tag to its repo. The registry updates automatically.

Consumers of a module don't need access to its source repository, even when running Terraform from the command line; the registry handles downloads, and uses TFE's API tokens to control access.

» Preparing a Module Repository

Since the registry relies on VCS repositories for most of its data, you must ensure your module repositories are in a format it can understand. A module repository must meet all of the following requirements before you can add it to the registry:

  • Available in a connected VCS provider. The repository must be in one of your configured VCS providers, and TFE's VCS user account must have admin access to the repository. (Since the registry uses webhooks to import new module versions, it needs admin access to create those webhooks.)

  • Named terraform-<PROVIDER>-<NAME>. Module repositories must use this three-part name format, where <NAME> reflects the type of infrastructure the module manages and <PROVIDER> is the main provider where it creates that infrastructure. The <NAME> segment can contain additional hyphens. Examples: terraform-google-vault or terraform-aws-ec2-instance.

  • Standard module structure. The module must adhere to the standard module structure. This allows the registry to inspect your module and generate documentation, track resource usage, and more.

  • x.y.z tags for releases. The registry uses tags to identify module versions. Release tag names must be a semantic version, which can optionally be prefixed with a v. For example, v1.0.4 and 0.9.2. To publish a module initially, at least one release tag must be present. Tags that don't look like version numbers are ignored.

» Publishing a New Module

To publish a module, navigate to the modules list with the "Modules" button and click the "+ Add Module" button in the upper right.

TFE screenshot: the "modules" button and the "+Add Module" button

This brings you to the "Add a New Module" page, which has a text field and at least one VCS provider button.

TFE screenshot: the "add a new module" page, with a repository name entered

If you have multiple VCS providers configured, use the buttons to select one. In the text field, enter the name of the repository for the module you're adding. Then click the "Publish Module" button.

TFE will display a loading page while it imports the module versions from version control, and will then take you to the new module's details page. On the details page you can view available versions, read documentation, and copy a usage example.

TFE screenshot: the module loading page

TFE screenshot: a module details page

» Releasing New Versions of a Module

To release a new version of a module, push a new version tag to its VCS repository. The registry will automatically import the new version.

Version tags must be a semantic version, which can optionally be prefixed with a v. For example, v1.0.4 and 0.9.2.

» Deleting Versions and Modules

Each module's details page includes a "Delete Module 🗑" button, which can delete individual versions of a module or entire modules.

To delete a module or version:

  1. Navigate to the module's details page.
  2. If you only want to delete a single version, use the "Versions" drop-down to select it.
  3. Click the "Delete Module 🗑" button.
  4. Select the desired action from the drop-down and confirm with the "Delete" button.
    • "Delete only this module version" affects the version of the module you were viewing when you clicked delete.
    • The other two options are only different if you have modules with the same name but different providers. (For example, if you have module repos named terraform-aws-appserver and terraform-azure-appserver, the registry treats them as alternate providers of the same appserver module.) If you use multi-provider modules like this, the "Delete all providers and versions for this module" option can delete multiple modules.

TFE screenshot: the deletion dialog