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.