digger.yml

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

Note: you can also name your Digger configuration file differently, and specify its name using the digger-filename input at GitHub Action level.

---

Example using all keys

traverse_to_nested_projects: true
auto_merge: false
pr_locks: true
projects:
  - name: prod
    dir: prod
    apply_requirements: [approved, mergeable, undiverged]
    branch: main
    workspace: default
    terragrunt: false
    workflow: prod
    include_patterns: ["../modules/**"]
    exclude_patterns: []
  - name: staging
    dir: staging
    branch: main
    workflow: staging
    include_patterns: ["../modules/**"]
    exclude_patterns: []    
generate_projects:
  include: "../projects/**"
  exclude: "../.terraform/**"
workflows:
  staging:
    env_vars:
      state:
        - name: TF_LOG
          value: trace
      commands:
        - name: TF_LOG
          value: trace
    plan:
      steps:
        - init:
          extra_args: ["backend-config=../backend.hcl"]
        - run: "echo hello world"
        - plan
    apply:
      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_commit_to_default: ["digger apply"]
  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"]

Reference

Top-level

Key	Type	Default	Required	Description	Notes
telemetry	boolean	true	no	allows collecting anonymised usage and debugging data
auto_merge	boolean	false	no	automatically merge pull requests when all checks pass
auto_merge_strategy	string	”squash”	no	The merge strategy to use while automerging, defaults to “squash”. Possible values: ‘squash’, ‘merge’ (for merge commits) and ‘rebase’	currently only github supported for this flag
pr_locks	boolean	true	no	Enable PR-level locking
delete_prior_comments	boolean	false	no	Enables digger to delete previous comments to reduce noise in the PR
projects	array of Projects	[]	no	list of projects to manage
generate_projects	GenerateProjects	no	generate projects from a directory structure
workflows	map of Workflows	no	workflows and configurations to run on events
traverse_to_nested_projects	boolean	false	no	enabled traversal of nested directories

Project

Key	Type	Default	Required	Description	Notes
name	string		yes	name of the project	must be unique
branch	string		yes	the target branch to match this project on	This field is optional and defaults to the repository’s default branch when not set
dir	string		yes	directory containing the project
apply_requirements	[]string	[mergeable]	no	list of requirements to be met before merged	see apply requirements for details
workspace	string	default	no	terraform workspace to use
opentofu	boolean	false	no	whether to use opentofu
terragrunt	boolean	false	no	whether to use terragrunt
workflow	string	default	no	workflow to use	default workflow will be created for you described in workflow section
include_patterns	array of strings	[]	no	list of directory glob patterns to include, e.g. ./modules	see Include / Exclude Patterns
exclude_patterns	array of strings	[]	no	list of directory glob patterns to exclude, e.g. .terraform	see Include / Exclude Patterns
depends_on	array of strings	[]	no	list of project names that need to be completed before the project	it doesn’t force terraform run, but affects the order of commands for projects modified in the current PR
aws_role_to_assume	RoleToAssume		no	A string representing the AWS role to assume for this project

GenerateProjects

Key	Type	Default	Required	Description	Notes
include	string		no	glob pattern to include directories
exclude	string		no	glob pattern to exclude directories
blocks	array of Block	[]	no	list of blocks to generate projects

Block

Key	Type	Default	Required	Description	Notes
block_name	string		no	name of the block
workflow	string	default	no	workflow to use	default workflow will be created for you described in workflow section
workflow_file	string		no	name of workflow file for GitHub Actions
aws_role_to_assume	RoleToAssume		no	A string representing the AWS role to assume for this project
include	string		no	glob pattern to include directories	only for terraform and opentofu
exclude	string		no	glob pattern to exclude directories	only for terraform and opentofu
opentofu	boolean	false	no	whether to use opentofu	only for opentofu
terragrunt	boolean	false	no	whether to use terragrunt	only for terragrunt
root_dir	string		no	root directory of terragrunt projects	only for terragrunt

Workflows

Key	Type	Default	Required	Description	Notes
env_vars	EnvVars	no	environment variables to set for per stage
plan	Plan	no	plan stage configuration
apply	Apply	no	apply stage configuration
workflow_configuration	WorkflowConfiguration	no	describes how to react to CI events

EnvVars

Key	Type	Default	Required	Description	Notes
state	array of EnvVar	[]	no	environment variables to set for terraform init stage	can be use to set different credentials for remote backend for example
commands	array of EnvVar	[]	no	environment variables to set for other terraform commands	can be use to set different credentials for actual managed infrastructure

EnvVar

Key	Type	Default	Required	Description	Notes
name	string		yes	name of the environment variable
value_from	string		yes	name of the other environment variable to get the value from	this can be used for secrets. For example you set a secret from some secret manager (e.g. github secrets) as environment variable and the remap it to another variable. E.g. setting DEV_TF_ACCESS_KEY as a secret in github action, but then remap it into AWS_ACCESS_KEY during terraform apply command execution
value	string		yes	value of the environment variable	this value will have a preference over value_from field if both are set

RoleToAssume

Key	Type	Default	Required	Description	Notes
aws_role_region	string		no	Regions used when performing sts web identity calls	This will default to “us-east-1” if not set
state	string		yes	ARN of the role to assume for state backend	You can optionally set role and the same role
command	string		yes	ARN of the role to assume for commands e.g. plan / apply	will be used for both.

Plan

Key	Type	Default	Required	Description	Notes
steps	array of Step	[]	no	list of steps to run during plan stage

Apply

Key	Type	Default	Required	Description	Notes
steps	array of Step	[]	no	list of steps to run during apply stage

WorkflowConfiguration

Key	Type	Default	Required	Description	Notes
on_pull_request_pushed	array of enums[digger plan, digger apply, digger lock, digger unlock]	[]	no	list of stages to run when pull request is pushed
on_pull_request_closed	array of enums[digger plan, digger apply, digger lock, digger unlock]	[]	no	list of stages to run when pull request is closed
on_commit_to_default	array of enums[digger plan, digger apply, digger lock, digger unlock]	[]	no	list of stages to run when commit is pushed to default branch
skip_merge_check	boolean	false	no	Allow a workflow to skip mergeability checks and run digger commands

Step

Key	Type	Default	Required	Description	Notes
init	Init/string	{} OR ""	no	terraform init step	if missing from array of steps, it will be skipped
plan	Plan/string	{} OR ""	no	terraform plan step	if missing from array of steps, it will be skipped
apply	Apply/string	{} OR ""	no	terraform apply step	if missing from array of steps, it will be skipped
run	Run/string	{} OR ""	no	shell command to run	if missing from array of steps, it will be skipped

Init/Apply/Plan as object

Key	Type	Default	Required	Description	Notes
extra_args	array of strings	[]	no	extra arguments to pass to terraform init/plan/apply

Run as object

Key	Type	Default	Required	Description	Notes
shell	string		yes	shell to use to run the command	zsh/bash etc.

Default workflow

Default workflow will be created for you if you don’t specify any workflows in the configuration. It will have the following configuration:

workflow_configuration:
  on_pull_request_pushed: [digger plan]
  on_pull_request_closed: [digger unlock]
  on_commit_to_default: [digger unlock]

Workflow configuration explanation

Workflow configuration describes how to react to CI events. It has 3 sections:

• on_pull_request_pushed - describes what to do when pull request is created or updated

• on_pull_request_closed - describes what to do when pull request is closed

• on_commit_to_default - describes what to do when pull request is merged into 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 Github PR comment:

digger apply -p my-second-app