Terraform Registry publishing FAQ

Below you'll find answers to some of the most common questions that arise when publishing a Terraform provider, module, or Sentinel policy library into the Registry.

How do I fix provider documentation issues?

If you have issues formatting documentation, use the documentation preview tool to view how the Terraform Registry will format your documentation before you commit to a new provider release. Learn more about creating provider documentation.

If you have already released a version of your provider and are unhappy with its documentation, fix the documentation issue in your repository and include it in a new release.

Why is my documentation not rendered like it is in Github?

We make every effort to support GitHub Markdown syntax in the registry documentation, but occasionally compatibility limitations arise. To ensure consistent rendering in the public registry, we recommend using syntax widely supported across various Markdown flavors. Use the documentation preview tool to view how the Terraform Registry will format your documentation.

How do I remove a published version?

If you remove a version of a provider, module, or policy library from the Terraform Registry, you will break the configuration of any individuals using that version. For this reason, we never recommend removing previously published versions of providers, modules, or policy libraries.

There are a few situations where you may need to remove a version from the Terraform Registry. For example, if a version has a critical security vulnerability.

In these situations, your options for removing previously published versions vary on the type of Terraform Registry artifact:

• Modules: The module owner can use the Terraform Registry to remove a specific version, all versions of a specific module provider, or the module entirely.
• Providers: There is no manual process for removing a version of a provider. Reach out to us via email if it is critical that a version be deleted.
• Policy Libraries: The owner of a policy library can completely remove it from the Registry through the website.

How do I correct bugs in published versions?

If there is a problem with a specific version, publish a new release with the issue fixed. Increment the patch version according to standard Semantic Versioning practices (e.g., from 1.2.0 to 1.2.1).

Can I delete a GitHub tag or release for a published version?

We do not recommend removing content from a GitHub repository you previously published to the Terraform Registry.

The Terraform Registry effectively acts as an index for Terraform-related content hosted on GitHub. When you make a new tag or release in the GitHub repository that holds your Terraform Registry artifact, the Registry automatically creates an index record for that content. Think of an index record as a pointer to those files in your GitHub repository.

The Terraform Registry is unaware if you remove a file, a tag, a release, or other content from GitHub. The Registry could still host index records pointing to now-removed content. As a result, someone using your provider or module may have their Terraform configuration break because the Registry is referencing GitHub files that are no longer available.

If you find a typo, bug, or other issues with a published version of your provider, module, or policy library, we recommend fixing the problem and publishing a new release.

How do I change the image associated with my artifacts?

The image is associated with the GitHub user or organization profile. Customize the user profile or organization profile to update the image.

Can I change the name of my artifact?

Once consumers start using your provider, module, or policy library, the name of the artifact must remain constant. Otherwise, you could break your consumer's Terraform configuration.

For this reason, we strongly recommend against moving or renaming an existing artifact. Instead, it's often a better choice to create a new repository, representing the new name of your artifact while leaving the old content in place.

For further help, reach out to us via email.

Can I rename the GitHub user or organization that owns my artifact's repository?

When you change the name of a GitHub user or organization, GitHub automatically redirects requests for the old user or organization to the new one. This means there is no interruption for your artifact's consumers, who can continue using the old name. If you need to change the name of your artifact, see the above answer.

If you have changed your publishing Github user or organization name, we recommend reclaiming any names you previously published from. If someone else claims your old user or organization name, they could build repositories that "capture" any redirected requests from the Registry. At that point, your consumers would be unable to download your artifact.

What does resyncing an artifact do?

Owners of Terraform Registry artifacts have access to a Resync button on their providers, modules, and policy libraries. Clicking Resync instructs the Terraform Registry to check an artifact's source repository on GitHub, so the Registry:

• Ensures the repository has a webhook to publish new versions automatically.
• Checks for discrepancies between the versions on GitHub and the versions within the Registry.

The Terraform Registry will publish any versions in Github that the Registry hasn't published yet.

If a version you previously published to the Registry no longer exists in GitHub, the Registry responds differently depending on the type of artifact:

• Modules: if a version is available in the Registry but not in GitHub, the Registry removes that version. This might confuse your consumers that rely on specific module versions.

• Providers and Policy Libraries: if a version is available in the Registry but not in GitHub, the Registry keeps that published version. This state can cause certain versions of the artifact to be unusable. We never recommend deleting files, tags, or releases from GitHub once you have published to the Registry.

What can I do if new versions are not displaying in the Registry?

If a new version you've published to GitHub is not showing up in the Terraform Registry, try resyncing your artifact with Github.

If resyncing does not work or publishing problems occur after resyncing, investigate your GitHub repository's webhooks. You can locate these webhooks in your repository's settings page by navigating to:

https://github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPO_NAME>/settings/hooks

If multiple webhooks point to the Registry's URL (https://registry.terraform.io), remove them, then attempt to resync your artifact again.

If you are still running into trouble, please reach out to us via email for support. If you are a customer of HashiCorp, work with your enterprise support contact to escalate the issue.

How is the latest version of an artifact selected?

Each version of an artifact published in the Terraform Registry has a string version identifier (e.g., 1.2.3). You create the version identifier when you create a tag (for modules and policy libraries) or a release (for providers) in the GitHub repository where the artifact's code lives.

The Terraform Registry requires that these version identifiers are SemVer compliant. The Registry sorts versions using these identifiers, following standard SemVer precedence rules. The Registry lists the version identifier with the greatest precedence as the latest.

Can I prevent prereleases from being the latest version?

No. The Terraform Registry's version sorting is strictly SemVer compliant (see above). This means that "latest" in the Registry can be a prerelease version, if the prerelease's version identifier has the greatest precedence.

For example, if your provider has a published version (i.e., 1.0.0), and you create a new release for a version 2 prerelease (e.g., 2.0.0-preview). The Registry lists the version 2 prerelease as the latest version in the Terraform Registry.

Note that Terraform never selects a prerelease version during a plan or apply unless the configuration files explicitly request one using an exact version constraint.

Can I change the GPG key I use to sign a provider?

The public GPG keys that you upload to the Terraform Registry serve two purposes:

1. When you publish a new provider version, the Registry uses the GPG key to verify the signature file you created. This lets the Registry confirm that you compiled the binary files.
2. When someone downloads a version of your provider from the Registry, they can verify that the downloaded binary files have not been tampered with since you built them and generated the signature file.

If you want to change to a new GPG key to sign and publish providers, you can upload a new one and use its private key to sign future provider releases. You do not need to remove any old GPG keys. Leaving the old key in place allows consumers of old versions of your provider to continue using those versions.

Can I remove public GPG keys that I previously published with?

You should never remove a public GPG key from the Registry, so we do not provide a way for you to do so.

If you removed a public GPG key that you used to sign previous versions of a provider, consumers would be unable to use those versions because they could not verify the authenticity of the binary file they downloaded.

What can I do if my GPG Keys or GitHub account was compromised?

If your GPG key or Github account has been compromised, please reach out to us via email. If you are a customer of HashiCorp, work with your enterprise support contact to escalate the issue.

Can I regain ownership of my artifact after losing access to my GitHub account?

Artifacts in the Public Registry that were originally published by a GitHub user that no longer exists are routinely detected and marked with a disclaimer.

The GitHub user that published this artifact no longer exists. See the FAQ for more information.

If you are the owner of such an artifact, or for other artifact ownership issues, please reach out to us.