Release Process

This document describes the release process for the LiteLLM Terraform Provider.

Overview

Releases are automated via GitHub Actions when a version tag is pushed. The workflow builds the provider for multiple platforms, signs the artifacts with GPG, and publishes them to GitHub Releases.

Prerequisites

GPG Key Setup (One-Time Setup for Repository Maintainers)

The Terraform Registry requires all providers to be signed with a GPG key. This must be configured before the first release.

1. Generate a GPG Key

If you don't already have a GPG key for provider signing:

bash

gpg --full-generate-key

Configuration:

Key type: RSA and RSA (default)
Key size: 4096 bits
Expiration: No expiration (or set a long expiration period)
Email: Use an email associated with your GitHub account
Set a strong passphrase (or leave empty for CI/CD use)

2. Export the GPG Key

bash

# List your keys to get the key ID
gpg --list-secret-keys --keyid-format=long

# Example output:
# sec   rsa4096/ABCD1234EFGH5678 2024-01-01 [SC]
#       1234567890ABCDEF1234567890ABCDEF12345678
# uid                 [ultimate] Your Name <[email protected]>
#
# The key ID is: ABCD1234EFGH5678
# The fingerprint is: 1234567890ABCDEF1234567890ABCDEF12345678

# Export the private key (ASCII-armored format)
gpg --armor --export-secret-keys ABCD1234EFGH5678

# Export the public key
gpg --armor --export ABCD1234EFGH5678

3. Configure GitHub Repository Secrets

Add the following secrets to the repository at: Settings → Secrets and variables → Actions → New repository secret

Secret Name	Description	Value
`GPG_PRIVATE_KEY`	The GPG private key for signing releases	Full output from `gpg --armor --export-secret-keys` (including `-----BEGIN PGP PRIVATE KEY BLOCK-----` and `-----END PGP PRIVATE KEY BLOCK-----`)
`PASSPHRASE`	The passphrase for the GPG key	Your GPG key passphrase (leave empty if no passphrase was set)

4. Register Public Key with Terraform Registry

Before publishing to the Terraform Registry:

Go to https://registry.terraform.io/settings/gpg-keys
Click "Add a key"
Paste your public GPG key (output from gpg --armor --export)
Submit

Note: The public key fingerprint must match the key used to sign the provider releases.

Release Steps

1. Prepare the Release

Before creating a release:

Update CHANGELOG.md
- Move items from [Unreleased] section to a new version section
- Follow Keep a Changelog format
- Use Semantic Versioning for version numbers
- Include all notable changes since the last release
Example:
markdown
```
## [0.1.2] - 2026-02-20

### Added
- New feature description

### Fixed
- Bug fix description

### Changed
- Changed behavior description
```
Verify tests pass
bash
```
make test
```
Verify the build works locally
bash
```
make build
```
Land the changes in BerriAI/litellm

Open a PR to BerriAI/litellm updating terraform/provider/CHANGELOG.md (and any source changes) and merge it

2. Mirror and Tag via project-releaser

The provider source lives at terraform/provider/ in BerriAI/litellm; BerriAI/terraform-provider-litellm is a thin release mirror. Do not commit or tag the mirror directly

Normally there is nothing to do here. BerriAI/project-releaser's release pipeline runs the same check on every release except adhoc, nightly included: it reads the topmost released heading in terraform/provider/CHANGELOG.md, probes the mirror for v<version>, and dispatches Publish Terraform provider only when the changelog has moved ahead of what the mirror carries. Cutting the version heading in step 1 is therefore what releases the provider, and the next release picks it up, so the wait is a day rather than a week

Dispatch by hand only for an out-of-band release, or to recover a run that failed:

Go to BerriAI/project-releaser > Actions > Publish Terraform provider
Click Run workflow:
- git_ref: full 40-char commit SHA from BerriAI/litellm to release from
- provider_version: the new version without the v prefix (e.g. 0.3.0)
- dry_run: optional; validates without pushing

Automatic or manual, the run waits on the production-release approval in project-releaser, then rsyncs terraform/provider/ into the mirror repo, commits, and pushes tag v<provider_version>. That approval is the only one in the flow. The tag push triggers the mirror's Release workflow (goreleaser), which runs unattended

Important:

Tags must follow the format: v<MAJOR>.<MINOR>.<PATCH> (e.g., v0.1.2, v1.0.0)
The workflow refuses to overwrite an existing tag; publish a new version instead

3. Monitor the Release Workflow

Go to: https://github.com/BerriAI/terraform-provider-litellm/actions
Find the "Release" workflow run for your tag
Monitor the progress and check for any errors

The workflow will:

Check out the code
Set up Go
Import the GPG key
Run go mod tidy
Build binaries for multiple platforms (Linux, macOS, Windows, FreeBSD)
Create archives and checksums
Sign the checksums with GPG
Create a GitHub release
Upload all artifacts

4. Verify the Release

After the workflow completes successfully:

Check the GitHub Release
- Go to: https://github.com/BerriAI/terraform-provider-litellm/releases
- Verify the release was created with the correct version
- Confirm all artifacts are present:
  - Binary archives for each platform
  - SHA256SUMS file
  - SHA256SUMS.sig (GPG signature)
  - terraform-registry-manifest.json

Verify the signature (optional)

bash

# Download the checksums and signature
wget https://github.com/BerriAI/terraform-provider-litellm/releases/download/v0.1.2/terraform-provider-litellm_0.1.2_SHA256SUMS
wget https://github.com/BerriAI/terraform-provider-litellm/releases/download/v0.1.2/terraform-provider-litellm_0.1.2_SHA256SUMS.sig

# Verify the signature
gpg --verify terraform-provider-litellm_0.1.2_SHA256SUMS.sig terraform-provider-litellm_0.1.2_SHA256SUMS

5. Publish to Terraform Registry (Optional)

If this provider is published to the Terraform Registry:

The registry should automatically detect the new release via the GitHub webhook
If not, you may need to manually trigger a sync on the Terraform Registry dashboard
Verify the new version appears at: https://registry.terraform.io/providers/BerriAI/litellm/latest

Troubleshooting

Release Workflow Fails with GPG Error

Error: Input required and not supplied: gpg_private_key

Solution:

Verify that GPG_PRIVATE_KEY and PASSPHRASE secrets are configured in the repository
Ensure the secrets are not expired
Check that the secret names match exactly (case-sensitive)

GoReleaser Signing Fails

Error: gpg: signing failed: No secret key

Solution:

Verify the GPG_PRIVATE_KEY secret contains the complete private key block
Ensure the passphrase is correct
Check that the key hasn't expired: gpg --list-keys

Build Fails

Error: Build errors during compilation

Solution:

Run make test and make build locally first
Ensure go.mod and go.sum are up to date
Check that all dependencies are available

Tag Already Exists

Error: The publish workflow refuses to push because the tag already exists on the mirror

Solution: Tags are immutable by design. Re-run the workflow with a new patch version instead of deleting or moving an existing tag

Version Numbering

This project follows Semantic Versioning:

MAJOR version (1.0.0): Incompatible API changes
MINOR version (0.1.0): New functionality in a backward-compatible manner
PATCH version (0.0.1): Backward-compatible bug fixes

For pre-1.0 releases:

Breaking changes may occur in minor versions
Patch versions should only contain bug fixes

Security Considerations

Never commit private keys: The GPG private key should only be stored as a GitHub secret
Protect repository secrets: Limit who has access to manage repository secrets
Use a dedicated key: Consider using a separate GPG key specifically for provider signing
Key rotation: If the GPG key is compromised, generate a new key, update secrets, and register the new public key with the Terraform Registry
Passphrase: Use a strong passphrase for the GPG key, or use a passphrase-less key specifically for CI/CD

Release Process

Release Process

Overview

Prerequisites

GPG Key Setup (One-Time Setup for Repository Maintainers)

1. Generate a GPG Key

2. Export the GPG Key

3. Configure GitHub Repository Secrets

4. Register Public Key with Terraform Registry

Release Steps

1. Prepare the Release

2. Mirror and Tag via project-releaser

3. Monitor the Release Workflow

4. Verify the Release

5. Publish to Terraform Registry (Optional)

Troubleshooting

Release Workflow Fails with GPG Error

GoReleaser Signing Fails

Build Fails

Tag Already Exists

Version Numbering

Security Considerations

References