Publishing Lab

8 minute read

Lab Overview

In this lab, you’ll walk through the complete process of preparing, releasing, and publishing a Terraform provider to the registry.

Prerequisites

  • Terraform provider repository
  • GitHub account
  • GPG key pair
  • Complete documentation
  • Passing tests

Lab Setup

Verify Repository

cd terraform-provider-cachecloud

# Check repository structure
tree -L 2 -I 'vendor|.git'

Expected structure:

.
├── .github/
│   └── workflows/
├── .goreleaser.yml
├── CHANGELOG.md
├── LICENSE
├── README.md
├── docs/
│   ├── data-sources/
│   ├── guides/
│   ├── index.md
│   └── resources/
├── examples/
│   ├── data-sources/
│   ├── provider/
│   └── resources/
├── go.mod
├── go.sum
├── internal/
│   └── provider/
└── main.go

Part 1: Pre-Release Preparation

Step 1: Update Documentation

# Regenerate documentation
tfplugindocs generate

# Verify no changes needed
git diff docs/

# If changes exist, commit them
git add docs/
git commit -m "docs: regenerate provider documentation"

Step 2: Update Changelog

# CHANGELOG.md
## [Unreleased]

## [1.0.0] - 2026-06-30

### Added
- Initial release of CacheCloud provider
- Resource: `cachecloud_cache` for managing cache instances
- Data source: `cachecloud_cache` for querying caches
- Support for Redis and Memcached engines
- Multi-AZ deployment configuration
- Automatic backup configuration
- Comprehensive documentation and examples

### Documentation
- Getting started guide
- Authentication guide
- Complete resource documentation
- Example configurations

[Unreleased]: https://github.com/example/terraform-provider-cachecloud/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/example/terraform-provider-cachecloud/releases/tag/v1.0.0

Step 3: Update README

# README.md

# Terraform Provider CacheCloud

[![Tests](https://github.com/example/terraform-provider-cachecloud/workflows/Tests/badge.svg)](https://github.com/example/terraform-provider-cachecloud/actions)
[![Release](https://github.com/example/terraform-provider-cachecloud/workflows/Release/badge.svg)](https://github.com/example/terraform-provider-cachecloud/releases)

The CacheCloud provider allows Terraform to manage CacheCloud infrastructure.

## Requirements

- [Terraform](https://www.terraform.io/downloads.html) >= 1.0
- [Go](https://golang.org/doc/install) >= 1.21 (for development)

## Using the Provider

```terraform
terraform {
  required_providers {
    cachecloud = {
      source  = "example/cachecloud"
      version = "~> 1.0"
    }
  }
}

provider "cachecloud" {
  api_key = var.cachecloud_api_key
}

resource "cachecloud_cache" "example" {
  name      = "my-cache"
  engine    = "redis"
  node_type = "cache.t3.micro"
}

Documentation

Full documentation is available on the Terraform Registry.

Development

# Clone repository
git clone https://github.com/example/terraform-provider-cachecloud

# Build provider
make build

# Run tests
make test

# Run acceptance tests
make testacc

Contributing

See CONTRIBUTING.md for guidelines.

License

Mozilla Public License Version 2.0 - see LICENSE for details.


### Step 4: Run Tests

```bash
# Unit tests
make test

# Acceptance tests (requires valid credentials)
export CACHECLOUD_API_KEY="test-key"
make testacc

# Verify all pass

Part 2: GPG Setup

Step 1: Generate GPG Key (if not done)

# Check for existing keys
gpg --list-secret-keys --keyid-format=long

# If none, generate new key
gpg --full-generate-key

# Select:
# - Type: RSA and RSA
# - Size: 4096
# - Expiration: 2y
# - Name: Your Name
# - Email: your.email@example.com
# - Comment: Terraform Provider Signing

Step 2: Export Keys

# Get key ID
gpg --list-secret-keys --keyid-format=long
# Note the key ID (e.g., ABCD1234EFGH5678)

KEY_ID="ABCD1234EFGH5678"

# Export public key
gpg --armor --export $KEY_ID > public-key.asc

# Export private key (for GitHub Secrets)
gpg --armor --export-secret-keys $KEY_ID > private-key.asc

# Get fingerprint
gpg --fingerprint $KEY_ID

Step 3: Configure Git

# Set signing key
git config --global user.signingkey $KEY_ID

# Enable automatic signing
git config --global commit.gpgsign true
git config --global tag.gpgsign true

Part 3: GitHub Setup

Step 1: Add GitHub Secrets

# Navigate to repository settings
open https://github.com/example/terraform-provider-cachecloud/settings/secrets/actions

# Add secrets:
# 1. GPG_PRIVATE_KEY: (contents of private-key.asc)
# 2. PASSPHRASE: (your GPG passphrase)

Step 2: Verify Workflows

# Check workflow files exist
ls .github/workflows/

# Expected:
# - release.yml
# - test.yml

release.yml:

name: Release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  goreleaser:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: 'go.mod'
          cache: true
      
      - name: Import GPG key
        id: import_gpg
        uses: crazy-max/ghaction-import-gpg@v6
        with:
          gpg_private_key: $
          passphrase: $
      
      - name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v5
        with:
          version: latest
          args: release --clean
        env:
          GPG_FINGERPRINT: $
          GITHUB_TOKEN: $

Step 3: Test GoReleaser Locally

# Install GoReleaser
brew install goreleaser

# Test release (dry run)
goreleaser release --snapshot --clean

# Check output
ls -la dist/

# Verify files:
# - Binaries for each platform
# - SHA256SUMS
# - SHA256SUMS.sig (if GPG configured)

Part 4: Create Release

Step 1: Commit Changes

# Stage all changes
git add .

# Commit
git commit -m "chore: prepare v1.0.0 release"

# Push to main
git push origin main

Step 2: Create and Push Tag

# Create signed tag
git tag -s v1.0.0 -m "Release v1.0.0

Initial release of CacheCloud provider:
- Resource: cachecloud_cache
- Data source: cachecloud_cache
- Redis and Memcached support
- Multi-AZ configuration
- Backup management
- Complete documentation"

# Verify tag
git tag -v v1.0.0

# Push tag
git push origin v1.0.0

Step 3: Monitor Release

# Watch GitHub Actions
open https://github.com/example/terraform-provider-cachecloud/actions

# Wait for release workflow to complete (5-10 minutes)

Step 4: Verify Release

# Check release page
open https://github.com/example/terraform-provider-cachecloud/releases/tag/v1.0.0

# Verify artifacts:

Expected artifacts:

✅ terraform-provider-cachecloud_1.0.0_darwin_amd64.zip
✅ terraform-provider-cachecloud_1.0.0_darwin_arm64.zip
✅ terraform-provider-cachecloud_1.0.0_linux_amd64.zip
✅ terraform-provider-cachecloud_1.0.0_linux_arm64.zip
✅ terraform-provider-cachecloud_1.0.0_windows_amd64.zip
✅ terraform-provider-cachecloud_1.0.0_SHA256SUMS
✅ terraform-provider-cachecloud_1.0.0_SHA256SUMS.sig
✅ terraform-provider-cachecloud_1.0.0_manifest.json
✅ Source code (zip)
✅ Source code (tar.gz)

Part 5: Registry Publication

Step 1: Register GPG Key

# Navigate to Terraform Registry
open https://registry.terraform.io/settings/gpg-keys

# Add GPG Key:
# 1. Click "Add GPG Key"
# 2. Paste contents of public-key.asc
# 3. Click "Add key"

Step 2: Publish Provider

# Navigate to publish page
open https://registry.terraform.io/publish/provider

# Select repository:
# 1. Choose "GitHub"
# 2. Select: example/terraform-provider-cachecloud
# 3. Review information
# 4. Click "Publish Provider"

Step 3: Wait for Processing

Registry processing (10-15 minutes):
├── Validate repository structure
├── Verify GPG signatures
├── Parse documentation
├── Generate provider page
└── Index for search

Step 4: Verify Publication

# Check provider page
open https://registry.terraform.io/providers/example/cachecloud/latest

# Verify:
# ✅ Provider overview displayed
# ✅ Documentation rendered correctly
# ✅ Version 1.0.0 listed
# ✅ All platforms available
# ✅ Examples working

Part 6: Test Installation

Step 1: Create Test Configuration

mkdir -p /tmp/test-provider
cd /tmp/test-provider

cat > main.tf <<EOF
terraform {
  required_providers {
    cachecloud = {
      source  = "example/cachecloud"
      version = "1.0.0"
    }
  }
}

provider "cachecloud" {
  # Configuration
}

output "provider_version" {
  value = "Provider installed successfully!"
}
EOF

Step 2: Initialize and Verify

# Initialize
terraform init

# Expected output:
# Initializing provider plugins...
# - Finding example/cachecloud versions matching "1.0.0"...
# - Installing example/cachecloud v1.0.0...
# - Installed example/cachecloud v1.0.0 (signed by a HashiCorp partner, key ID ...)
#
# Terraform has been successfully initialized!

# Verify version
terraform version

# Expected:
# Terraform v1.6.0
# + provider registry.terraform.io/example/cachecloud v1.0.0

Step 3: Test with Real Configuration

# main.tf
terraform {
  required_providers {
    cachecloud = {
      source  = "example/cachecloud"
      version = "~> 1.0"
    }
  }
}

provider "cachecloud" {
  api_key = "test-key"  # Use real key for actual test
}

resource "cachecloud_cache" "test" {
  name      = "test-cache"
  engine    = "redis"
  node_type = "cache.t3.micro"
}

# Plan (dry run)
terraform plan

# If API key valid, apply
terraform apply

Part 7: Post-Publication

Step 1: Announce Release

# Create announcement
cat > announcement.md <<EOF
🎉 CacheCloud Terraform Provider v1.0.0 Released!

We're excited to announce the first stable release of the CacheCloud Terraform provider!

🚀 Features:
- Manage cache instances (Redis & Memcached)
- Multi-AZ deployments
- Automatic backups
- Comprehensive documentation

📦 Installation:
\`\`\`terraform
terraform {
  required_providers {
    cachecloud = {
      source  = "example/cachecloud"
      version = "~> 1.0"
    }
  }
}
\`\`\`

📖 Documentation: https://registry.terraform.io/providers/example/cachecloud
📦 GitHub: https://github.com/example/terraform-provider-cachecloud

#Terraform #IaC #CacheCloud
EOF

# Post to:
# - GitHub Discussions
# - Twitter/X
# - Company blog
# - HashiCorp Community

Step 2: Monitor Feedback

# Watch GitHub issues
open https://github.com/example/terraform-provider-cachecloud/issues

# Check registry reviews
open https://registry.terraform.io/providers/example/cachecloud

# Monitor download statistics
# (Available in registry analytics after 24 hours)

Step 3: Plan Next Release

# ROADMAP.md

## v1.1.0 (Q3 2026)

### Planned Features
- [ ] Cluster mode support
- [ ] Parameter group resource
- [ ] Enhanced monitoring

### Improvements
- [ ] Better error messages
- [ ] Performance optimizations
- [ ] Additional examples

## v1.2.0 (Q4 2026)

### Planned Features
- [ ] Snapshot management
- [ ] Cost optimization features
- [ ] Advanced networking

Lab Challenges

Challenge 1: Patch Release

Create and publish v1.0.1 with a bug fix:

# 1. Fix a bug
# 2. Update CHANGELOG.md
# 3. Commit and tag v1.0.1
# 4. Verify automatic publication

Challenge 2: Pre-release Version

Create and publish v1.1.0-beta.1:

# 1. Add new feature
# 2. Tag as v1.1.0-beta.1
# 3. Publish to registry
# 4. Test installation

Challenge 3: Private Distribution

Set up alternative distribution:

# 1. Download release artifacts
# 2. Set up local mirror
# 3. Configure .terraformrc
# 4. Test installation from mirror

Verification Checklist

Pre-Release

  • ✅ All tests passing
  • ✅ Documentation complete
  • ✅ CHANGELOG updated
  • ✅ README updated
  • ✅ GPG key configured
  • ✅ GitHub secrets set

Release

  • ✅ Tag created and signed
  • ✅ GitHub Actions completed
  • ✅ All artifacts generated
  • ✅ Checksums signed
  • ✅ Release notes added

Publication

  • ✅ GPG key registered in registry
  • ✅ Provider published
  • ✅ Documentation rendered
  • ✅ Version available
  • ✅ Installation tested

Post-Publication

  • ✅ Announcement posted
  • ✅ Feedback monitored
  • ✅ Issues tracked
  • ✅ Analytics reviewed
  • ✅ Roadmap updated

Troubleshooting

Issue: Release Failed

# Check GitHub Actions logs
open https://github.com/example/terraform-provider-cachecloud/actions

# Common fixes:
# - Verify GPG secrets set correctly
# - Check .goreleaser.yml syntax
# - Ensure all tests pass

Issue: Documentation Not Rendering

# Validate documentation
tfplugindocs validate

# Check frontmatter format
# Regenerate if needed
tfplugindocs generate

Issue: Provider Not Found

# Verify registry publication completed
# Check provider page exists
# Wait for processing (10-15 minutes)
# Clear Terraform cache
rm -rf ~/.terraform.d/plugins
rm -rf .terraform
terraform init

Key Takeaways

  • ✅ Complete pre-release checklist systematically
  • ✅ Test GoReleaser locally before pushing tag
  • ✅ Sign all commits and tags
  • ✅ Monitor GitHub Actions workflow
  • ✅ Verify all release artifacts
  • ✅ Register GPG key before publishing
  • ✅ Wait for registry processing
  • ✅ Test provider installation
  • ✅ Announce release appropriately
  • ✅ Monitor and respond to feedback

Congratulations!

You’ve successfully published your Terraform provider! 🎉

Module 13 is complete. Continue to Module 14 to learn about advanced provider development topics.

Next Module: Advanced Topics →

Previous: ← Distribution Strategies
Next Module: Advanced Topics →

Last updated: June 30, 2026

Updated:

You may also enjoy