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

auto_merge: false
projects:
- name: prod
  dir: prod
  workspace: default
  terragrunt: false
  workflow: prod
  include_patterns: ["../modules/**"]
  exclude_patterns: []
- name: staging
  dir: staging
  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
collect_usage_data	boolean	true	no	allows collecting anonymised usage and debugging data	This flag is only supported in Digger enterprise
auto_merge	boolean	false	no	automatically merge pull requests when all checks pass
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

Project

Key	Type	Default	Required	Description	Notes
name	string		yes	name of the project	must be unique
dir	string		yes	directory containing the project
workspace	string	default	no	terraform workspace to use
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

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
state	string		yes	ARN of the role to assume for state backend
command	string		yes	ARN of the role to assume for commands e.g. plan / apply

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

Step

Key	Type	Default	Required	Description	Notes
init	Init/string	/""	no	terraform init step	if missing from array of steps, it will be skipped
plan	Plan/string	/""	no	terraform plan step	if missing from array of steps, it will be skipped
apply	Apply/string	/""	no	terraform apply step	if missing from array of steps, it will be skipped
run	Run/string	/""	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