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

Automerge can be used to automatically merge the pull request after all directories have been successful applied.

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
create_and_select_workspace	Boolean	Select and create the workspace defined in the workspaces configuration. Default is true.
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.

workspaces

The workspaces configuration is an object where the object key is the name of the Workspace and the value is its configuration.

Unique custom tags can be created against a directory and workspace combination.

dirs:
  dir1:
    workspaces:
      development:
        tags: ['dev']
      production:
        tags: ['prod']

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	Provider	Description
oidc	List		Initiate an OIDC connection to a cloud provider.
provider	String		Name of provider: aws or gcp.
role_arn	String	aws	Specifies the ARN of an IAM role that you want to use. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
assume_role_arn	String	aws	Specifies the ARN of an IAM role that you want to assume into. Default is the value of role_arn. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
assume_role_enabled	Boolean	aws	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	aws	Specifies the AWS audience name to use. Default is sts.amazonaws.com. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
region	String	aws	Specifies the AWS region to use and sets the AWS_REGION environment variable. Default is us-east-1.
session_name	String	aws	Specifies the AWS session name. Default is terrateam.
duration	Integer	aws	Specifies the AWS session duration in seconds. Default is 3600.
service_account	String	gcp	Email address or unique identifier of the Google Cloud service account for which to generate credentials. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
workload_identity_provider	String	gcp	The full identifier of the Workload Identity Provider, including the project number, pool name, and provider name. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
access_token_lifetime	Integer	gcp	Desired lifetime duration of the access token, in seconds. Default is 3600.
audience	String	gcp	Specifies the GCP audience name to use. Default is https://iam.googleapis.com/ + workload_identity_provider.
access_token_subject	String	gcp	Email address of a user to impersonate for Domain-Wide Delegation. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.

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. Prefix with ! to exclude a file glob. 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.
lock_policy	String	Override how Terrateam acquires a lock. See workflows.

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.