Publish private modules to the private registry

This topic describes how to publish private modules to an organization's private registry. For instructions on adding modules from the public registry, refer to Add modules from the Terraform registry.

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

Introduction

When publishing modules to the private registry, the registry downloads the module source code. 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 version control system (VCS) integrations and delegates management tasks, such as handling new version releases, to your VCS provider. The only manual tasks are adding a new module and deleting module versions.

Access to private modules

Private modules are only available to members of the organization that owns the private registry. In Terraform Enterprise, they are also available to organizations that you configure to share modules with that organization.

Publishing worfklows

You can publish modules according to VCS tags or branches. Refer to Tag-based publishing considerations and Branch-based publishing considerations for more information.

Requirements

Verify that you have met the following requirements before completing these instructions.

Permissions

You must be a member of the owners team and teams with Manage private registry permissions enabled to publish and delete modules from the private registry.

VCS provider settings

• You must configure a VCS provider connection. Refer to Connect to VCS Providers for more information.
• The source directory settings in your VCS must specify the path to the module configuration files.

Repository configuration

The registry automatically detects module names and versions in the repository. Your module repository must meet all of the following requirements before adding it to the registry.

• The repository must be in one of your configured VCS providers.
• The HCP Terraform or Terraform Enterprise 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.
• Subfolders that contain module source code must adhere to the standard module structure so that the registry can inspect your module, generate documentation, and track resource usage.

Release tag prefixes

Specify a prefix to filter repository Git tags when using the tag-based publishing type in a repository that contains code for multiple modules. Without a prefix, HCP Terraform and Terraform Enterprise publish new versions for all modules with valid Git tags that use semantic versioning.

For example, specifying app as a tag prefix for the registry module instructs HCP Terraform to select only Git tags with the prefix app in them. As a result, HCP Terrraform selects the module tagged with appv1.0.0 and publishes v1.0.0 to the registry.

Refer to Enable publishing from a single repository

Module

By default, HCP Terraform and Terraform Enterprise require a separate repository for each module. As a result, each module must use the following three-part naming convention:

terraform-<PROVIDER>-<NAME>

The <NAME> segment reflects the type of infrastructure the module manages and <PROVIDER> is the main provider where it creates the infrastructure.

The <PROVIDER> segment must be all lowercase. The <NAME> segment can contain additional hyphens.

Examples:

• terraform-google-vault
• terraform-aws-ec2-instance

When the Publish modules to your private registry from a single repository option is enabled,you can store multiple modules in a single repository. As a result, modules do not need to follow the naming convention. Refer to the following topics for more information:

• Enable publishing from a single repository
• Multiple modules in a single repository

Enable publishing from a single repository

By default, HCP Terraform and Terraform Enterprise retrieve new versions of modules published to the private registry according to the repository release tag. As a result, you must store the code for each module in separate repositories. Otherwise, the registry retrieves and publishes new versions of all modules in a repository each time you create a new release tag.

If you want to use a single repository to store modules source code, you can enable the Publish modules to your private registry from a single repository option in your workspace's general settings. When this option is enabled, you can add a prefix to the version tag that the registry uses to select module sources to publish when new you create new release tags. Refer to Release tag prefixes for additional information.

After enabling this option, complete the instructions for publishing a new module.

Publish a new module

You can publish modules using either the UI or API. Refer to Publish a Private Module from a VCS for instructions on using API. Note that you can also call the API to publish modules without a VCS repository as the source, which is not possible in the UI.

The interface for publishing modules and the registry behavior depends on how the Publish modules to your private registry from a single repository option. Refer to Enable publishing from a single repository for more information about this setting.

One module per repository

The Publish modules to your private registry from a single repository option is disabled by default, which requires requires each module to be stored in its own repository. Complete the following steps when this option is disabled:

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to the organization where you want to publish a module.

2. Select Registry from the sidebar.

3. Choose Module from the Publish and drop-down menu. The Add Module page appears with a list of available repositories.

4. Click on a VCS connection. The screen advances to the Choose a repository step.

5. 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.

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

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

1. 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.

Multiple modules in a single repository

Complete the following steps when the Publish modules to your private registry from a single repository option is enabled:

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to the organization where you want to publish a module.

2. Select Registry from the sidebar.

3. Choose Module from the Publish and drop-down menu. The Add Module page appears with a list of available repositories.

4. Click on a VCS connection. The screen advances to the Configure VCS Settings step.

5. In the Select a VCS Repository field, choose the repository containing your modules' source code. You can search the list by typing part or all of a repository name into the filter field. 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, such as INFRA.

6. Enable either the Tag or Branch module publishing type. Refer to Tag-based publishing considerations and Branch-based publishing considerations for more information.

7. Complete the fields for your publishing type.

   When Tag is enabled:

   • In the Module Tag Prefix field, specify a Git tag prefix. The registry uses the prefix and a release version as a unique identifier when sourcing code for multiple modules in a single repository. Refer to Requirements for more information about setting up tags.
   • In the Source Directory field, specify the path to the module source code.

   When Branch is enabled:

   • In the Branch Name field, specify the name of the branch to scan for the module code.
   • In the Module Version field, specify the version of the module.
   • In the Source Directory field, specify the path to the module source code.

8. Click Next to advance to the Confirm selection screen.

9. In the Module Name field, specify a name for the module. This is the name that appears in the registry. HCP Terraform and Terraform Enterprise use the name in the module address.

10. In the Provider Name field, specify the name of the provider that integrates the module. HCP Terraform and Terraform Enterprise use the name in the module address.

11. It is optional, but if this module is a no-code ready module, enable the Add Module to no-code provision allowlist option to allow your organization members to provision resources defined by this module using the no-code workflow. Refer to Provision no-code infrastructure for more information.

1. Click Publish module.

HCP Terraform and Terraform Enterprise displays a loading page while it imports the module versions and then directs 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

To enable the Tag module publishing type, your registry must use the x.y.z format for 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.

To publish modules from a single repository, you should also include a tag prefix so that HCP Terraform can publish individual modules in the repository when you create new version tags. Refer to Release tag prefixes for more information.

Branch-based publishing considerations

To enable the Branch module publishing type, you must provide the name of an existing branch in your VCS repository and provide the module with 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.

Module testing is disabled when the Publish modules to your private registry from a single repository option is enabled in your workspace's general settings. Refer to Enable publishing from a single repository for more information.

Release new module versions

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.

Delete versions and modules

You can delete individual versions of a module or the entire module. Deleting a tag from your VCS repository does not automatically remove the version from the private registry. 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. Sign in to HCP Terraform or Terraform Enterprise and 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.

Restore 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.

Share 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.

Generate module tests

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.