when_modified

The when_modified configuration allows you to configure autoplan and autoapply operations based on pull request file changes. This enables you to automatically trigger plan and apply operations when specific files are modified in your repository.

Configuration Levels

The when_modified configuration can be set at three different levels, all using the same syntax:

Global level - Applied to all directories unless overridden
Directory level - Set under dirs.<directory>.when_modified to override global settings for a specific directory
Workspace level - Set under dirs.<directory>.workspaces.<workspace>.when_modified to override settings for a specific workspace

All three levels support the exact same configuration options. More specific configurations override broader ones (workspace > directory > global).

Default Configuration

when_modified:
  file_patterns: ["${DIR}/*.tf", "${DIR}/*.tfvars"]
  autoplan: true
  autoplan_draft_pr: true
  autoapply: false
  depends_on: ""

Keys

Key	Type	Description
file_patterns	List	List of file globs to identify changes in a directory. Always relative to the root of the repository. Prefix with `!` to exclude a file glob. Default is `["${DIR}/.tf", "${DIR}/.tfvars"]`.
autoplan	Boolean	Automatically run a plan operation on a new pull request or an update on an existing one. Default is true.
autoplan_draft_pr	Boolean	Automatically run a plan operation on a new draft pull request or an update on an existing one. Default is true.
autoapply	Boolean	Automatically run an apply operation after merging a pull request. Default is false.
depends_on	String	Defines dependencies between different directories or environments, allowing for sequential operations. Supports `dir:` for absolute paths or `relative_dir:` for relative paths within the repository. Can also combine dependencies using tag queries. Default is an empty string.

File Patterns

The file_patterns key specifies a list of file globs that identify changes in a directory. These patterns are relative to the root of the repository.

Auto-Plan

The autoplan key enables or disables automatic plan operations on new pull requests or updates to existing ones.

Auto-Plan Draft Pull Request

The autoplan_draft_pr key enables or disables automatic plan operations on new draft pull requests or updates to existing ones.

Auto-Apply

The autoapply key enables or disables automatic apply operations after merging a pull request.

Depends-On

The depends_on key allows you to specify dependencies on other directories within your repository. This is particularly useful in scenarios where your infrastructure is structured into functional layers that must be deployed in a specific order. For example, a network setup must be applied before a managed PostgreSQL service can be deployed, as the latter might depend on outputs from the former.

Key Features

Layered Operations: Supports multi-layered operations, where each layer depends on the successful apply of the previous one.
Dependency Management: Automatically triggers plan and apply operations based on changes in the lowest layer, and cascades through dependent layers.

While the depends_on key can be specified in the top-level when_modified configuration (which would make ALL directories depend on the specified directories), it is strongly recommended to define dependencies at the directory or workspace level for better control. Use dirs.<directory>.when_modified.depends_on or dirs.<directory>.workspaces.<workspace>.when_modified.depends_on instead.

Configuration Examples

Same Configuration at Different Levels

The following three configurations achieve the same result for the production directory:

1. Global Level Configuration

when_modified:
  file_patterns: ["${DIR}/*.tf", "${DIR}/*.tfvars"]
  autoplan: true
  autoapply: false

2. Directory Level Configuration

dirs:
  production:
    when_modified:
      file_patterns: ["${DIR}/*.tf", "${DIR}/*.tfvars"]
      autoplan: true
      autoapply: false

3. Workspace Level Configuration

dirs:
  production:
    workspaces:
      default:
        when_modified:
          file_patterns: ["${DIR}/*.tf", "${DIR}/*.tfvars"]
          autoplan: true
          autoapply: false

Auto-Plan on Terraform File Changes

when_modified:
  file_patterns: ["${DIR}/*.tf"]
  autoplan: true
  autoplan_draft_pr: false
  autoapply: false

This configuration triggers a plan operation automatically when any .tf file in the repository is modified. It does not trigger plans on draft pull requests and does not automatically apply changes after merging.

Auto-Plan and Auto-Apply on Terraform and tfvars File Changes

when_modified:
  file_patterns: ["${DIR}/*.tf", "${DIR}/*.tfvars"]
  autoplan: true
  autoplan_draft_pr: true
  autoapply: true

This configuration triggers plan operations automatically on changes to .tf or .tfvars files, including draft pull requests. It also automatically applies changes after merging and creates a status check for pending applies.

Exclude Certain Files from Triggering Auto-Plan

when_modified:
  file_patterns: ["${DIR}/*.tf", "!**/modules/**/*.tf"]
  autoplan: true
  autoplan_draft_pr: true
  autoapply: false

This configuration triggers plan operations automatically on changes to .tf files, including draft pull requests, but excludes .tf files in the modules directory and its subdirectories.

Auto-Plan with Single Dependency

dirs:
  "database/":
    when_modified:
      depends_on: "relative_dir:../base"

This configuration triggers a plan operation for the database directory if changes are found in the base directory.

Depends-On with Multiple Dependencies

dirs:
  network:
    when_modified:
      file_patterns: ["${DIR}/*.tf"]
  database:
    when_modified:
      depends_on: 'dir:network'
      file_patterns: ["${DIR}/*.tf"]
  application:
    when_modified:
      depends_on: 'dir:database'
      file_patterns: ["${DIR}/*.tf"]

This configuration triggers a plan operation for the network layer if changes are detected. If the apply for the network layer is successful, a plan operation will be triggered for the database layer, which depends on network. If the database layer’s apply is successful, the process continues with a plan operation for the application layer, and so on.