DEV Community

John Ajera
John Ajera

Posted on

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

#terraform #public #registry #github

🚀 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:

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-<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).
  • 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
Enter fullscreen mode Exit fullscreen mode

🔑 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/<NAMESPACE>/<NAME>/<PROVIDER>
Enter fullscreen mode Exit fullscreen mode
  • Providers: 
  https://registry.terraform.io/providers/<NAMESPACE>/<NAME>
Enter fullscreen mode Exit fullscreen mode
  • 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

Problem Solution
Repo not visible Ensure repo is public, named correctly, and has a release tag
Authorization errors Grant the Terraform Registry GitHub App access to your org
Validation errors Ensure required files (LICENSE, README.md, etc.) are present
Naming errors Match required patterns exactly
Tag format issues Terraform Registry strictly requires tags to follow full Semantic Versioning, such as v1.0.0. Tags like v1 or any non-standard formats will cause the release to be rejected and show a warning in the Registry. Only full semantic version tags are allowed.
  • Providers have extra rules (Terraform SDK requirements).
  • Functions will have lightweight rules in the future.

📃 References

🎉 Congratulations!

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

Top comments (0)