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
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

KeyTypeDefaultRequiredDescriptionNotes
telemetrybooleantruenoallows collecting anonymised usage and debugging data
auto_mergebooleanfalsenoautomatically merge pull requests when all checks pass
projectsarray of Projects[]nolist of projects to manage
generate_projectsGenerateProjectsnogenerate projects from a directory structure
workflowsmap of Workflowsnoworkflows and configurations to run on events
traverse_to_nested_projectsbooleanfalsenoenabled traversal of nested directories

Project

KeyTypeDefaultRequiredDescriptionNotes
namestringyesname of the projectmust be unique
dirstringyesdirectory containing the project
workspacestringdefaultnoterraform workspace to use
terragruntbooleanfalsenowhether to use terragrunt
workflowstringdefaultnoworkflow to usedefault workflow will be created for you described in workflow section
include_patternsarray of strings[]nolist of directory glob patterns to include, e.g. ./modulessee Include / Exclude Patterns
exclude_patternsarray of strings[]nolist of directory glob patterns to exclude, e.g. .terraformsee Include / Exclude Patterns
depends_onarray of strings[]nolist of project names that need to be completed before the projectit doesn’t force terraform run, but affects the order of commands for projects modified in the current PR
aws_role_to_assumeRoleToAssumenoA string representing the AWS role to assume for this project

GenerateProjects

KeyTypeDefaultRequiredDescriptionNotes
includestringnoglob pattern to include directories
excludestringnoglob pattern to exclude directories

Workflows

KeyTypeDefaultRequiredDescriptionNotes
env_varsEnvVarsnoenvironment variables to set for per stage
planPlannoplan stage configuration
applyApplynoapply stage configuration
workflow_configurationWorkflowConfigurationnodescribes how to react to CI events

EnvVars

KeyTypeDefaultRequiredDescriptionNotes
statearray of EnvVar[]noenvironment variables to set for terraform init stagecan be use to set different credentials for remote backend for example
commandsarray of EnvVar[]noenvironment variables to set for other terraform commandscan be use to set different credentials for actual managed infrastructure

EnvVar

KeyTypeDefaultRequiredDescriptionNotes
namestringyesname of the environment variable
value_fromstringyesname of the other environment variable to get the value fromthis 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
valuestringyesvalue of the environment variablethis value will have a preference over value_from field if both are set

RoleToAssume

KeyTypeDefaultRequiredDescriptionNotes
aws_role_regionstringnoRegions used when performing sts web identity callsThis will default to “us-east-1” if not set
statestringyesARN of the role to assume for state backendYou can optionally set role and the same role
commandstringyesARN of the role to assume for commands e.g. plan / applywill be used for both.

Plan

KeyTypeDefaultRequiredDescriptionNotes
stepsarray of Step[]nolist of steps to run during plan stage

Apply

KeyTypeDefaultRequiredDescriptionNotes
stepsarray of Step[]nolist of steps to run during apply stage

WorkflowConfiguration

KeyTypeDefaultRequiredDescriptionNotes
on_pull_request_pushedarray of enums[digger plan, digger apply, digger lock, digger unlock][]nolist of stages to run when pull request is pushed
on_pull_request_closedarray of enums[digger plan, digger apply, digger lock, digger unlock][]nolist of stages to run when pull request is closed
on_commit_to_defaultarray of enums[digger plan, digger apply, digger lock, digger unlock][]nolist of stages to run when commit is pushed to default branch

Step

KeyTypeDefaultRequiredDescriptionNotes
initInit/string/""noterraform init stepif missing from array of steps, it will be skipped
planPlan/string/""noterraform plan stepif missing from array of steps, it will be skipped
applyApply/string/""noterraform apply stepif missing from array of steps, it will be skipped
runRun/string/""noshell command to runif missing from array of steps, it will be skipped

Init/Apply/Plan as object

KeyTypeDefaultRequiredDescriptionNotes
extra_argsarray of strings[]noextra arguments to pass to terraform init/plan/apply

Run as object

KeyTypeDefaultRequiredDescriptionNotes
shellstringyesshell to use to run the commandzsh/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