Manage namespace artifacts

Namespaces let you connect a GitHub account to an HCP Terraform organization, letting organization members collectively manage that GitHub account’s existing and future public registry artifacts.

Requirements

The following permissions are necessary to manage a namespace's artifacts:

• Organization owners or members with Manage public modules permissions can manage modules in the public registry
• Organization owners or members with Manage public providers permissions can manage providers in the public registry

Publish artifacts

You can publish new modules and providers to the public registry under your organization’s claimed namespace. The following workflow should be familiar to existing public registry users:

1. Set up a GitHub repository following the conventions and instructions outlined for the type of artifact you want to publish.
   • For modules, ensure your repository meets the requirements.
   • For providers, follow all of the steps up to the Publishing to the Registry section.
   • If you have not installed the Terraform Cloud GitHub App globally in your GitHub account, install the app in the repository you want to publish.
2. Sign in to HCP Terraform and navigate to your organization, then select Registry in the sidebar, then Public namespaces and select the namespace you want to publish from.
3. Click Publish and select the type of artifact, provider or module, you want to publish.
4. Select the repository you want to publish.
5. If you are publishing a provider, choose a Category.
6. Check the box to agree to the terms of service.
7. Click Publish provider or Publish module.

HCP Terraform then displays a list of all the versions of your provider or module currently in your repository, and the status of each version that the public registry creates. If you navigate away from this page before processing is complete, it continues in the background.

Publish new artifact versions

You can create new versions of public registry artifacts using the same workflow as individual GitHub accounts. Add a properly formatted tag for modules, or release for providers, to your artifact's GitHub repository. GitHub notifies HCP Terraform that a new version or release is available and instructs the public registry to create a new version.

Once the public registry creates the new version it appears in your namespace in HCP Terraform. You can view artifact versions by clicking the ellipsis … next to an artifact and selecting View version history. New versions are also visible on your artifact's page in the public registry.

If the new version creates errors, a notification appears on your organization's Public namespaces page. The notification includes an error, and after you fix the problem we recommend creating a new tag or release.

View artifacts

On the Public namespaces page, you can click the ellipsis … next to an artifact to list the available actions you can take on that artifact:

• View in public registry links to the artifact’s page on https://registry.terraform.io.
• View downloads has the download metrics for the selected artifact.
  • View the number of times users have downloaded multiple versions, or select a single version to view the number of times users have downloaded it.
  • You can also download a CSV file that summarizes the monthly downloads of each artifact version.
• View version history lists the artifact's published versions.
• Add to private library adds the artifact to your organization’s private registry.

Delete artifacts or artifact versions

On the Public namespaces page, you can delete modules, providers, and module and provider versions if you have the correct permissions and an artifact meets specific deletion requirements.

Deletion requirements

To delete a provider, module, or a provider or module version, one of the following must be true:

• Someone published the artifact less than 48 hours ago.
• No version of the artifact was downloaded by users more than 100 times.

Delete a module or provider

If your provider or module meets the deletion requirements, you delete it by doing the following:

• Clicking on the ellipsis … next to the artifact and choosing Delete.
• Confirm by entering delete and click Delete.

Delete a module or provider version

If your provider or module meets the deletion requirements, you delete a version by doing the following:

• Clicking on the ellipsis … next to the artifact and choosing to Delete version.
• Entering the exact version of the provider or module to delete.
• Confirm by entering delete and click Delete version.

Resync artifacts

Resyncing an artifact checks for discrepancies between the versions of an artifact on GitHub and the versions available within the public registry. Resyncing attempts to reconcile any differences by changing versions available in the public registry to match GitHub.

If an artifact version exists in GitHub but not in the registry, HCP Terraform attempts to create new versions in the registry. If an artifact version exists in the registry but not in GitHub, HCP Terraform deletes the registry versions that meet the deletion requirements.

To resync an artifact:

1. Click the ellipsis … next to the artifact you want to resync.
2. Select Resync.
3. HCP Terraform lists the versions it intends to create or delete, click Resync to confirm.

You can then see the public registry's progress as it performs each operation. If you navigate away from this page before processing is complete it continues in the background