Contributing

Contribution Guidelines

Contributions to Terragrunt are very welcome! We follow a fairly standard pull request process for contributions, subject to the following guidelines:

What to do before you start

Before starting any work, search for an existing PR, issue or discussion detailing the contribution you want to make.

If you don’t find anything, file a GitHub discussion or issue in this repo to document the desired change.

This is your chance to ask questions and get feedback from the maintainers and the community before you sink a lot of time into writing (possibly the wrong) code. If there is anything you’re unsure about, just ask! A discussion is more appropriate when you want to learn or discuss a problem or proposed change to Terragrunt. An issue is more appropriate when you have a reproducible bug report or a well defined solution to a problem that maintainers and the community have consensus on.

Sometimes, the scope of the feature proposal is large enough, or desired behavior is ambiguous enough that it requires an RFC. To write an RFC, click the RFC button in the issues tab.

This will present you a template you can fill out to describe the feature you want to propose.

The form can be a lot to fill out all at once. You can access the template for the RFC as a file here. It can be more convenient to fill out the form with a text editor, or use an AI agent to help you work through the different parts of the form locally before submitting. Make sure that the content is concise and that you fully understand the RFC before you submit it.

Update the documentation

Before updating any code, update the documentation for that code (see Readme Driven Development).

This ensures the documentation stays up to date and allows you to think through the problem at a high level before you get lost in the weeds of implementing the solution. It also helps you understand how the changes are going to impact users, and how they’ll learn about it.

The docs site is built with Starlight and hosted on Vercel from the docs folder on main branch. Read this README.md to learn more about making updates to the docs.

Don’t do the bare minimum to address this requirement. Try to leave the docs in a better place than you found them.

Update the tests

Before updating any code, update the tests for that code based on expected behavior (see Test Driven Development).

That means you add or update a test case, verify that it’s failing with a clear error message, and then make the code changes to get that test to pass. This ensures the tests stay up to date and verify all the functionality in this Module, including whatever new functionality you’re adding in your contribution.

Check out Developing Terragrunt for instructions on running the automated tests.

Don’t do the bare minimum to address this requirement. Try to leave the test suite in a better place than you found it.

Making your contribution

At this point, make your code changes and use your new test case to verify that everything is working. Check out Developing Terragrunt for instructions on how to build and run Terragrunt locally.

We have a style guide for the Go programming language, in which we documented some best practices for writing Go code. Please ensure your code adheres to the guidelines outlined in the guide.

Create a pull request

Create a pull request with your changes. Please make sure to include the following:

1. A description of the change, including a link to your GitHub issue.
2. The output of your automated test run, preferably in a GitHub Gist. We cannot run automated tests for pull requests automatically due to security concerns, so we need you to manually provide this test output so we can verify that everything is working.
3. Any notes on backwards incompatibility.

Merging your pull request

Maintainers will review your code and provide feedback. If everything looks good, they will merge your code and a tip build will be shared as a comment on the issue you closed with your PR (using the fixes #000 marker).

You can use this tip build to try out your fix early, before it’s released as part of the standard release process.

Developing Terragrunt

Running locally

To run Terragrunt locally, use the go run command:

go run . find

It can be useful to use the --working-dir to run Terragrunt in a different working directory so that you can build Terragrunt locally, but run Terragrunt elsewhere.

go run . --working-dir /path/to/fixture find

Linting

Terragrunt uses golangci-lint to lint the golang code in the codebase. This is a helpful form of static analysis that can catch common bugs and issues related to performance, style and maintainability.

We use the linter as a guide to learn about how we can improve the Terragrunt codebase. We do not enforce 100% compliance with the linter. If you believe that an error thrown by the linter is irrelevant, use the documentation on false-positives to suppress that error, along with an explanation of why you believe the error is a false positive.

If you feel like the linter is missing a check that would be useful for improving the code quality of Terragrunt, please open a discussion to discuss it.

The default configuration in .golangci.yml is used when running golangci-lint run. These lints must pass before any code is merged into the main branch.

Running the linter

Before any tests run in our continuous integration suite, they must pass the default linter. This is to ensure an acceptable floor for code quality in the codebase.

To run the default linter directly, use:

golangci-lint run

There’s also a Makefile recipe that runs the default linter:

make run-lint

Note

The Makefile recipe ensures that all code is linted, including lints for test code that isn’t run by default. You may see errors with golangci-lint if you don’t invoke the linter this way, as some code might seem unused to the linter by default.

If possible, you are advised to integrate the linter into your code editor to get immediate feedback as you edit Terragrunt code.

Markdownlint

In addition to the golang linter, we also use markdownlint to lint markdown content in the codebase. This is to ensure that the documentation is consistent and easy to read.

You’ll want to check that the markdown files are linted correctly before submitting a pull request to update the docs. You can do this by running:

markdownlint \
    --disable MD013 MD024 \
    -- \
    docs

Running tests

There are multiple different kinds of tests in the Terragrunt codebase, and each serves a different purpose.

Unit tests

These are the most common tests in the codebase, and they test small units of code. They are located in the same package as the code they are testing and are suffixed *_test.go.

They use a package directive that is suffixed _test of the package they test to force them to only test exported functions of that package, while residing in the same directory.

The idea behind this practice is to keep the tests close to the code they are testing, and to force them to only test the public API of the package. This allows implementation details of particular functions to change without breaking tests, as long as the public API behaves the same.

In general, if you are editing Terragrunt code, and there isn’t a unit test that covers the code you are updating, it’s probably a good idea to add one. If there is a unit test for the code you are updating, you should make sure that you run that test after any update to ensure that you haven’t broken anything.

When possible, introduce new tests for code before you start making changes. This is a practice known as Test Driven Development.

You can run unit tests for a particular package by running:

go test ./path/to/package

To specifically run a single test, you can use the -run flag:

go test -run TestFunctionName ./path/to/package

There are many ways to customize the go test command, including using flags like -v to get more verbose output. To learn more about go testing, read the official documentation.

Testing on Windows

Running tests on Windows can be more challenging. Sometimes, making some local configuration adjustments helps to reduce those challenges.

Specifically:

• Enable long file paths.
• Install a Bash shell (e.g., via Git Bash or WSL) in your environment.

See windows-setup.ps1 to see how we set up CI to get reliable results in Windows runners.

Integration tests

These are tests that test integrations between multiple parts of the Terragrunt codebase, and external services. They generally invoke Terragrunt as if you were using it from the command line.

These tests are located in the test directory, and are suffixed *_test.go.

Often, these tests run against test fixtures, which are small Terragrunt configurations that emulate specific real-world scenarios. These test fixtures are located in the test/fixtures directory.

To run the integration tests, you can use the go test command:

go test ./test

Note that integration tests can be slow, as they often involve running full Terragrunt commands, and that frequently involves spawning new tofu/terraform processes. As a result, you may want to run only a subset of the tests while developing.

You can do this by using the -run flag:

go test -run '^TestBeginningOfFunctionName' ./test

This will run all tests that start with TestBeginningOfFunctionName.

Some tests may require that you opt-in for them to be tested. This is because they may require access to external services that you need to authenticate with or use a specific external tool that you might not have installed. In these cases, we use golang build tags to conditionally compile the tests. You can run these tests by setting the appropriate build tag before testing.

For example, AWS tests are tagged using the aws build tag. To run these tests, you can use the -tags flag like so:

go test -tags=aws ./...

Depending on how you’ve configured your development environment, you may need to make sure that your editor has the GOFLAGS environment variable set before starting for the best development experience, as the gopls language server will throw errors that it can’t compile the test code you’re editing behind a build flag otherwise.

export GOFLAGS='-tags=aws'
neovim .

In general, we try to make sure that any test that requires a build tag is also consistently prefixed with a shared prefix so that they can be tested as a group in an environment configured to support it.

For example, all AWS tests are prefixed with TestAWS*, so if you authenticate your local session with AWS, you can test all code related to AWS by targeting that prefix.

OpenTofu tests

The largest group of opt-in tests are the ones that test integration with a real OpenTofu/Terraform binary. They’re prefixed with TestTF* and tagged with the tf build tag:

go test -tags=tf -run '^TestTF' ./...

Tests that depend on OpenTofu specifically, rather than on whichever binary tf-path points at, are prefixed with TestTofu* and tagged with the tofu build tag. Run them alongside the TestTF* tests, the way CI does:

go test -tags=tofu,tf -run '^(TestTF|TestTofu)' ./...

Without those tags, go test ./... only runs the tests that Terragrunt can satisfy on its own with no external integrations, so the suite stays green in an environment with no external dependencies installed. Add the tag whenever you modify behavior that reaches an orchestrated binary.

GCP tests

Terragrunt has integration tests for Google Cloud Platform (GCP). These tests are prefixed with TestGCP* and are tagged with the gcp build tag. To run these tests, you can use the -tags flag set in the GOFLAGS environment variable, similar to AWS tests:

go test -tags=gcp ./internal/gcphelper/...
go test -tags=gcp -run '^TestGCP' ./test

To successfully run GCP integration tests, you must set the following environment variables:

• GCLOUD_SERVICE_KEY: The service account JSON key used for authentication.
• GOOGLE_CLOUD_PROJECT or GOOGLE_PROJECT_ID: The GCP project name.
• GOOGLE_COMPUTE_ZONE: The compute zone name.
• GOOGLE_IDENTITY_EMAIL: The service account identity email.
• GCLOUD_SERVICE_KEY_IMPERSONATOR: (Optional) An additional service account key used in impersonation tests.

Make sure these environment variables are set in your shell before running tests. For example:

export GCLOUD_SERVICE_KEY="/path/to/service-account.json"
export GOOGLE_CLOUD_PROJECT="your-gcp-project"
export GOOGLE_COMPUTE_ZONE="us-central1-a"
export GOOGLE_IDENTITY_EMAIL="service-account@your-gcp-project.iam.gserviceaccount.com"
export GCLOUD_SERVICE_KEY_IMPERSONATOR="/path/to/impersonator-service-account.json"

The service account used for GCP tests must have the following IAM roles in your GCP project:

• roles/storage.admin
• roles/iam.serviceAccountTokenCreator

You can assign these roles using the following gcloud commands:

gcloud projects add-iam-policy-binding <gcp-project> \
  --member="<service-account>" \
  --role="roles/storage.admin"

gcloud projects add-iam-policy-binding <gcp-project> \
  --member="<service-account>" \
  --role="roles/iam.serviceAccountTokenCreator"

Azure tests

Terragrunt has integration tests for Azure. These are prefixed with TestAzure* and use the azure build tag, because they create and destroy real Azure resources.

go test -tags=azure ./internal/azurehelper/...
go test -tags=azure -run 'TestAzure*' ./test

The internal/azurehelper live test skips when the credentials are absent. The tests under test/ fail rather than skip, so a misconfigured environment is visible instead of silently reporting success.

To successfully run Azure integration tests, you must set the following environment variables:

• TG_AZURE_TEST_SUBSCRIPTION_ID: The subscription hosting the test storage account. ARM_SUBSCRIPTION_ID or AZURE_SUBSCRIPTION_ID also work.

• TG_AZURE_TEST_STORAGE_ACCOUNT: The name of a pre-existing storage account the tests create containers in. ARM_STORAGE_ACCOUNT_NAME also works.

• AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID: Service principal credentials. The ARM_* spelling of each is also accepted, and these can be omitted entirely when authenticating with az login.

With ARM-capable authentication, the resource group is looked up from the storage account. Set TG_AZURE_TEST_RESOURCE_GROUP when using an access key or SAS token, because data-plane credentials cannot perform that lookup.

export TG_AZURE_TEST_SUBSCRIPTION_ID="00000000-0000-0000-0000-000000000000"
export TG_AZURE_TEST_STORAGE_ACCOUNT="tgteststate"
az login

The identity used for Azure tests must have the following roles:

• Storage Blob Data Contributor, because the tests authorize blob access with Microsoft Entra rather than an account key.
• Storage Account Contributor, because blob versioning and soft delete are management-plane properties of the account. Without it, TestAzureBackendVersioningConverges cannot converge them.

You can assign these roles using the following Azure CLI commands:

RG="/subscriptions/<subscription-id>/resourceGroups/<resource-group>"

az role assignment create \
  --assignee "<client-id>" \
  --role "Storage Blob Data Contributor" \
  --scope "$RG"

az role assignment create \
  --assignee "<client-id>" \
  --role "Storage Account Contributor" \
  --scope "$RG"

Scoping both roles to the resource group also lets the tests resolve it from the storage account name, so no subscription-wide assignment is needed.

An account key (ARM_ACCESS_KEY) authenticates the blob data plane and is enough for most of the suite, but it cannot reach the management plane at all, so TestAzureBackendVersioningConverges skips under it. Only an Entra identity runs the whole suite.

The tests create and delete blob containers with unique names on each run; they never create or delete the storage account itself.

Race tests

Given that Terragrunt is a tool that frequently involves running concurrent code, there’s a higher than average risk for race conditions to occur. As such, there are dedicated tests that are run with the -race flag in CI to use golang’s built-in tooling for identifying race conditions.

We can do a better job of finding candidates for additional testing here, so if you are interested in helping out, please open a discussion to discuss it.

The convention we use for race tests is to prefix them with WithRacing. The CI workflow will run these tests with the -race flag as part of the test suite.

Sandboxed tests

Terragrunt routes side effects like interacting with the filesystem through virtualized handles, so tests can drive fake filesystems, subprocess and HTTP clients without actually interacting with the host environment. This helps us to make sure that tests pass reliably by default, are generally faster and won’t pass unreliably on different machines.

This is done using the venv package.

A test can bypass that virtualized handle in a couple ways:

1. A test that reaches the network directly without going through a virtualized client handle.

2. A test that writes to arbitrary directories.

3. A test that runs a real external process, like tofu or terraform.

To check for all of them, run the suite through the sandbox wrapper:

./.github/scripts/ci/sandbox-test.sh

Tip

Before reading anything into a passing run, confirm the sandbox is working. The output will tell you what it restricts:

./.github/scripts/ci/sandbox-exec.sh --check

Loopback stays reachable, so tests that stand up an httptest server keep working, and tests that use vhttp can mock network traffic. Writes stay open in the temp directory, the Go caches and Terragrunt’s user cache. A test that needs to test process execution can substitute vexec for the real process. Tests that need to test filesystem interactivity can use vfs.

How the sandbox is built, and how much it covers, differ by platform:

Linux

Each test binary runs in its own network namespace, created with unshare. The network_namespaces(7) and user_namespaces(7) man pages cover what that isolates. Writes and execution are not confined. Doing either needs bubblewrap or a Landlock wrapper, neither of which is wired up, so --check reports the network half alone.

This is the platform Continuous Integration runs on, so CI checks the network and nothing else.

Ubuntu 24.04 and later confine unprivileged user namespaces with AppArmor, which stops unshare from creating that namespace. If the check reports that the sandbox cannot run a command at all, lift the restriction:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

macOS

Each test binary runs under the seatbelt profile at .github/scripts/ci/sandbox.sb, applied with sandbox-exec. That profile confines the network, writes and toolchain execution together.

Nothing to set up. sandbox-exec ships with macOS. Apple documents sandbox-exec(1) and sandbox(7) but not the profile language, so the profiles under /System/Library/Sandbox/Profiles are the working reference for changing sandbox.sb.

Benchmark tests

Benchmark tests are run with the -bench flag to the go test command. They are used to measure the performance of a particular function or set of functions.

You can find them by looking for tests that start with Benchmark* instead of Test* in the codebase.

In general, if you contribute any change to Terragrunt that is designed to impact (or carefully not impact) performance you must submit benchmarks to demonstrate the impact of your change.

For more information on Terragrunt performance, read the dedicated Performance documentation.

Continuous Integration

All of the testing mentioned above is run automatically as part of our continuous integration suite in GitHub Actions.

You can find that workflow here.

Debug logging

Set the TG_LOG_LEVEL environment variable to debug before running Terragrunt to get debug information.

Error handling

In this project, we try to ensure that every error has a custom type or uses an error sentinel. This makes error handling more precise, as we can decide to handle different types or values of errors intentionally.

Formatting

Every source file in this project should be formatted with go fmt. There are few helper scripts and targets in the Makefile that can help with this:

1. make fmtcheck Checks to see if all source files are formatted. Exits 1 if there are unformatted files.

2. make fmt Formats all source files with gofmt.

3. make install-pre-commit-hook

   Installs a git pre-commit hook that will run all of the source files through gofmt.

To ensure that your changes get properly formatted, please install the git pre-commit hook with make install-pre-commit-hook.

Development Containers

Development Containers enable you to capture an entire development environment within a container. They can specify the required binaries, languages, extensions, and settings for a project. They can even define commands to run when entering the container. The Dev Container spec is met by a number of supporting tools and editors, but here we demonstrate a Visual Studio Code example for contributing to the Terragrunt project.

1. Install the Dev Containers VSCode extension.

2. Create a .devcontainer.json file at the project root.

   The example below:

   • Launches a container configured with the appropriate version of Go.
   • Integrates golangci-lint (the standard Golang linter) into the editor.
   • Installs the markdownlint extension with specific rules disabled:
     • MD013
     • MD024
   • Includes Node.js and OpenTofu.
   • Starts the Astro Starlight docs upon container startup.

   .devcontainer.json

   {
     "name": "Terragrunt Contributing IDE",
     "image": "mcr.microsoft.com/devcontainers/go:1-1.23-bookworm",
     "runArgs": ["--network=host"],
     "customizations": {
       "vscode": {
         "settings": {
           "go.lintTool": "golangci-lint",
           "go.lintFlags": [
             "--fast"
           ],
           "markdownlint.config": {
             "MD013": false,
             "MD024": false
           }
         },
         "extensions": [
           "davidanson.vscode-markdownlint"
         ]
       }
     },
     "features": {
       "ghcr.io/devcontainers/features/node:1": {},
       "ghcr.io/robbert229/devcontainer-features/opentofu:1": {}
     },
     "postCreateCommand": "cd docs && npm install && npm run dev"
   }

3. Open the project as a VSCode workspace and select Reopen in Container when prompted.

   Tip

   If you miss the prompt, just open the command palette and run:

   Dev Containers: Rebuild and Reopen in Container

Releasing your changes

To learn about how changes get released, read the Releases documentation.