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
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 |
|---|
| telemetry | boolean | true | no | allows collecting anonymised usage and debugging data | |
| auto_merge | boolean | false | no | automatically merge pull requests when all checks pass | |
| pr_locks | boolean | true | no | Enable PR-level locking | |
| 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 |
| dir | string | | yes | directory containing the project | |
| 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
