Publish private modules to the HCP Terraform private registry

Hands-on: Try the Share Modules in the Private Module Registry tutorial.

In addition to adding modules from the Terraform Registry, you can publish private modules to an organization's HCP Terraform private registry. The registry handles downloads and controls access with HCP Terraform API tokens, so consumers do not need access to the module's source repository, even when running Terraform from the command line.

The private registry uses your configured Version Control System (VCS) integrations and defers to your VCS provider for most management tasks. For example, your VCS provider handles new version releases. The only manual tasks are adding a new module and deleting module versions.

Permissions

Private modules are only available to members of the organization where you add them. In Terraform Enterprise, they are also available to organizations that you configure to share modules with that organization.

Members of the owners team and teams with Manage Private Registry permissions can publish and delete modules from the private registry.

Preparing a Module Repository

After you configure at least one connection to a VCS provider, you can publish a new module by specifying a properly formatted VCS repository (details below). The registry automatically detects the rest of the information it needs, including the module's name and its available versions.

A module repository must meet all of the following requirements before you can add it to the registry:

• Location and permissions: The repository must be in one of your configured VCS providers, and HCP Terraform's VCS user account must have admin access to the repository. The registry needs admin access to create the webhooks to import new module versions. GitLab repositories must be in the main organization or group, and not in any subgroups.

• 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 <PROVIDER> segment must be all lowercase. 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.

Publishing a New Module

You can publish modules through the UI as shown below or with the Registry Modules API. The API also supports publishing modules without a VCS repo as the source, which is not possible in the UI.

To publish a new module:

1. Click Registry. The Registry page appears.

2. Click Publish and select Module.

   The Add Module page appears with a list of available repositories.

3. Select the repository containing the module you want to publish.

   You can search the list by typing part or all of a repository name into the filter field. Remember that VCS providers use <NAMESPACE>/<REPO NAME> strings to locate repositories. The namespace is an organization name for most providers, but Bitbucket Data Center, not Bitbucket Cloud, uses project keys, like INFRA.

4. When prompted, choose either the Tag or Branch module publishing type.

5. (Optional) If this module is a no-code ready module, select the Add Module to no-code provision allowlist checkbox.

6. Click Publish module.

   HCP Terraform displays a loading page while it imports the module versions and then takes you to the new module's details page. On the details page, you can view available versions, read documentation, and copy a usage example.

Tag-based publishing considerations

When using the Tag module publishing type, the registry uses x.y.z formatted release tags to identify module versions. Your repository must contain at least one release tag for you to publish a module. Release tag names must be a semantic version, which you can optionally prefix with a v. For example, v1.0.4 and 0.9.2. The registry ignores tags that do not match these formats.

Branch-based publishing considerations

When using the Branch module publishing type, you must provide the name of an existing branch in your VCS repository and give the module a Module version. Your VCS repository does not need to contain a matching tag or release.

You can only enable testing on modules published using branch-based publishing. Refer to the test-integrated modules documentation for more information.

Releasing New Versions of a Module

The process to release a new module version differs between the tag-based and branch-based publishing workflows.

Tag-Based Publishing Workflow

To release a new version of a module in the tag-based publishing workflow, push a new release tag to its VCS repository. The registry automatically imports the new version.

Refer to Preparing a Module Repository for details about release tag requirements.

Branch-Based Publishing Workflow

To release a new version of a module using the branch-based publishing workflow, navigate to the module overview screen, then click the Publish New Version button. Select the commit SHA that the new version will point to, and assign a new module version. You cannot re-use an existing module version.

Update Publish Settings

After publishing your module, you can change between tag-based and branch-based publishing. To update your module's publish settings, navigate to the the module overview page, click the Manage Module for Organization dropdown, and then click Publish Settings.

• To change from tag-based to branch-based publishing, you must configure a Module branch and create a new module version, as HCP Terraform will not automatically create one.

• To change from branch-based publishing to tag-based publishing, you must create at least one tag in your VCS repository.

Deleting Versions and Modules

You can delete individual versions of a module or the entire module. If deleting a module version would leave a module with no versions, HCP Terraform removes the entire module. To delete a module or version:

1. Navigate to the module's details page.

2. If you want to delete a single version, use the Versions menu to select it.

3. Click Delete module.

4. Select an action from the menu:

   • Delete only this module version: Deletes only the version of the module you were viewing when you clicked Delete module.
   • Delete all versions for this provider for this module: Deletes the entire module for a single provider. This action is important if you have modules with the same name but with 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.
   • Delete all providers and versions for this module: Deletes all modules with this name, even if they are from different providers. For example, this action deletes both terraform-aws-appserver and terraform-azure-appserver.

5. Type the module name and click Delete.

Restoring a Deleted Module or Version

Deletion is permanent, but there are ways to restore deleted modules and module versions.

• To restore a deleted module, re-add it as a new module.
• To restore a deleted version, either delete the corresponding tag from your VCS and push a new tag with the same name, or delete the entire module from the registry and re-add it.

Sharing Modules Across Organizations

HCP Terraform does not typically allow one organization's workspaces to use private modules from a different organization. This restriction is because HCP Terraform gives Terraform temporary credentials to access modules that are only valid for that workspace's organization. Although it is possible to mix modules from multiple organizations when you run Terraform on the command line, we strongly recommend against it.

Instead, you can share modules across organizations by sharing the underlying VCS repository. Grant each organization access to the module's repository, and then add the module to each organization's registry. When you push tags to publish new module versions, both organizations update accordingly.

Terraform Enterprise administrators can configure module sharing to allow organizations to use private modules from other organizations.

Generating Module Tests (Beta)

You can generate and run generated tests for your module with the terraform test command.

Before you can generate tests for a module, it must have at least one version published. Tests can only be generated once per module and are intended to be reviewed by the module's authors before being checked into version control and maintained with the rest of the module's content. If the module's configuration files exceed 128KB in total size, HCP Terraform will not be able to generate tests for that module.

You must have permission to manage registry modules and permission to manage module test generation to generate tests.