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

import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';

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.

## 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, go to the [Releases Page](https://github.com/gruntwork-io/terragrunt/releases) and cut a new pre-release off the `main` branch. Ensure that the new release uses the **Set as a pre-release** checkbox initially.

The GitHub Actions workflow for this repository has been configured to:

1. Automatically detect new tags.

2. Build assets for every OS using that tag as a version number (including binaries, archives, checksums, signature files, etc.).

3. Upload the assets to the release in GitHub.

See [`.github/workflows/release.yml`](https://github.com/gruntwork-io/terragrunt/blob/main/.github/workflows/release.yml) for details.

Follow the GitHub Actions logs to ensure that the assets are built and uploaded correctly. Once the job is successful, go back to the release, give the release notes a final review, then uncheck the **Set as a pre-release** checkbox and check the **Set as the latest release** checkbox.

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

Alpha pre-releases are generally cut off a feature branch, in order to keep the `main` branch stable and releasable at all times.

Pre-releases are tagged with a pre-release name that looks like the following: `alpha2025022501`, etc. with the following information:

- Channel: e.g. `alpha` (indicating the stability of the release)

  The `alpha` channel has the following meaning in Terragrunt:

  - `alpha`: This release is recommended for testing in non-production environments only. It is intended for testing out new features with stakeholders external to Gruntwork before a general release.

  At the moment, this is really the only channel we need. In the future, we might adjust this to include more channels, such as `beta`, etc.

- Date: e.g. `20250225` (indicating the date the release was cut without dashes or slashes)
- Incremental number: e.g. `01` (indicating the number of pre-releases cut on that day)

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

The current plan for how maintainers are going to handle pre-releases after 1.0 is that:

1. Pre-releases for the `alpha` channel will continue to be cut from feature branches, and use the same naming convention as before.
2. Pre-releases for the `rc` channel will be cut from the `main` branch, and use a naming convention that looks like `v1.0.0-rc1`, which is incremented for each release candidate.

Release candidates in the `rc` channel will undergo more thorough testing, both automated and manual.

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

