Skip to content

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.

KeyTypeDescription
enabledBooleanEnabling the access control feature. Default is true.
apply_require_all_dirspace_accessBooleanIf true then user must have permission to all targeted Dirspaces to trigger an Apply operation. Default is true.
plan_require_all_dirspace_accessBooleanIf true then user must have permission to all targeted Dirspaces to trigger a Plan operation. Default is false.
terrateam_config_updateListRuleset 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 ['*'].
unlockListRuleset for which users can trigger an Unlock operation on a pull request. Default is ['*'].
policiespoliciesAccess 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:

KeyTypeDescription
applyListRuleset for which users can trigger an Apply operation. This includes when_modified Autoapply. Default is ['repo:maintain'].
apply_autoapproveListRuleset for which users can trigger an Apply Auto Approve operation. Default is [].
apply_forceListRuleset for which users can trigger an Apply Force operation. Default is [].
apply_with_superapprovalListAllows a user to trigger an Apply operation if a user matching the superapproval list has approved the pull request. Default is [].
superapprovalListDefine a list of users whose approvals are super approvals. Default is [].
planListRuleset 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.

KeyTypeDescription
checkschecksConfiguration for the apply requirement checks.
create_pending_apply_checkBooleanCreate 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.

KeyTypeDescription
enabledBooleanSpecified whether automerge is enabled. Default is false.
delete_branchBooleanDelete the source branch after a successful Apply and git merge. Default is false.

Default configuration:

automerge:
  enabled: false
  delete_branch: false

checkout_strategy

KeyTypeDescription
checkout_strategyStringHow 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.

KeyTypeDescription
enabledBooleanSpecified whether cost estimation is enabled. Default is true.
providerStringCost estimation provider. Default is infracost.
currencyStringA 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.

KeyTypeDescription
default_tf_versionStringGlobal 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.

KeyTypeDescription
branchStringThe branch that a pull request can be merged into.
source_branchesListThe 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.

KeyTypeDescription
<directory_name>directory_nameDirs 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:

KeyTypeDescription
create_and_select_workspaceBooleanSelect and create the workspace defined in the workspaces configuration. Default is true.
tagsListList of tags to assign the directory.
workspacesWorkspacesWorkspace configuration.
when_modifiedWhen ModifiedConfiguration 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.

KeyTypeDescription
enabledBooleanSpecified 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.

KeyTypeDescription
enabledBooleanSpecified whether drift detection is enabled. If set to false, drift detection and reconciliation will not run. Default is false.
scheduleStringThe interval to run drift detection and reconciliation: hourly, daily, weekly, monthly
reconcileBooleanSpecified 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.

KeyTypeDescription
allallPre and post hook configuration to run around all operations.
planplanPre and post hook configuration for Plan operations.
applyapplyPre 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

KeyTypeDescription
prepreCommands to run before any hooks.
postpostCommands to run after any hooks.

The following types can be defined under pre and post:

env

KeyTypeDescription
nameStringName of environment variable.
cmdListCommand to use to set environment variable.
trim_trailing_newlinesBooleanTrim trailing newlines. Default is true.

run

KeyTypeDescription
cmdListCommand to run from the directory that Terrateam is operating against.
run_onStringRun the command on step success, failure, or always. Default is success.
capture_outputBooleanWhen 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

KeyTypeProviderDescription
oidcListInitiate an OIDC connection to a cloud provider.
providerStringName of provider: aws or gcp.
role_arnStringawsSpecifies 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_arnStringawsSpecifies 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_enabledBooleanawsRetrieve 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.
audienceStringawsSpecifies the AWS audience name to use. Default is sts.amazonaws.com. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
regionStringawsSpecifies the AWS region to use and sets the AWS_REGION environment variable. Default is us-east-1.
session_nameStringawsSpecifies the AWS session name. Default is terrateam.
durationIntegerawsSpecifies the AWS session duration in seconds. Default is 3600.
service_accountStringgcpEmail 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_providerStringgcpThe 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_lifetimeIntegergcpDesired lifetime duration of the access token, in seconds. Default is 3600.
audienceStringgcpSpecifies the GCP audience name to use. Default is https://iam.googleapis.com/ + workload_identity_provider.
access_token_subjectStringgcpEmail 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.

KeyTypeDescription
typeStringPre-hook type: env, run, oidc.

post

Commands to run after any hooks.

KeyTypeDescription
typeStringPost-hook type: env, run, oidc.

plan

KeyTypeDescription
prepreCommands to run before a plan workflow.
postpostCommands to run after a plan workflow.

pre

Commands to run before a plan workflow.

KeyTypeDescription
typeStringPre-hook type: env, run, oidc.

post

Commands to run after a plan workflow.

KeyTypeDescription
typeStringPost-hook type: env, run, oidc.

apply

KeyTypeDescription
prepreCommands to run before an apply workflow.
postpostCommands to run after an apply workflow.

pre

Commands to run before an apply workflow.

KeyTypeDescription
typeStringPre-hook type: env, run, oidc.

post

Commands to run after an apply workflow.

KeyTypeDescription
typeStringPost-hook type: env, run, oidc.

parallel_runs

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

KeyTypeDescription
parallel_runsIntegerNumber 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.

KeyTypeDescription
versionStringConfiguration 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.

KeyTypeDescription
file_patternsListList 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"].
autoplanBooleanAutomatically run a Plan operation on a new pull request or an update on an existing one. Default is true.
autoplan_draft_prBooleanAutomatically run a Plan operation on a new draft pull request or an update on an existing one. Default is true.
autoapplyBooleanAutomatically 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

KeyTypeDescription
approvedapprovedConfiguration for pull request approval.
merge_conflictsmerge_conflictsConfiguration for merge conflicts.
status_checksstatus_checksConfiguration for status checks.

approved

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

KeyTypeDescription
enabledBooleanIf the check is enabled. Default is false.
countIntegerNumber of approvals needed to pass. Default is 1.

merge_conflicts

Requires that the pull request has no merge conflicts.

KeyTypeDescription
enabledBooleanIf the check is enabled. Default is true.

status_checks

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

KeyTypeDescription
enabledBooleanIf the check is enabled. Default is true.
ignore_matchingListList of regex to match against names of checks to ignore. Default is [].

create_pending_apply_check

KeyTypeDescription
create_pending_apply_checkBooleanCreate 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.

KeyTypeDescription
tag_querytag_queryWorkflow 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:

KeyTypeDescription
planplanPlan steps.
applyapplyApply steps.
terragruntBooleanOverride the terraform command with terragrunt. Default is false.
terraform_versionBooleanOverride the Terraform version specified in default_tf_version.
lock_policyStringOverride how Terrateam acquires a lock. See workflows.

The following types can be defined under workflows:

init

KeyTypeDescription
initListRun terraform init.
extra_argsListExtra command line arguments passed to the terraform command.

plan

KeyTypeDescription
planListRun terraform plan.
extra_argsListExtra command line arguments passed to the terraform command.

apply

KeyTypeDescription
applyListRun terraform apply.

env

KeyTypeDescription
nameStringName of environment variable.
cmdListCommand to use to set environment variable.
trim_trailing_newlinesBooleanTrim trailing newlines. Default is true.

run

KeyTypeDescription
cmdListCommand to run from the directory that Terrateam is operating against.
run_onStringRun the command on step success, failure, or always. Default is success.
capture_outputBooleanWhen 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

KeyTypeDescription
oidcListInitiate an OIDC connection to a cloud provider.
providerStringName of provider: aws.
role_arnStringSpecifies the ARN of an IAM role that you want to use.
assume_role_arnStringSpecifies the ARN of an IAM role that you want to assume into. Default is the value of role_arn.
assume_role_enabledBooleanRetrieve 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.
audienceStringSpecifies the AWS audience name to use. Default is sts.amazonaws.com.
regionStringSpecifies the AWS region to use and sets the AWS_REGION environment variable. Default is us-east-1.
session_nameStringSpecifies the AWS session name. Default is terrateam.
durationIntegerSpecifies the AWS session duration in seconds. Default is 3600.

plan

Plan steps.

KeyTypeDescription
typeStringTerrateam step type: init, plan, env, run, oidc.

apply

Apply steps.

KeyTypeDescription
typeStringTerrateam step type: init, apply, env, run, oidc.

Need help?

See our Support page for assistance.