Docs

Terragrunt

Description

The Terragrunt crawler looks recursively for all Terragrunt files (*.hcl) containing a module definition from a specific root directory. Then for each of them, it tries to automate its update.

It currently support two types of sources: - terraform/registry - gittag

It will parsed the module source and infer the source type.

It will update the file using the hcl target.

It supports the following module source definition and will update with prefixing accordingly

terraform {
  source = "tfr://someModule?version=1.2.3
}
terraform {
  source = local.base_url
}
terraform {
  source = "tfr://${local.module}?version=${local.module_version}"
}
terraform {
  source = "tfr://someModule?version=${local.module_version}"
}
terraform {
  source = "tfr://${local.module}?version=1.2.3"
}

This crawler is enabled by default, so it can be used either automatically by running updatecli diff from a directory containing the files to update, or by providing a manifest. The automatic discovery behavior can be tuned by providing a YAML manifest with a terragrunt crawler in top-level directive autodiscovery as explained in the "Autodiscovery" page.

Generated manifests

The source kind is inferred from the module source:

  • a tfr:// source resolves through terraform/registry,

  • a git:: source resolves through gittag, reading tags from the remote repository.

In both cases the version is written back with the hcl target.

Authentication

Git-hosted modules are queried over the network, so private repositories need credentials. Set username and token to authenticate against the git provider.

Manifest

Parameters

NameTypeDescriptionRequired
ignorearrayignore specifies rule to ignore .terraform.lock.hcl update.
    modulesobject

modules specifies a map of modules, the key is module url as seen in the different terragrunt manifests, the value is an optional semver version constraint.

examples: - providers: # Ignore modules update for a specific registry tfr://registry.opentofu.org: # Ignore modules updates for a very specific module tfr:///terraform-aws-modules/rdss/aws: registry.terraform.io/hashicorp/aws: # Ignore module updates for this version git@github.com:hashicorp/exampleLongNameForSorting.git: "1.x"

    pathstringpath specifies a terragrunt manifest path pattern, the pattern requires to match all of name, not just a substring.
onlyarrayonly specify required rule to restrict .terraform.lock.hcl update.
    modulesobject

modules specifies a map of modules, the key is module url as seen in the different terragrunt manifests, the value is an optional semver version constraint.

examples: - providers: # Ignore modules update for a specific registry tfr://registry.opentofu.org: # Ignore modules updates for a very specific module tfr:///terraform-aws-modules/rdss/aws: registry.terraform.io/hashicorp/aws: # Ignore module updates for this version git@github.com:hashicorp/exampleLongNameForSorting.git: "1.x"

    pathstringpath specifies a terragrunt manifest path pattern, the pattern requires to match all of name, not just a substring.
rootdirstringrootdir defines the root directory from where looking for terragrunt configuration
tokenstring

token specifies the token to use for Git authentication when accessing private repositories. Works with any Git provider (GitHub, GitLab, Bitbucket, Gitea, etc.)

compatible:

  • autodiscovery

default: When not specified: No authentication (suitable for public repositories)

remark: Must be explicitly set for private repositories. Use template functions to read from environment: token: “{{ requiredEnv "GITLAB_TOKEN" }}”

example: token: “ghp_xxxxxxxxxxxx” token: “glpat-xxxxxxxxxxxx” token: “{{ requiredEnv "GITLAB_TOKEN" }}”

usernamestring

username specifies the username to use for Git authentication when accessing private repositories. Works with any Git provider (GitHub, GitLab, Bitbucket, Gitea, etc.)

compatible:

  • autodiscovery

default: When not specified: “oauth2” (matches GitHub SCM plugin, required for go-git HTTP BasicAuth)

remark: For token-based auth, the username is typically a placeholder (token identifies the user). Common values: “oauth2” (default), “x-access-token”, “git”, or actual username. Use template functions to read from environment: username: “{{ requiredEnv "GIT_USERNAME" }}”

example: username: “git” username: “oauth2” username: “{{ requiredEnv "GIT_USERNAME" }}”

versionfilterobject

versionfilter provides parameters to specify the version pattern to use when generating manifest.

kind - semver versionfilter of kind semver uses semantic versioning as version filtering pattern accepts one of: patch - patch only update patch version minor - minor only update minor version major - major only update major versions a version constraint such as >= 1.0.0

kind - regex versionfilter of kind regex uses regular expression as version filtering pattern accepts a valid regular expression

example: versionfilter: kind: semver pattern: minor

and its type like regex, semver, or just latest.

    kindstringspecifies the version kind such as semver, regex, or latest
    patternstringspecifies the version pattern according the version kind for semver, it is a semver constraint for regex, it is a regex pattern for time, it is a date format
    regexstringspecifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used.
    replaceallobjectreplaceAll applies a regex replacement to version strings before filtering. This is useful for transforming versions (e.g., curl-8_15_0 to curl-8.15.0) before regex extraction.
        patternstringPattern specifies the regex pattern to match for replacement
        replacementstringReplacement specifies the replacement string (supports $1, $2, etc. for captured groups)
    strictbooleanstrict enforce strict versioning rule. Only used for semantic versioning at this time
⚠ This table is generated from the Updatecli codebase and may contain inaccurate data. Feel free to report them on github.com/updatecli/updatecli

Example

# updatecli.d/default.yaml
name: "Terraform autodiscovery using git scm"
scms:
  default:
    kind: git
    spec:
      url: https://github.com/updatecli-test/jenkins-infra-aws.git
      branch: main

autodiscovery:
  # scmid is applied to all crawlers
  scmid: default
  crawlers:
    terraform:
      # platforms to request package checksums for, defaults to:
      platforms:
        - linux_amd64
        - linux_arm64
        - darwin_amd64
        - darwin_arm64
      # To ignore specific path
      #ignore:
      #  - path: <filepath relative to scm repository>
      #  - providers:
      #      # Ignoring provider updates for this provider
      #      registry.terraform.io/hashicorp/aws:
      #      # Ignore provider updates for this version
      #      registry.terraform.io/hashicorp/kubernetes: "1.x"

      ignore:
      #  - path: <filepath relative to scm repository>
      #  - providers:
      #      # Ignoring provider updates for this provider
      #      registry.terraform.io/hashicorp/aws:
      #      # Ignore provider updates for this version
      #      registry.terraform.io/hashicorp/kubernetes: "1.x"
Last updated on July 30, 2026
Prev
Terraform
Next
updatecli