Get Your Code Out There: How to Publish to the Terraform Registry

Want to share your Terraform modules, providers, or functions with the world? This guide provides a clear, step-by-step approach to publishing on the Public Terraform Registry (registry.terraform.io) and making your work accessible to the Terraform community. Learn how to properly format and structure your repositories for a seamless publishing experience.

This guide covers publishing to the Terraform Registry:

• Modules
• Providers
• Functions

Important Note: The Public Terraform Registry exclusively supports public repositories hosted on GitHub.com. Other platforms, such as GitLab and Bitbucket, are not supported.

See It in Action: Real-World Examples

Before diving in, let's look at a practical example:

• GitHub Source: tfstack/terraform-aws-s3-static-website
• Published Module: Terraform Registry Module: tfstack/s3-static-website/aws

This showcases a real repository and its corresponding module on the public Terraform Registry. Check out the pre-configured GitHub Actions workflow for automated release tagging and a hands-free publishing process!

Step 1: Laying the Groundwork - Prerequisites

Before you start publishing, ensure you have the following:

• GitHub Account: A valid account on GitHub.com.
• Public Repository: The code you want to share must be in a public GitHub repository.
• Specific Naming Conventions: Adhere to these naming rules:
  • Modules: terraform-<PROVIDER>-<NAME> (e.g., terraform-aws-vpc)
  • Providers: terraform-provider-<NAME> (e.g., terraform-provider-example)
  • Functions: terraform-function-<NAME>
• Release Tag: At least one semantic version tag (e.g., v1.0.0).
• Required Files:
  • LICENSE
  • README.md
  • Source code (main.tf, provider.go, or function files)
  • versions.tf (for modules)
  • Optional: examples/ folder

Step 2: Set the Stage- Preparing Your GitHub Repository

Correct preparation is key for easy publishing of Terraform Registry modules. Here's what you need to do:

• Make it Public: Ensure your repository is set to public visibility.
• Follow the Naming Rules: Abide the specific naming convention for your content type (module, provider, or function).
• Include Essential Files: Make sure the required files are present in your repository.
• Create a Release Tag: Tagging identifies specific versions of your module, use the following commands:

git tag v1.0.0
git push origin v1.0.0

Step 3: Giving Access - Granting Terraform Registry Access to GitHub

The Terraform Registry needs permission to access your GitHub repository.

For Personal Repositories:

• If you've already authorized the Terraform Registry GitHub App, you're all set!

For Organization Repositories:

1. Go to GitHub Applications Connections.
2. Locate "Terraform Registry".
3. Under "Organization access," click "Grant" for your organization (e.g., "tfstack").
4. Optionally, configure access for specific repositories only.

Step 4: Go Live - Publishing to the Terraform Registry

Here's how to get your code on the Terraform Registry:

1. Go to the Terraform Registry Publish Page.
2. Sign in with your GitHub account.
3. Choose whether you are publishing a module or provider and select the repository you created.
4. Follow the prompts to complete the publishing process.

The Terraform Registry automatically validates your repository structure and release tags to prevent potential issues.

Step 5: Check and Stay Fresh - Verify and Update

After publishing your content on the Terraform Registry:

• Modules: https://registry.terraform.io/modules/<NAMESPACE>/<NAME>/<PROVIDER>
• Providers: https://registry.terraform.io/providers/<NAMESPACE>/<NAME>
• Functions: Coming Soon!

Important Points:

• The Terraform Registry automatically detects new tags (e.g., v1.0.1) within minutes of them being pushed.
• After the initial setup, no manual publishing is needed – it syncs automatically.
• Consider setting up a GitHub Actions workflow to automatically create release tags when you push to your main branch.
• Simply commit, push, and your new version will appear on the Terraform Registry.

Step 6: Addressing Issues - Troubleshooting

Encountering issues? Here’s a quick guide for common problems and their solutions when publishing to the terraform registry:

Additional Resources

• Terraform Registry: Publishing Modules
• Terraform Registry: Publishing Providers
• GitHub App Access Settings

Congratulations! Your Terraform module or provider is now live on the public Terraform Registry, ready to be used and shared with the community.