Terrateam Configuration Reference

This document is a reference for the Terrateam configuration keys that are used in the .terrateam/config.yml file.

See a complete config.yml in our full example.

`access_control`

The access_control directive can be used to provide a capabilities-based security configuration for Terrateam operations.

Key	Type	Description
enabled	Boolean	Enabling the access control feature. Default is `true`.
apply_require_all_dirspace_access	Boolean	If `true` then user must have permission to all targeted Dirspaces to trigger an Apply operation. Default is `true`.
plan_require_all_dirspace_access	Boolean	If `true` then user must have permission to all targeted Dirspaces to trigger a Plan operation. Default is `false`.
terrateam_config_update	List	Ruleset for which users can trigger a Terrateam operation on a pull request with a Terrateam configuration file change as part of the changeset. Default is `['*']`.
unlock	List	Ruleset for which users can trigger an Unlock operation on a pull request. Default is `['*']`.
policies	policies	Access Control policies.

Default configuration:

access_control:
  enabled: true
  apply_require_all_dirspace_access: true
  plan_require_all_dirspace_access: false
  terrateam_config_update: ['*']
  unlock: ['*']
  policies:
    - tag_query: ''
      apply: ['*']
      apply_autoapprove: []
      apply_force: []
      apply_with_superapproval: []
      plan: ['*']
      superapproval: []

`policies`

`tag_query`

A list of all tags that must be present in a tag set in order to match the policy. See Tags documentation for Tag Query details.

Each tag_query consists of a map as a value.

The value map has the following attributes:

Key	Type	Description
apply	List	Ruleset for which users can trigger an Apply operation. This includes `when_modified` Autoapply. Default is `['repo:maintain']`.
apply_autoapprove	List	Ruleset for which users can trigger an Apply Auto Approve operation. Default is `[]`.
apply_force	List	Ruleset for which users can trigger an Apply Force operation. Default is `[]`.
apply_with_superapproval	List	Allows a user to trigger an Apply operation if a user matching the `superapproval` list has approved the pull request. Default is `[]`.
superapproval	List	Define a list of users whose approvals are super approvals. Default is `[]`.
plan	List	Ruleset for which users can trigger a Plan operation. Default is `['*']`.

`apply_requirements`

The apply_requirements directive allows for the specification of when an Apply operation can be performed on a pull request that has not been merged. See Apply Requirements documentation for details.

Key	Type	Description
checks	checks	Configuration for the apply requirement checks.
create_pending_apply_check	Boolean	Create status checks for pending applies. Default is `true`.

Default configuration:

apply_requirements:
    checks:
        approved:
            enabled: false
            count: 1
        merge_conflicts:
            enabled: true
        status_checks:
            enabled: true
            ignore_matching: []
    create_pending_apply_check: true

`automerge`

The automerge directive can be used to automatically merge the pull request after a successful Apply.

Key	Type	Description
enabled	Boolean	Specified whether automerge is enabled. Default is `false`.
delete_branch	Boolean	Delete the source branch after a successful Apply and git merge. Default is `false`.

Default configuration:

automerge:
  enabled: false
  delete_branch: false

`checkout_strategy`

Key	Type	Description
checkout_strategy	String	How Terrateam performs a code checkout from the pull request. Default is `merge`.

Default configuration:

checkout_strategy: merge

`cost_estimation`

The cost_estimation directive can be used to automatically provide cost estimates for pull requests. See Cost Estimation documentation for details.

Key	Type	Description
enabled	Boolean	Specified whether cost estimation is enabled. Default is `true`.
provider	String	Cost estimation provider. Default is `infracost`.
currency	String	A ISO 4217 currency to report results. Default is `USD`.

Default configuration:

cost_estimation:
  enabled: true
  provider: infracost
  currency: USD

`default_tf_version`

The default_tf_version directive specifies the global version of the Terraform CLI.

Key	Type	Description
default_tf_version	String	Global `terraform` version. Default is `latest`.

Default configuration:

default_tf_version: latest

`destination_branches`

The destination_branches directive specifies a list of valid destination branches with an optional list of source branches. See Destination Branches documentation for details.

Key	Type	Description
branch	String	The branch that a pull request can be merged into.
source_branches	List	The branch name that can be merged.

Default configuration:

destination_branches:

`dirs`

The dirs directive is a way to describe which Tags, Workspaces, and When Modified rules apply to a directory. See Directories and Globs documentation for details.

Key	Type	Description
`<directory_name>`	directory_name	Dirs configuration for a directory.

Default configuration:

dirs:

`<directory_name>`

Each directory consists of the directory's name as a key and a map as a value.

For example, the directory foobar would have the following configuration:

dirs
  foobar:

The value map has the following attributes:

Key	Type	Description
tags	List	List of tags to assign the directory.
workspaces	Workspaces	Workspace configuration.
when_modified	When Modified	Configuration to override when to match pull request file changes with Autoplan and Autoapply.

`enabled`

The enabled directive can be used to enable or disable a repository.

Key	Type	Description
enabled	Boolean	Specified whether the repository is enabled. If set to `false`, all events from this repository will be ignored. Default is `true`.

Default configuration:

enabled: true

`drift`

The drift directive can be used to enable or disable drift detection and reconciliation. See Drift documentation for details.

Key	Type	Description
enabled	Boolean	Specified whether drift detection is enabled. If set to `false`, drift detection and reconciliation will not run. Default is `false`.
schedule	String	The interval to run drift detection and reconciliation: `hourly`, `daily`, `weekly`, `monthly`
reconcile	Boolean	Specified whether reconciliation is enabled. Default is `false`.

Default configuration:

drift:
  enabled: false
  reconcile: false

`hooks`

The hooks directive can be used to run commands or set environment variables pre and post Workflows. See Hooks documentation for details.

Key	Type	Description
all	all	Pre and post hook configuration to run around all operations.
plan	plan	Pre and post hook configuration for Plan operations.
apply	apply	Pre and post hook configuration for Apply operations.

Default configuration:

hooks:
  all:
    pre: []
    post: []
  plan:
    pre: []
    post: []
  apply:
    pre: []
    post: []

`all`

Wrap execution of a plan or apply in the pre and post commands.

The order of operations for a plan operation:

hooks.all.pre -> hooks.plan.pre -> workflows.plan -> hooks.plan.post -> hooks.all.post

And for an apply:

hooks.all.pre -> hooks.apply.pre -> workflows.apply -> hooks.apply.post -> hooks.all.post

Key	Type	Description
pre	pre	Commands to run before any hooks.
post	post	Commands to run after any hooks.

The following types can be defined under pre and post:

env

Key	Type	Description
name	String	Name of environment variable.
cmd	List	Command to use to set environment variable.
trim_trailing_newlines	Boolean	Trim trailing newlines. Default is `true`.

run

Key	Type	Description
cmd	List	Command to run from the directory that Terrateam is operating against.
run_on	String	Run the command on step `success`, `failure`, or `always`. Default is `success`.
capture_output	Boolean	When `capture_output` is set to `true`, command output is included in the GitHub pull request comment on a failure. Sensitive data is not masked. Be aware, this data is sent back to the Terrateam backend for processing. Default is `false`.

oidc

Key	Type	Description
oidc	List	Initiate an OIDC connection to a cloud provider.
provider	String	Name of provider: `aws`.
role_arn	String	Specifies the ARN of an IAM role that you want to use.
assume_role_arn	String	Specifies the ARN of an IAM role that you want to assume into. Default is the value of `role_arn`.
assume_role_enabled	Boolean	Retrieve a set of temporary security credentials from AWS and set the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables. Default is `true`.
audience	String	Specifies the AWS audience name to use. Default is `sts.amazonaws.com`.
region	String	Specifies the AWS region to use and sets the `AWS_REGION` environment variable. Default is `us-east-1`.
session_name	String	Specifies the AWS session name. Default is `terrateam`.
duration	Integer	Specifies the AWS session duration in seconds. Default is `3600`.

`pre`

Commands to run before any hooks.

Key	Type	Description
type	String	Pre-hook type: `env`, `run`, `oidc`.

`post`

Commands to run after any hooks.

Key	Type	Description
type	String	Post-hook type: `env`, `run`, `oidc`.

`plan`

Key	Type	Description
pre	pre	Commands to run before a plan workflow.
post	post	Commands to run after a plan workflow.

`pre`

Commands to run before a plan workflow.

Key	Type	Description
type	String	Pre-hook type: `env`, `run`, `oidc`.

`post`

Commands to run after a plan workflow.

Key	Type	Description
type	String	Post-hook type: `env`, `run`, `oidc`.

`apply`

Key	Type	Description
pre	pre	Commands to run before an apply workflow.
post	post	Commands to run after an apply workflow.

`pre`

Commands to run before an apply workflow.

Key	Type	Description
type	String	Pre-hook type: `env`, `run`, `oidc`.

`post`

Commands to run after an apply workflow.

Key	Type	Description
type	String	Post-hook type: `env`, `run`, `oidc`.

`parallel_runs`

The parallel_runs directive specifies the number of terraform executions that can run at the same time.

Key	Type	Description
parallel_runs	Integer	Number of `terraform` executions that can run at the same time. Default is `3`.

Default configuration:

parallel_runs: 3

`version`

The version directive specifies the version of the Terrateam configuration file.

Key	Type	Description
version	String	Configuration file version number. Default is `1`.

Default configuration:

version: "1"

`when_modified`

The when_modified directive can be used to match pull request file changes with Autoplan and Autoapply.

Key	Type	Description
file_patterns	List	List of file globs to identify changes in a directory. Always relative to the root of the repository. Default is `["*/.tf", "*/.tfvars"]`.
autoplan	Boolean	Automatically run a Plan operation on a new pull request or an update on an existing one. Default is `true`.
autoplan_draft_pr	Boolean	Automatically run a Plan operation on a new draft pull request or an update on an existing one. Default is `true`.
autoapply	Boolean	Automatically run an Apply operation after merging a pull request. Default is `false`.

Default configuration:

when_modified:
  file_patterns: ["**/*.tf", "**/*.tfvars"]
  autoplan: true
  autoplan_draft_pr: true
  autoapply: false

`checks`

Key	Type	Description
approved	approved	Configuration for pull request approval.
merge_conflicts	merge_conflicts	Configuration for merge conflicts.
status_checks	status_checks	Configuration for status checks.

`approved`

Requires that the pull request has received a certain number of approvals.

Key	Type	Description
enabled	Boolean	If the check is enabled. Default is `false`.
count	Integer	Number of approvals needed to pass. Default is `1`.

`merge_conflicts`

Requires that the pull request has no merge conflicts.

Key	Type	Description
enabled	Boolean	If the check is enabled. Default is `true`.

`status_checks`

Requires that all status checks associated with the pull request have passed.

Key	Type	Description
enabled	Boolean	If the check is enabled. Default is `true`.
ignore_matching	List	List of regex to match against names of checks to ignore. Default is `[]`.

`create_pending_apply_check`

Key	Type	Description
create_pending_apply_check	Boolean	Create status checks for pending applies. Default is `true`.

`workflows`

The Workflows directive can be used to replace the default workflow steps Terrateam executes during an operation. See Workflows documentation for details.

Key	Type	Description
tag_query	tag_query	Workflow configuration for a Tag Query.

Default configuration:

workflows:
  - tag_query: ""
    terragrunt: false
    terraform_version: latest
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply

`tag_query`

A list of all tags that must be present in a tag set in order to match the workflow. See Tags documentation for Tag Query details.

Each tag_query consists of a map as a value.

The value map has the following attributes:

Key	Type	Description
plan	plan	Plan steps.
apply	apply	Apply steps.
terragrunt	Boolean	Override the `terraform` command with `terragrunt`. Default is `false`.
terraform_version	Boolean	Override the Terraform version specified in default_tf_version.

The following types can be defined under workflows:

init

Key	Type	Description
init	List	Run `terraform init`.
extra_args	List	Extra command line arguments passed to the `terraform` command.

plan

Key	Type	Description
plan	List	Run `terraform plan`.
extra_args	List	Extra command line arguments passed to the `terraform` command.

apply

Key	Type	Description
apply	List	Run `terraform apply`.

env

Key	Type	Description
name	String	Name of environment variable.
cmd	List	Command to use to set environment variable.
trim_trailing_newlines	Boolean	Trim trailing newlines. Default is `true`.

run

Key	Type	Description
cmd	List	Command to run from the directory that Terrateam is operating against.
run_on	String	Run the command on step `success`, `failure`, or `always`. Default is `success`.
capture_output	Boolean	When `capture_output` is set to `true`, command output is included in the GitHub pull request comment on a failure. Sensitive data is not masked. Be aware, this data is sent back to the Terrateam backend for processing. Default is `false`.

oidc

Key	Type	Description
oidc	List	Initiate an OIDC connection to a cloud provider.
provider	String	Name of provider: `aws`.
role_arn	String	Specifies the ARN of an IAM role that you want to use.
assume_role_arn	String	Specifies the ARN of an IAM role that you want to assume into. Default is the value of `role_arn`.
assume_role_enabled	Boolean	Retrieve a set of temporary security credentials from AWS and set the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables. Default is `true`.
audience	String	Specifies the AWS audience name to use. Default is `sts.amazonaws.com`.
region	String	Specifies the AWS region to use and sets the `AWS_REGION` environment variable. Default is `us-east-1`.
session_name	String	Specifies the AWS session name. Default is `terrateam`.
duration	Integer	Specifies the AWS session duration in seconds. Default is `3600`.

`plan`

Plan steps.

Key	Type	Description
type	String	Terrateam step type: `init`, `plan`, `env`, `run`, `oidc`.

`apply`

Apply steps.

Key	Type	Description
type	String	Terrateam step type: `init`, `apply`, `env`, `run`, `oidc`.

Need help?

See our Support page for assistance.

Full Example FAQ