Releases

Terragrunt releases use semantic versions (semver).

Note that as of 2026/01/27, Terragrunt is still pre-1.0, so breaking changes may still be introduced in minor releases. We will try to minimize these changes as much as possible, but they may still happen.

Once 1.0 is released, Terragrunt backwards compatibility will be guaranteed for all minor releases (see Terragrunt 1.0 Guarantees for details on what constitutes a breaking change).

This documentation should be updated at that time to reflect the new policy. If it has not, please file a bug report.

Immutable Releases

Terragrunt uses GitHub’s immutable releases to ensure that once a release is published, its tag and assets cannot be modified or deleted. This means the binary you download today is the same binary that was uploaded when the release was published.

To support immutability, releases are built as drafts first. All artifacts are uploaded and verified before the release is published. Once published, the git tag is created and the release is locked.

Not yet enabled

Immutable releases are not yet turned on for the gruntwork-io/terragrunt repository. The release workflow has been updated to support them, and maintainers want to run a few releases through the new workflow before enabling the setting on GitHub.

When to Cut a New Release

While Terragrunt is still pre-1.0, maintainers will cut a new release whenever a new feature is added or a bug is fixed. Maintainers will exercise their best judgment to determine when a new release is necessary, and bias towards cutting a new release as frequently as possible when in doubt.

How to Create a New Release

To release a new version of Terragrunt:

1. Go to the Releases Page and click Draft a new release.

2. In the Choose a tag field, enter the version (e.g., v1.0.2). Select Create new tag: v1.0.2 on publish.

3. Set the target to an explicit commit SHA, not a branch name. This prevents new commits from being pulled into the release between draft creation and publishing. You can find the commit SHA from the tip of the branch you want to release (e.g., main).

4. Set the release title to the version tag (e.g., v1.0.2).

5. Click Save draft.

6. Trigger the Release workflow via Run workflow, providing the version string you just drafted (e.g., v1.0.2). The workflow looks up the draft release, reads its target commit SHA, and will:

   • Validate the tag is a valid semantic version
   • Verify the target is a commit SHA (not a branch name)
   • Build binaries for every supported OS and architecture
   • Sign macOS and Windows binaries
   • Generate checksums and cryptographic signatures
   • Upload all assets to the draft release

7. Once the workflow succeeds, go back to the draft release and verify the assets are present and downloadable.

8. Write or finalize the release notes.

Re-running after edits

If you edit the draft (for example, to retarget a new commit SHA), re-run the Release workflow with the same version to rebuild and overwrite the assets. Editing the draft does not automatically trigger a rebuild.

9. When ready:

   • For stable releases: uncheck Set as a pre-release and check Set as the latest release.
   • For pre-releases: check Set as a pre-release.

10. Click Publish release. This creates the git tag at the pinned commit, makes the release immutable, and triggers the release announcement.

Retrying a Failed Build

If the build workflow fails mid-way, re-run the Release workflow via workflow_dispatch with the same version (e.g., v1.0.2). It looks up the existing draft release and rebuilds, overwriting any previously uploaded assets.

Pre-releases

Occasionally, Terragrunt maintainers will cut a pre-release to get feedback on the UI/UX for a new feature or to give the community a chance to test it in the wild before making it generally available.

All pre-releases use semver-compliant version strings:

• v1.0.0-alpha.1: Alpha pre-releases, recommended for testing in non-production environments only. Intended for testing new features with stakeholders external to Gruntwork before a general release.
• v1.0.0-beta.1: Beta pre-releases, for broader testing.
• v1.0.0-rc1: Release candidates, which undergo more thorough testing (automated and manual) before the final release.

This pre-release system is subject to change, and maintainers will update this documentation to reflect any changes.

Tip Builds

Every successful CI run on the main branch automatically produces a tip build. Tip builds are builds of Terragrunt from the latest commit at the time of build (the tip of the main branch). Tip builds are versioned as tip-{commit_sha} and are available for all supported platforms as .tar.gz archives. Windows and macOS binaries are not signed as they are in full releases, and a reduced set of assets are included.

Tip builds are useful for testing the latest changes on main before a release is cut, or for reproducing issues against the most recent code.

No retention guarantee

Tip builds may be reclaimed at any time to reduce hosting costs. Do not rely on a specific tip build being available indefinitely. Use official releases for long-lived references.

Accessing Tip Builds

Tip builds are served via the builds API at https://builds.terragrunt.com.

The API can be used to get metadata for the latest tip build, or for a specific build by commit SHA.

The download endpoints accept either os and arch query parameters to download a platform-specific archive, or a filename query parameter to download a specific file by name.

Latest

Get metadata — returns build info for the latest tip build.

GET /api/v1/tip/latest

curl https://builds.terragrunt.com/api/v1/tip/latest

Download by platform — redirects to the .tar.gz archive for the given OS and architecture.

GET /api/v1/tip/latest/download?os=<os>&arch=<arch>

curl -L -o terragrunt.tar.gz \
  "https://builds.terragrunt.com/api/v1/tip/latest/download?os=linux&arch=amd64"

Download by filename — redirects to a specific file from the build (e.g., SHA256SUMS).

GET /api/v1/tip/latest/download?filename=<name>

curl -L -o SHA256SUMS \
  "https://builds.terragrunt.com/api/v1/tip/latest/download?filename=SHA256SUMS"

By Commit SHA

Get metadata — returns build info for a specific commit.

GET /api/v1/tip/{ref}

curl https://builds.terragrunt.com/api/v1/tip/abc123def456

Download by platform — redirects to the .tar.gz archive for the given OS and architecture.

GET /api/v1/tip/{ref}/download?os=<os>&arch=<arch>

curl -L -o terragrunt.tar.gz \
  "https://builds.terragrunt.com/api/v1/tip/abc123def456/download?os=darwin&arch=arm64"

Download by filename — redirects to a specific file from the build (e.g., SHA256SUMS).

GET /api/v1/tip/{ref}/download?filename=<name>

curl -L -o SHA256SUMS \
  "https://builds.terragrunt.com/api/v1/tip/abc123def456/download?filename=SHA256SUMS"

Signing and Verification

Tip builds are signed using the same process as official releases. Each build includes:

• SHA256SUMS — checksums for all archives
• SHA256SUMS.gpgsig — GPG signature of the checksums file
• SHA256SUMS.sigstore.json — Sigstore (Cosign) signature of the checksums file

Test Builds

Maintainers can manually trigger a test build from any branch using the test-build.yml workflow via workflow_dispatch. Test builds are versioned as test-{commit_sha} and uploaded under the test prefix (or tip if triggered from main).

This is useful for giving stakeholders a binary to test before a feature branch is merged.