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.