---
title: Releases
description: Learn about the Terragrunt release process.
slug: process/releases
sidebar:
  order: 3
---

import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import Since from '@components/Since.astro';
import Before from '@components/Before.astro';

Terragrunt releases use [semantic versions (semver)](https://semver.org/).

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](/process/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](https://docs.github.com/en/code-security/concepts/supply-chain-security/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.

<Before version="1.1.0">
Immutable releases are not yet enabled for the repository. The release workflow already supports them, and the setting will be turned on starting with `v1.1.0`.
</Before>

<Since version="1.1.0">
Releases starting with `v1.1.0` are immutable. Releases published before then predate the setting being enabled on the repository, so they are not locked.
</Since>

## 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](https://github.com/gruntwork-io/terragrunt/releases) 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](https://github.com/gruntwork-io/terragrunt/actions/workflows/release.yml) 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.

<Aside type="note" title="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.
</Aside>

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.

<Aside type="caution" title="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.
</Aside>

### 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.

<Tabs>
  <TabItem label="Latest">
    **Get metadata** — returns build info for the latest tip build.

    ```
    GET /api/v1/tip/latest
    ```

    ```bash
    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>
    ```

    ```bash
    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>
    ```

    ```bash
    curl -L -o SHA256SUMS \
      "https://builds.terragrunt.com/api/v1/tip/latest/download?filename=SHA256SUMS"
    ```
  </TabItem>
  <TabItem label="By Commit SHA">
    **Get metadata** — returns build info for a specific commit.

    ```
    GET /api/v1/tip/{ref}
    ```

    ```bash
    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>
    ```

    ```bash
    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>
    ```

    ```bash
    curl -L -o SHA256SUMS \
      "https://builds.terragrunt.com/api/v1/tip/abc123def456/download?filename=SHA256SUMS"
    ```
  </TabItem>
</Tabs>

### 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`](https://github.com/gruntwork-io/terragrunt/actions/workflows/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.
