Skip to main content
Fields marked as Required must be set. Optional fields have sensible defaults shown below.
You can configure Digger by dropping a digger.yml file at the root level of your repo. 
projects:
  - name: my-first-app
    dir: app-one
  - name: my-second-app
    dir: app-two
auto_merge: true
You can also name your Digger configuration file differently, and specify its name using the digger-filename input at GitHub Action level. 
traverse_to_nested_projects: true
auto_merge: false
pr_locks: true
allow_draft_prs: false
apply_after_merge: false
comment_render_mode: basic
report_terraform_outputs: true
mention_drifted_projects_in_pr: false
disable_digger_apply_comment: false
disable_digger_apply_status_check: false
trusted_appIDs:
  - 41898282
respect_layers: false
reporting:
  ai_summary: false
  comments_enabled: true
dependency_configuration:
  mode: hard
projects:
  - name: prod
    dir: prod
    alias: production
    apply_requirements: [approved, mergeable, undiverged]
    branch: main
    workspace: default
    terragrunt: false
    opentofu: false
    pulumi: false
    pulumi_stack: ""
    workflow: prod
    workflow_file: digger_workflow.yml
    drift_detection: true
    layer: 0
    include_patterns: ["../modules/**"]
    exclude_patterns: []
    depends_on: []
    aws_role_to_assume:
      aws_role_region: us-east-1
      state: arn:aws:iam::123456789012:role/state-role
      command: arn:aws:iam::123456789012:role/command-role
    aws_cognito_oidc:
      aws_account_id: "123456789012"
      aws_region: us-east-1
      cognito_identity_pool_id: us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      session_duration: 3600
  - name: staging
    dir: staging
    branch: main
    workflow: staging
    include_patterns: ["../modules/**"]
    exclude_patterns: []
generate_projects:
  include: "../projects/**"
  exclude: "../.terraform/**"
  terragrunt: false
  blocks:
    - block_name: dev-block
      include: "dev/**"
      exclude: "dev/.terraform/**"
      workflow: dev
      workflow_file: digger_workflow.yml
      opentofu: false
      terragrunt: false
      include_patterns: []
      exclude_patterns: []
      aws_role_to_assume:
        aws_role_region: us-east-1
        state: arn:aws:iam::123456789012:role/state-role
        command: arn:aws:iam::123456789012:role/command-role
workflows:
  staging:
    env_vars:
      state:
        - name: TF_LOG
          value: trace
      commands:
        - name: TF_LOG
          value: trace
    plan:
      filter_regex: ""
      steps:
        - init:
          extra_args: ["backend-config=../backend.hcl"]
        - run: "echo hello world"
        - plan
    apply:
      filter_regex: ""
      steps:
        - run: "echo hello world"
          shell: zsh
        - init
        - apply:
          extra_args: ["-compact-warnings"]
    workflow_configuration:
      on_pull_request_pushed: ["digger plan"]
      on_pull_request_closed: ["digger unlock"]
      on_pull_request_to_draft: []
      on_commit_to_default: ["digger apply"]
      skip_merge_check: false
  prod:
    env_vars:
      state:
        - name: AWS_ACCESS_KEY_ID
          value_from: PROD_BACKEND_TF_ACCESS_KEY_ID
        - name: AWS_SECRET_ACCESS_KEY
          value_from: PROD_BACKEND_TF_SECRET__ACCESS_KEY
      commands:
        - name: AWS_ACCESS_KEY_ID
          value_from: PROD_TF_ACCESS_KEY_ID
        - name: AWS_SECRET_ACCESS_KEY
          value_from: PROD_TF_SECRET_ACCESS_KEY
    plan:
      steps:
        - run: "checkov -d ."
        - init
        - plan
    apply:
      steps:
        - run: "terraform fmt -check -diff -recursive"
          shell: zsh
        - init
        - apply
    workflow_configuration:
      on_pull_request_pushed: ["digger plan"]
      on_pull_request_closed: ["digger unlock"]
      on_commit_to_default: ["digger unlock"]

​
Top-level Configuration

​
telemetry
boolean
default:"true"
Allows collecting anonymised usage and debugging data.
​
auto_merge
boolean
default:"false"
Automatically merge pull requests when all checks pass.
​
auto_merge_strategy
string
default:"squash"
The merge strategy to use while automerging. Possible values: squash, merge (for merge commits), and rebase. Currently only GitHub supported.
​
pr_locks
boolean
default:"true"
Enable PR-level locking to prevent concurrent operations on the same project.
​
delete_prior_comments
boolean
default:"false"
Enables Digger to delete previous comments to reduce noise in the PR.
​
traverse_to_nested_projects
boolean
default:"false"
Enable traversal of nested directories to discover projects.
​
allow_draft_prs
boolean
default:"false"
Allow Digger to run on draft pull requests.
​
apply_after_merge
boolean
default:"false"
Automatically run apply after a pull request is merged.
​
respect_layers
boolean
default:"false"
Respect project layers when determining execution order. See layering for details.
​
disable_digger_apply_comment
boolean
default:"false"
Disable the digger apply comment prompt after successful plan.
​
disable_digger_apply_status_check
boolean
default:"false"
Disable the status check that verifies apply was executed.
​
trusted_appIDs
array
default:"[]"
Allow bot comments from these GitHub user IDs. Example: trusted_appIDs: [41898282] for GitHub Actions.
​
comment_render_mode
string
default:"basic"
How to render plan output in comments. Options: basic, detailed.
​
mention_drifted_projects_in_pr
boolean
default:"false"
Mention projects that have drifted from the target state in PR comments.
​
report_terraform_outputs
boolean
default:"true"
Include Terraform outputs in the PR comment after apply.
​
projects
array
List of projects to manage. See Project Configuration.
​
generate_projects
object
Generate projects from a directory structure. See GenerateProjects Configuration.
​
workflows
map
Workflows and configurations to run on events. See Workflow Configuration.
Configure reporting options using the reporting key.
​
reporting.ai_summary
boolean
default:"false"
Enable AI-generated summaries of plan output. See AI Summaries.
​
reporting.comments_enabled
boolean
default:"true"
Enable posting plan/apply results as PR comments.
Configure dependency handling using the dependency_configuration key.
​
dependency_configuration.mode
string
default:"hard"
Dependency execution mode:
  • hard - Execute dependency projects even if they weren’t changed
  • soft - Skip dependency projects if they weren’t changed

​
Project Configuration

Define individual projects using the projects array.
​
name
string
required
Name of the project. Must be unique across all projects.
​
dir
string
required
Directory containing the Terraform/OpenTofu/Terragrunt code, relative to the repository root.
​
branch
string
The target branch to match this project on. Defaults to the repository’s default branch when not set.
​
alias
string
An alternative name for the project, useful for referencing in commands.
​
apply_requirements
array
default:"[\"mergeable\"]"
List of requirements that must be met before apply can run. Options: approved, mergeable, undiverged. See apply requirements for details.
​
workspace
string
default:"default"
Terraform workspace to use for this project.
​
terragrunt
boolean
default:"false"
Whether to use Terragrunt for this project.
​
opentofu
boolean
default:"false"
Whether to use OpenTofu instead of Terraform.
​
pulumi
boolean
default:"false"
Whether to use Pulumi for this project.
​
pulumi_stack
string
The Pulumi stack to use when pulumi: true.
​
workflow
string
default:"default"
Name of the workflow to use for this project.
​
workflow_file
string
default:"digger_workflow.yml"
Name of the GitHub Actions workflow file for this project.
​
drift_detection
boolean
default:"true"
Enable drift detection for this project. See Drift Detection.
​
layer
number
default:"0"
Layer number for controlling execution order when respect_layers is enabled. Lower layers execute first.
​
include_patterns
array
default:"[]"
List of directory glob patterns to include as dependencies, e.g., ["../modules/**"]. See Include / Exclude Patterns.
​
exclude_patterns
array
default:"[]"
List of directory glob patterns to exclude, e.g., [".terraform/**"]. See Include / Exclude Patterns.
​
depends_on
array
default:"[]"
List of project names that must complete before this project. Does not force terraform run, but affects the order of commands for projects modified in the current PR.
Configure AWS role assumption using the aws_role_to_assume key.
​
aws_role_to_assume.aws_role_region
string
default:"us-east-1"
AWS region used when performing STS web identity calls.
​
aws_role_to_assume.state
string
ARN of the IAM role to assume for state backend operations. If only state is set, it will also be used for commands.
​
aws_role_to_assume.command
string
ARN of the IAM role to assume for Terraform commands (plan/apply). If only command is set, it will also be used for state.
Configure AWS Cognito OIDC authentication using the aws_cognito_oidc key.
​
aws_cognito_oidc.aws_account_id
string
required
The AWS account ID where the Cognito Identity Pool is located.
​
aws_cognito_oidc.aws_region
string
The AWS region for the Cognito Identity Pool.
​
aws_cognito_oidc.cognito_identity_pool_id
string
required
The Cognito Identity Pool ID for federated authentication.
​
aws_cognito_oidc.session_duration
number
Session duration in seconds for the assumed role credentials.

​
GenerateProjects Configuration

Automatically generate projects from directory structure using the generate_projects key.
​
include
string
Glob pattern to include directories for project generation.
​
exclude
string
Glob pattern to exclude directories from project generation.
​
terragrunt
boolean
default:"false"
Whether to use Terragrunt for generated projects.
​
blocks
array
List of blocks for more granular project generation. See Block Configuration.
​
terragrunt_parsing
object
Terragrunt-specific parsing configuration. See Terragrunt Parsing for all options.
​
aws_role_to_assume
object
Default AWS role configuration for all generated projects. See AWS Role Configuration.
​
aws_cognito_oidc
object
Default AWS Cognito OIDC configuration for all generated projects. See AWS Cognito OIDC Configuration.
Blocks allow you to define multiple project generation rules with different settings.
​
block_name
string
Name of the block for identification.
​
include
string
Glob pattern to include directories. Only for Terraform and OpenTofu.
​
exclude
string
Glob pattern to exclude directories. Only for Terraform and OpenTofu.
​
include_patterns
array
default:"[]"
List of directory glob patterns to include as dependencies for generated projects.
​
exclude_patterns
array
default:"[]"
List of directory glob patterns to exclude from generated projects.
​
workflow
string
default:"default"
Workflow to use for projects in this block.
​
workflow_file
string
Name of the GitHub Actions workflow file for projects in this block.
​
workspace
string
Terraform workspace to use for projects in this block.
​
terragrunt
boolean
default:"false"
Whether to use Terragrunt for projects in this block.
​
root_dir
string
Root directory for Terragrunt projects. Only for Terragrunt.
​
opentofu
boolean
default:"false"
Whether to use OpenTofu for projects in this block.
​
terragrunt_parsing
object
Terragrunt-specific parsing configuration for this block. See Terragrunt Parsing.
​
aws_role_to_assume
object
AWS role configuration for projects in this block.
​
aws_cognito_oidc
object
AWS Cognito OIDC configuration for projects in this block.

​
Workflow Configuration

Define custom workflows using the workflows map. Each workflow can have its own environment variables, plan/apply stages, and event configurations.
​
env_vars
object
Environment variables to set per stage. See EnvVars Configuration.
​
plan
object
Plan stage configuration. See Stage Configuration.
​
apply
object
Apply stage configuration. See Stage Configuration.
​
workflow_configuration
object
Describes how to react to CI events. See WorkflowConfiguration.
Configure environment variables for different stages using the env_vars key.
​
env_vars.state
array
default:"[]"
Environment variables to set for terraform init stage. Useful for setting different credentials for remote backend.
​
env_vars.commands
array
default:"[]"
Environment variables to set for other terraform commands. Useful for setting different credentials for managed infrastructure.
Each environment variable object has:
​
name
string
required
Name of the environment variable to set.
​
value
string
Direct value for the environment variable. Takes preference over value_from if both are set.
​
value_from
string
Name of another environment variable to get the value from. Useful for secrets—set a secret from a secret manager (e.g., GitHub secrets) as an environment variable, then remap it to another variable.
Configure plan and apply stages.
​
filter_regex
string
Regular expression to filter which files trigger this stage.
​
steps
array
default:"[]"
List of steps to run during this stage. See Step Configuration.
Steps can be terraform commands or custom shell commands.Terraform commands (init, plan, apply):
steps:
  - init
  - plan
  - apply
With extra arguments:
steps:
  - init:
      extra_args: ["-backend-config=backend.hcl"]
  - plan:
      extra_args: ["-var-file=prod.tfvars"]
  - apply:
      extra_args: ["-compact-warnings"]
Custom shell commands:
steps:
  - run: "echo hello world"
  - run: "checkov -d ."
    shell: zsh
​
init
string | object
Terraform init step. Can be a string init or an object with extra_args.
​
plan
string | object
Terraform plan step. Can be a string plan or an object with extra_args.
​
apply
string | object
Terraform apply step. Can be a string apply or an object with extra_args.
​
run
string
Shell command to run.
​
shell
string
Shell to use for the run command (e.g., bash, zsh).
​
extra_args
array
default:"[]"
Extra arguments to pass to terraform init/plan/apply.
Configure how the workflow responds to CI events.
​
on_pull_request_pushed
array
default:"[\"digger plan\"]"
Commands to run when a pull request is created or updated. Options: digger plan, digger apply, digger lock, digger unlock.
​
on_pull_request_closed
array
default:"[\"digger unlock\"]"
Commands to run when a pull request is closed.
​
on_pull_request_to_draft
array
default:"[]"
Commands to run when a pull request is converted to draft.
​
on_commit_to_default
array
default:"[\"digger unlock\"]"
Commands to run when a commit is pushed to the default branch.
​
skip_merge_check
boolean
default:"false"
Allow this workflow to skip mergeability checks and run digger commands.

​
Default Workflow

A default workflow is created automatically if you don’t specify any workflows in the configuration: 
workflow_configuration:
  on_pull_request_pushed: [digger plan]
  on_pull_request_closed: [digger unlock]
  on_commit_to_default: [digger unlock]
plan:
  steps:
    - init
    - plan
apply:
  steps:
    - init
    - apply

​
Workflow Configuration Explanation

Workflow configuration describes how to react to CI events. It has 4 sections:
  • on_pull_request_pushed - describes what to do when a pull request is created or updated
  • on_pull_request_closed - describes what to do when a pull request is closed
  • on_pull_request_to_draft - describes what to do when a pull request is converted to draft
  • on_commit_to_default - describes what to do when a pull request is merged into the default branch

​
Projects

A project in Digger corresponds to a directory containing Terraform code. Projects are treated as standalone independent entities with their own locks. Digger will not prevent you from running plan and apply in different projects simultaneously. You can run plan / apply in a specified project by using the -p option in a GitHub PR comment: 
digger apply -p my-second-app

​
See Also