Get Your Code Out There: A Practical Guide to Publishing on the Terraform Registry

Want to share your awesome Terraform modules and providers with the world? Publishing to the Terraform Registry is the perfect way to do it! This guide breaks down the process into simple, actionable steps, making it easy for anyone to contribute to the Terraform ecosystem. Learn how to publish Terraform Registry modules and providers today.

Why Use the Terraform Registry?

The Terraform Registry is a central hub for discovering and sharing Terraform code. Publishing your work offers several key advantages:

• Increased Visibility: Makes your modules and providers easily accessible to a wide audience.
• Community Contribution: Helps others benefit from your expertise and accelerates infrastructure automation.
• Version Control: Simplifies managing and distributing updates to your code using semantic versioning.
• Collaboration: Encourages collaboration and feedback from the Terraform community.

Real-World Example: See It in Action

Check out this working example to see how it's all done:

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

Notice how the GitHub repository mirrors the structure and naming conventions required for publishing to the Terraform Registry.

Prep Work: Meeting the Terraform Registry Requirements

Before you dive in, ensure you have these prerequisites covered:

• GitHub Account: You'll need a GitHub.com account.
• Public Repository: Your code must reside in a public GitHub repository.
• Proper Naming: Follow the naming conventions to publish Terraform Registry modules (terraform-<PROVIDER>-<NAME>) and providers (terraform-provider-<NAME>).
• Semantic Versioning: Use semantic version tags (e.g., v1.0.0) to track releases of your code.
• Essential Files: Include LICENSE, README.md, and source code (main.tf, provider.go, or function files). For modules, a versions.tf file is also required.

Step-by-Step Guide: Preparing Your GitHub Repository

1. Make it Public: Ensure your repository is publicly accessible on GitHub.

2. Name It Right: Adhere to the naming conventions for modules, providers, or functions.

3. Include Necessary Files:

   • LICENSE
   • README.md
   • main.tf, provider.go, or function source code
   • versions.tf (for modules)
   • examples/ folder (recommended)

4. Create a Release Tag:

   git tag v1.0.0
   git push origin v1.0.0
   

   Copy

Granting Access: Letting the Terraform Registry In

Personal Repositories

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

Organization Repositories

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

Publishing Time: Putting Your Code on the Terraform Registry

1. Go to the Terraform Registry "Publish" Page.
2. Sign in with your GitHub account.
3. Select the type of resource you’re publishing, whether module, provider, or function.
4. Choose your repository from the list.
5. Follow the prompts to complete the publishing process.

The Terraform Registry will automatically validate your repository structure and release tags.

Verification and Updates: Keeping Your Code Fresh

After publishing, verify your module or provider is accessible through the following URLs:

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

Any time you push a new tag the Terraform Registry automatically detects it within minutes. This makes updates seamless, just commit and push, and your new version appears live!

Troubleshooting: Common Issues and Solutions

Problem	Solution
Repo not visible	Ensure the repository is public, named correctly, and has at least one release tag.
Authorization errors	Grant the Terraform Registry GitHub App access to your organization.
Validation errors	Ensure all required files (LICENSE, README.md, etc.) are present.
Naming errors	Match the required naming patterns exactly.
Tag format issues	Terraform Registry strictly requires tags to follow full Semantic Versioning, such as v1.0.0. Non-standard formats will cause rejection.

References: Deep Dive Resources

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

You're now equipped to confidently publish your Terraform modules and providers, helping others build amazing infrastructure!