• Docs
  • Configuration
  • Reference

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.

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

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

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:

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

hooks

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

KeyTypeDescription
planplanPre and post hook configuration for Plan operations.
applyapplyPre and post hook configuration for Apply operations.

Default configuration:

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

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

post

Commands to run after a plan workflow.

KeyTypeDescription
typeStringPost-hook type: env, run.
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.

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

post

Commands to run after an apply workflow.

KeyTypeDescription
typeStringPost-hook type: env, run.
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.

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. 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: ""
    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.

plan

Plan steps.

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

Extra command line arguments passed to the terraform command.

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.
envObjectEnvironment variables to set for this execution. Object keys are environment variable names and the value is a string.

apply

Apply steps.

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

Extra command line arguments passed to the terraform command.

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.

<directory_name>

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

The value map has the following attributes:

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

when_modified

Identical to the When Modified configuration. Overrides global When Modified configuration.

tags

KeyTypeDescription
tagsListList of tags to assign the directory.

workspaces

Workspace for the directory. Tags can be specified for the workspace.

<workspace_name>

Each workspace consists of the workspace name as a key and a map as a value.

The value map has the following attributes:

KeyTypeDescription
tagsListList of tags to assign the workspace.

Need help?

See our Support page for assistance.