How to Publish to the Terraform Registry (Modules, Providers, Functions)

🚀 How to Publish to the Terraform Registry (Modules, Providers, Functions)

This guide explains how to publish modules, providers, and functions to the Public Terraform Registry (registry.terraform.io) — covering everything you need to know.

Important: Only public GitHub.com repositories are supported for publishing to the Public Terraform Registry. Other platforms (GitLab, Bitbucket, manual uploads) are not supported.

📅 Real Example

To see a complete working example, check out this pair:

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

This shows a real repository and its resulting module on the public Terraform Registry.

Tip: The sample repository above is configured with an automated GitHub Actions workflow to handle release tagging, making the entire process hands-free after merging!

📋 1. Prerequisites

Before you can publish anything to the Registry, you need:

• GitHub Account: A GitHub.com account.
• Public Repository: The code must be stored in a public GitHub repository.
• Naming Convention:
  • Modules: terraform-- (e.g., terraform-aws-vpc)
  • Providers: terraform-provider- (e.g., terraform-provider-example)
  • Functions: terraform-function- (future support)
• 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

🛠️ 2. Prepare Your GitHub Repository

1. Make the repository public.
2. Use the correct naming convention for your type (module, provider, or function).
3. Include required files:
   • LICENSE
   • README.md
   • main.tf, provider.go, or function source
   • versions.tf for modules
   • examples/ folder (recommended)
4. Create a release tag:

git tag v1.0.0
   git push origin v1.0.0

🔑 3. Grant Terraform Registry Access to GitHub

For Personal Repositories

• If you've already authorized the Terraform Registry GitHub App, no extra steps are needed.

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 specific repositories.

🚀 4. Publish to the Terraform Registry

1. Go to the Terraform Registry Publish Page.
2. Sign in with GitHub.
3. Choose:
   • Module
   • Provider
   • (Future: Function)
4. Select your repository.
5. Follow the prompts to complete publishing.

Terraform Registry automatically validates your repository structure and release tags.

🔄 5. Verify and Update

After publishing:

• Modules:

https://registry.terraform.io/modules///

• Providers:

https://registry.terraform.io/providers//

• Functions: (coming soon)

Good to know:

• ✅ As soon as you push a new tag (e.g., v1.0.1), the Terraform Registry automatically detects it within minutes.
• ✅ No manual publishing needed after the initial setup — it syncs automatically.
• ✅ You can set up a GitHub Actions workflow to auto-create release tags when you push to main, making the entire flow seamless.

Simply commit → push → and your new version appears live on the Terraform Registry!
(Tip: the sample repository *tfstack/terraform-aws-s3-static-website** is configured with an automated GitHub Actions workflow to handle release tagging, making the entire process hands-free after merging!)*

🛠️ 6. Troubleshooting

• Providers have extra rules (Terraform SDK requirements).
• Functions will have lightweight rules in the future.

📃 References

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

🎉 Congratulations!

Your Terraform module, provider, or function is now live on the public Terraform Registry!