• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Terraform Home

Registry Publishing

Skip to main content
  • Registry Publishing
    • Overview
    • Publishing Providers
    • Documenting Providers
    • Recommended OS and Architecture
    • Terraform Integration Program
  • Run Tasks
  • Private Registries
  • Registry API

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Registry Publishing
  4. Providers
  5. Publishing Providers

»Publishing Providers

Anyone can publish and share a provider by signing into the Registry using their GitHub account and following a few additional steps.

This page describes how to prepare a Terraform provider for publishing, and how to publish a prepared provider using the Registry's interface.

Hands-on: Try the Release and Publish a Provider to the Terraform Registry tutorial. In this tutorial, you create a release for your custom Terraform provider and prepare your provider to publish to the Terraform Registry.

Preparing your Provider

Writing a Provider

Providers published to the Terraform Registry are written and built in the same way as other Terraform providers. A variety of resources are available to help our contributors build a quality integration:

Hands-on: Try the Call APIs with Terraform Providers tutorials to create a custom Terraform provider, complete with authentication and create/read/update/delete/import functionality.

  • How to build a provider – Video
  • Sample provider developed by a HashiCorp partner
  • Example providers for reference:
    • AWS
    • AzureRM
  • Contributing to Terraform

Important: In order to be detected by the Terraform Registry, all provider repositories on GitHub must match the pattern terraform-provider-{NAME}, and the repository must be public. Only lowercase repository names are supported.

Documenting your Provider

Your provider should contain an overview document (index.md), as well as a doc for each resource and data-source. See Documenting Providers for details about generating documentation and how to ensure your provider documentation renders properly on the Terraform Registry.

Note: In order to test how documents will render in the Terraform Registry, you can use the Terraform Registry Doc Preview Tool.

Terraform Registry Manifest File

The Terraform Registry supports a JSON configuration file in each release that provides additional data about the provider being published. For example:

{
  "version": 1,
  "metadata": {
    "protocol_versions": ["5.0"]
  }
}

This file is conventionally named terraform-registry-manifest.json at the root of the provider repository and will be renamed in the release assets. The file must contain valid JSON syntax, such as no trailing commas in lists or objects.

It supports the following fields:

FieldPurpose
metadataObject containing additional data to be associated with a release.
metadata.protocol_versionsList of strings with supported Terraform protocol versions of the provider. Providers developed using Terraform Plugin SDK version 2 should set this field to ["5.0"]. Providers developed using Terraform Plugin Framework should set this field to ["6.0"] unless the Framework is explicitly configured for protocol version 5. Defaults to ["5.0"].
versionNumeric version of the manifest format, not the version of your provider. Set this to 1.

Important: If developing a provider using Terraform Plugin Framework, ensure the protocol versions are set to ["6.0"] or practitioners will receive errors when attempting to use the provider.

Creating a GitHub Release

Publishing a provider requires at least one version be available on GitHub Releases. The tag must be a valid Semantic Version preceded with a v (for example, v1.2.3). There must not be a branch name with the same name as the tag.

Terraform CLI and the Terraform Registry follow the Semantic Versioning specification when detecting a valid version, sorting versions, solving version constraints, and choosing the latest version. Prerelease versions are supported (available if explicitly defined but not chosen automatically) with a hyphen (-) delimiter, such as v1.2.3-pre.

We have a list of recommend OS / architecture combinations for which we suggest most providers create binaries.

Important: Avoid modifying or replacing an already-released version of a provider, as this will cause checksum errors for users when attempting to download the plugin. Instead, if changes are necessary, please release as a new version.

GitHub Actions (Preferred)

GitHub Actions allow you to execute workflows when events on your repository occur. You can use this to publish provider releases to the Terraform Registry whenever a new version tag is created on your repository.

To use GitHub Actions to publish new provider releases to the Terraform Registry:

  1. Ensure the GitHub Organization settings for GitHub Actions and GitHub Repository settings for GitHub Actions allows running workflows and allows the actions specified in the GitHub Actions workflow from the terraform-provider-scaffolding repository.
  2. Create and export a signing key that you plan on using to sign your provider releases. See Preparing and Adding a Signing Key for more information.
  3. Copy the GoReleaser configuration from the terraform-provider-scaffolding repository to the root of your repository.
  4. Copy the GitHub Actions workflow from the terraform-provider-scaffolding repository to .github/workflows/release.yml in your repository.
  5. Go to Settings > Secrets in your repository, and add the following secrets:
  • GPG_PRIVATE_KEY - Your ASCII-armored GPG private key. You can export this with gpg --armor --export-secret-keys [key ID or email].
  • PASSPHRASE - The passphrase for your GPG private key.
  1. Ensure there is not a branch name with the new valid version tag name (e.g. v1.2.3).
  2. Push a new valid version tag (e.g. v1.2.3) to test that the GitHub Actions releaser is working.

Once a release is created, you can move on to Publishing to the Registry.

Using GoReleaser locally

GoReleaser is a tool for building Go projects for multiple platforms, creating a checksums file, and signing the release. It can also upload your release to GitHub Releases.

  1. Install GoReleaser using the installation instructions.
  2. Copy the .goreleaser.yml file from the hashicorp/terraform-provider-scaffolding repository.
  3. Cache the password for your GPG private key with gpg --armor --detach-sign (see note below).
  4. Set your GITHUB_TOKEN to a Personal Access Token that has the public_repo scope.
  5. Ensure there is not a branch name with the expected version tag name (e.g. v1.2.3).
  6. Tag your version with git tag v1.2.3 and push your tags to GitHub.
  7. Build, sign, and upload your release with goreleaser release --rm-dist.

GoReleaser does not support signing binaries with a GPG key that requires a passphrase. Some systems may cache your GPG passphrase for a few minutes. If you are unable to cache the passphrase for GoReleaser, please use the manual release preparation process below, or remove the signature step from GoReleaser and sign it prior to moving the GitHub release from draft to published.

Manually Preparing a Release

You can manually create the required assets by following these requirements or encode them into a Makefile or shell script. The release must meet the following criteria:

  • There are 1 or more zip files containing the built provider binary for a single architecture.
    • The binary name is terraform-provider-{NAME}_v{VERSION}.
    • The archive name is terraform-provider-{NAME}_{VERSION}_{OS}_{ARCH}.zip.
  • There is a terraform-provider-{NAME}_{VERSION}_manifest.json file, which contains the Terraform Registry manifest file in the release.
  • There is a terraform-provider-{NAME}_{VERSION}_SHA256SUMS file, which contains a SHA-256 checksum for each zip file and the manifest file in the release.
    • shasum -a 256 *.zip > terraform-provider-{NAME}_{VERSION}_SHA256SUMS
  • There is a terraform-provider-{NAME}_{VERSION}_SHA256SUMS.sig file, which is a valid GPG binary (not ASCII armored) signature of the terraform-provider-{NAME}_{VERSION}_SHA256SUMS file using the keypair.
    • gpg --detach-sign terraform-provider-{NAME}_{VERSION}_SHA256SUMS
  • Release is finalized (not a private draft).

Publishing to the Registry

Signing in

Before publishing a provider, you must first sign in to the Terraform Registry with a GitHub account (see the "User Account" section of the overview page). The GitHub account used must have the following permission scopes on the provider repository you’d like to publish. Permissions can be verified by going to your GitHub Settings and selecting the Terraform Registry Application under Authorized OAuth Apps.

screenshot: terraform registry github oauth required permissions

Preparing and Adding a Signing Key

All provider releases are required to be signed, thus you must provide HashiCorp with the public key for the GPG keypair that you will be signing releases with. The Terraform Registry will validate that the release is signed with this key when publishing each version, and Terraform will verify this during terraform init.

To prepare and add a signing key:

  1. Generate a GPG key to be used when signing releases. Refer to GitHub's detailed instructions for this step, but you do not need to add the key to GitHub.

    Note: The Terraform Registry API accepts both RSA and DSA keys, but not the default ECC type.

  2. Use the following command to export your public key in ASCII-armor format. Substitute the GPG key ID created in the previous step.

    $ gpg --armor --export "{Key ID or email address}"
    
  3. In the Terraform Registry, click User Settings > Signing Keys to add the ASCII-armored public key. You can add keys for your personal namespace or any organization where you are an admin.

Publishing Your Provider

In the top-right navigation, select Publish > Provider to begin the publishing process. Follow the prompts to select the organization and repository you would like to publish.

Webhooks

Publishing a provider will create a webhook on the GitHub repository subscribed to release events. Future versions released will notify the Terraform Registry, which will then ingress that version.

If the webhook is missing or not functioning, you can use the Resync button on the provider settings page. First, remove any existing webhooks for registry.terraform.io. Then, click the Resync button on the Terraform Registry's provider settings page. A new webhook should be created.

Terms of Use

Anything published to the Terraform Registry is subject to our terms of use. A copy of the terms are available for viewing at https://registry.terraform.io/terms

Support

If you experience issues publishing your provider to the Terraform Registry, please contact us at terraform-registry@hashicorp.com.

Edit this page on GitHub

On this page

  1. Publishing Providers
  2. Preparing your Provider
  3. Publishing to the Registry
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)