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

Want to share your Terraform modules, providers, or functions with the world? Publishing to the Terraform Registry is the way to go! This guide provides a step-by-step instruction on how to get your code onto the Public Terraform Registry (registry.terraform.io) and the requirements you need before publishing.

Important Note: The Terraform Registry exclusively supports public repositories hosted on GitHub.com at this time.

Visualize Success: A Real-World Example

See how it's done! Check out this live example to understand the process:

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

This demonstrates a repository and its corresponding module on the public Terraform Registry. It also showcases the proper folder structure, naming conventions, and more.

Pre-Flight Checklist: Prerequisites for Publishing

Before you begin, ensure you have the following:

• GitHub Account: A GitHub.com account is essential.

• Public Repository: Your code must reside in a public GitHub repository.

• Naming Conventions: Strict rules apply!

  • Modules: terraform-<PROVIDER>-<NAME> (e.g., terraform-aws-vpc)
  • Providers: terraform-provider-<NAME> (e.g., terraform-provider-example)
  • Functions: terraform-function-<NAME> (future support)

• Release Tag: At least one Semantic Version tag (e.g., v1.0.0) is required.

• Essential Files: Your repository must include:

  • LICENSE
  • README.md
  • Source code (main.tf for modules, provider.go for providers, function files for functions)
  • versions.tf (specifically for modules)
  • An examples/ folder is highly recommended.

Preparing Ground: Setting Up Your GitHub Repository

Get your GitHub repository ready for publishing:

1. Make it Public: Ensure the repository is set to "Public."

2. Adhere to Naming Conventions: Use the correct naming format as outlined above (module, provider, or function).

3. Include Required Files: Double-check that all necessary files (LICENSE, README.md, source code, versions.tf) exist.

4. Create a Release Tag: Tag your release using Semantic Versioning:

   git tag v1.0.0
   git push origin v1.0.0
   

   Copy

Opening the Gates: Granting Access to the Terraform Registry

The Terraform Registry needs permission to access your GitHub repository:

For Personal Repositories: No additional steps are necessary if you've previously authorized the Terraform Registry GitHub App.

For Organization Repositories:

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

The Moment of Truth: Publishing to the Terraform Registry

Time to publish your module, provider, or function. Steps:

1. Go to the Terraform Registry Publish Page.
2. Sign in with your GitHub account.
3. Choose the type of resource you're publishing (Module, Provider, or Function).
4. Select your repository.
5. Follow the instructions to complete the publishing process.

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

Checking the Lights: Verification and Updates

Verify your published resource:

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

Key Considerations:

• Automatic Updates: The Terraform Registry automatically detects new tags within minutes of pushing.
• Seamless Workflow: No manual publishing is needed after the initial setup—everything syncs automatically.
• Automation: Automate release tag creation with GitHub Actions for a completely hands-free publishing experience.

Commit, Push, and you're done! Your new version will appear live on the Terraform Registry.

Overcome Obstacles: Troubleshooting Common Issues

Problem	Solution
Repo not visible	Ensure the repository is public, named correctly, and has at least one Semantic Version release tag.
Authorization errors	Grant the Terraform Registry GitHub App access to your organization.
Validation errors	Verify that all required files (LICENSE, README.md, etc.) are present in the repository.
Naming errors	Adhere strictly to required naming conventions for modules, providers, or functions.
Tag format issues	Terraform Registry requires tags to follow full Semantic Versioning, such as v1.0.0. Tags like v1 or any non-standard formats will be rejected.

Taking Off: Additional Terraform Registry Resources

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

Congratulations! Your Terraform module, provider, or function is now live on the Terraform Registry for the world to use.