workflows

The workflows configuration allows you to customize the steps executed during a Terraform operation, replacing the default workflow. This feature enables you to tailor the behavior of Terrateam to better suit your specific use case and requirements.

Default Configuration

workflows:
  - tag_query: ""
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply

Keys

workflows is a list of workflow entries. The first entry whose tag_query matches a directory and workspace is used. Each entry has the following keys:

Key	Type	Description
tag_query	String	A tag query that must match the tag set of a directory and workspace for this workflow to apply. Required. An empty string matches everything.
plan	List	plan steps. Default is init followed by plan.
apply	List	apply steps. Default is init followed by apply.
engine	Engine	Configuration to override which engine to use for operations.
environment	String	GitHub environment to use for the operation. Not set by default.
runs_on	Object	Object describing the runs-on configuration. Default is ubuntu-latest.
lock_policy	String	When the directory should have a lock acquired. Values are strict (acquire a lock if either it is merged or applied), apply (only acquire a lock when it is applied), merge (only acquire a lock when it is merged), and none (never acquire a lock). Defaults to the top-level lock_policy, which itself defaults to strict.
storage	Storage	Plan storage configuration for this workflow. Defaults to the top-level storage configuration.
terragrunt	Boolean	Legacy. true is equivalent to engine: { name: terragrunt }. Default is false. Prefer engine.
cdktf	Boolean	Legacy. true is equivalent to engine: { name: cdktf }. Default is false. Prefer engine.
terraform_version	String	Legacy. Equivalent to engine: { name: terraform, version: <value> }. Prefer engine.

Note

Be careful when modifying lock_policy. Any value other than strict is considered less safe, but can be useful in the right situation.

Workflow Steps

Workflows consist of a series of steps that are executed in order. The available step types are:

• init: Runs terraform init.
• plan: Runs terraform plan.
• apply: Runs terraform apply.
• env: Sets environment variables.
• run: Runs a custom command.
• oidc: Initiates an OIDC connection to a cloud provider.
• checkov: Runs Checkov security scanning on the Terraform plan.
• conftest: Runs Conftest policy validation on the Terraform plan.
• opa: Evaluates an OPA policy against the Terraform plan.
• gates: Runs a command that creates Gatekeeper gates.

Every step type is accepted in both the plan and the apply list.

Caution

If a workflow specifies plan steps, at least one of them must be a plan step. If it specifies apply steps, at least one of them must be an apply step. A configuration that violates this is rejected with a repository configuration error.

A custom run step that shells out to terraform plan or terraform apply does not satisfy this requirement: the plan step is what reports the plan result that Terrateam tracks, and the apply step is what participates in Terrateam’s apply handling.

Omitting the plan or apply key uses the default steps, which already satisfy this.

Plan

Plan steps are defined under the plan key in a workflow. The list must contain at least one step of type: plan.

Apply

Apply steps are defined under the apply key in a workflow. The list must contain at least one step of type: apply.

Init, Plan, and Apply steps

The init, plan, and apply step types run the corresponding command of the engine. They accept the following keys:

Key	Type	Description
type	String	init, plan, or apply.
extra_args	List	Extra command line arguments passed to the command.
env	Object	Environment variables to set for this execution. Object keys are environment variable names and the value is a string.
visible_on	String	When the output should be visible in a PR comment or the UI. Options are always, failure, success. Default is failure for init and always for plan and apply.

Env

Environment variables can be set two ways:

• Using the env type combined with a cmd.
• Using the env type combined with a cmd and method set to source.

Command

Key	Type	Description
name	String	Environment variable name.
cmd	List	Command to execute that exports and environment variable.
trim_trailing_newlines	Boolean	Trim trailing newlines. Default is true.
sensitive	Boolean	Specify if the value of the environment variable is sensitive. It will be masked in all output. Default: false.

Source Method

Key	Type	Description
method	String	Must be set to source.
cmd	List	Command or script to execute that exports environment variables.
sensitive	Boolean	Indicates whether the environment variables modified by the script are sensitive. If true, they will be masked in all output. Default: false.

Run

Custom commands can be run using the run step type.

Key	Type	Description
cmd	List	Command to run from the directory that Terrateam is operating against.
run_on	String	Run the command depending on the state of the workflow. Options are success, failure, or always. Default is success.
capture_output	Boolean	When set to true, command output is recorded. Secrets are masked with ***. Default is false.
env	Object	Environment variables to set for this execution. Object keys are environment variable names and the value is a string.
ignore_errors	Boolean	Set to true if failure should be ignored. Default is false, except when on_error contains a gate, in which case it is true.
visible_on	String	When the output of the command should be visible in a PR comment or the UI. Options are always, failure, success. Default is failure.
format	String or Object	Controls how captured command output is rendered in PR comments. String values: code (default, fenced code block), raw (rendered as-is), markdown (rendered as markdown). Object form { type: code, lang: <language> } produces a fenced code block with syntax highlighting for <language>.
on_error	List	Actions to take if the command fails. Each entry is an object with a type. The only supported type is gate, which creates a Gatekeeper gate with the keys described in the Gate section below.

Checkov

Runs Checkov security scanning against the generated Terraform plan to detect misconfigurations and security issues.

The checkov step type automatically:

• Executes Checkov against the Terraform plan file
• Captures and includes the output in the Terrateam results
• Fails the workflow if critical issues are detected

Key	Type	Description
type	String	Must be checkov
extra_args	List	Extra command line arguments passed to the checkov command
env	Object	Environment variables to set for this execution. Object keys are environment variable names and the value is a string.
gate	Object	Gate configuration for manual approval if Checkov fails (see Gate section below)
ignore_errors	Boolean	Set to true if failure should be ignored. Default is false, except when gate is set, in which case it is true.
run_on	String	Run the step depending on the state of the workflow. Options are success, failure, or always. Default is success.
visible_on	String	When the output should be visible in a PR comment or the UI. Options are always, failure, success. Default is failure.

Configuration is done through environment variables. Common Checkov environment variables include:

• CKV_SKIP_CHECK: Comma-separated list of check IDs to skip
• CKV_CHECK: Comma-separated list of specific check IDs to run
• CKV_FRAMEWORK: Specify framework to scan (default: terraform_plan)

For a full list of configuration options, see the Checkov documentation.

Conftest

Runs Conftest policy validation using Open Policy Agent (OPA) against the generated Terraform plan.

The conftest step type automatically:

• Executes Conftest against the Terraform plan file using Rego policies
• Captures and includes the output in the Terrateam results
• Fails the workflow if policies are violated

Key	Type	Description
type	String	Must be conftest
extra_args	List	Extra command line arguments passed to the conftest command
env	Object	Environment variables to set for this execution. Object keys are environment variable names and the value is a string.
gate	Object	Gate configuration for manual approval if Conftest fails (see Gate section below)
ignore_errors	Boolean	Set to true if failure should be ignored. Default is false, except when gate is set, in which case it is true.
run_on	String	Run the step depending on the state of the workflow. Options are success, failure, or always. Default is success.
visible_on	String	When the output should be visible in a PR comment or the UI. Options are always, failure, success. Default is failure.

By default, Conftest looks for policies in the policy/ directory relative to the Terraform configuration. This can be customized using the CONFTEST_POLICY environment variable.

Common Conftest environment variables include:

• CONFTEST_POLICY: Path to the directory containing Rego policy files
• CONFTEST_NAMESPACE: Namespace to use for policy evaluation (default: main)
• CONFTEST_OUTPUT: Output format (json, table, tap, junit, github)

For more information on writing policies and configuration options, see the Conftest documentation.

OPA

Runs opa eval against the JSON representation of the generated Terraform plan. Use extra_args to pass the policy and the query, for example ['-d', 'policy.rego', 'data.terraform.deny'].

Key	Type	Description
type	String	Must be opa
extra_args	List	Extra command line arguments passed to opa eval, typically the policy file (-d) and the query.
fail_on	String	undefined fails the step when the query result is undefined. defined fails the step when the query result is defined. Default is undefined.
env	Object	Environment variables to set for this execution. Object keys are environment variable names and the value is a string.
gate	Object	Gate configuration for manual approval if the step fails (see Gate section below)
ignore_errors	Boolean	Set to true if failure should be ignored. Default is false, except when gate is set, in which case it is true.
run_on	String	Run the step depending on the state of the workflow. Options are success, failure, or always. Default is success.
visible_on	String	When the output should be visible in a PR comment or the UI. Options are always, failure, success. Default is failure.

Gate

The gate configuration allows you to require manual approval when certain workflow steps fail, particularly useful for security scanning, policy checks, and custom validation scripts. When a gated step fails, Terrateam records a gate instead of failing the plan, and blocks the apply until authorized users approve the gate. See Gatekeeper for details.

The gate key is supported on the following step types:

• checkov: Gate security scan failures
• conftest: Gate policy violations
• opa: Gate policy violations

The run step type does not accept gate. Use on_error with an entry of type: gate and the same keys instead.

Key	Type	Description
token	String	A unique identifier for this gate request. Gates without a token are approved by approving the pull request.
name	String	A name to give to the gate
all_of	List	List of users/teams/roles that must all approve the gate
any_of	List	List of users/teams/roles from which any_of_count approvals are required
any_of_count	Integer	Number of approvals required from the any_of list. Default is 0, which requires no approval from any_of. Set it to 1 or more when using any_of.

To approve a gate with a token, authorized users can comment:

terrateam gate approve <token>

Gates

The gates step type runs a command and creates a Gatekeeper gate for each entry of the gates list in the JSON the command prints to standard output. The step never fails the workflow.

Key	Type	Description
type	String	Must be gates
cmd	List	Command to run. Its standard output must be a JSON object of the form {"gates": [ ... ]}. Each gate accepts token, name, all_of, any_of, any_of_count, and add_reviewers (Boolean, default true: request a review from the user: and team: entries).
env	Object	Environment variables to set for this execution. Object keys are environment variable names and the value is a string.
run_on	String	Run the step depending on the state of the workflow. Options are success, failure, or always. Default is success.

OIDC

An OIDC connection to a cloud provider can be initiated using the oidc step type, which supports the AWS, Azure, and GCP providers.

Key	Type	Provider	Description
oidc	List		Initiate an OIDC connection to a cloud provider.
provider	String		Name of provider: aws, azure, or gcp. Required for azure and gcp; default is aws.
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}.
project_id	String	gcp	The Google Cloud project ID. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
client_id	String	azure	App Registration client ID. Required. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
tenant_id	String	azure	Azure AD (Entra ID) tenant ID. Required. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
subscription_id	String	azure	Default Azure subscription ID. Value can be specified using a GitHub Secret / environment variable with ${ENV_VAR}.
audience	String	azure	Specifies the Azure audience name to use. Default is api://AzureADTokenExchange.

Examples

Setting an Environment Variable with a Command

workflows:
  - tag_query: "dir:prod"
    plan:
      - type: env
        name: MY_CUSTOM_VAR
        cmd: ['echo', 'Hello, World!']
      - type: run
        cmd: ['echo', 'The value of MY_CUSTOM_VAR is: $MY_CUSTOM_VAR']
      - type: init
      - type: plan

Setting Environment Variables Using the Source Method

workflows:
  - tag_query: "dir:prod"
    plan:
      - type: env
        method: source
        cmd: ['$TERRATEAM_ROOT/scripts/environment']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['$TERRATEAM_ROOT/scripts/environment']
      - type: init
      - type: apply

This workflow matches any directories tagged with dir:prod and:

1. Executes the environment script to export environment variables.
2. Runs terraform init for both plan and apply.
3. Runs terraform plan with the environment variables set by the environment script.
4. Executes the environment script again to export environment variables before applying.
5. Runs terraform apply with the environment variables set by the environment script.

Custom Plan and Apply Steps

workflows:
  - tag_query: "dir:production"
    plan:
      - type: init
      - type: run
        cmd: ['echo', 'Running custom plan step']
      - type: plan
        extra_args: ['-input=false']
    apply:
      - type: init
      - type: apply
        extra_args: ['-auto-approve']
      - type: run
        cmd: ['./post_apply_script.sh']

This workflow matches any directories tagged with dir:production and:

1. Runs terraform init for both plan and apply.
2. Echoes a custom message before running terraform plan.
3. Runs terraform plan with the -input=false flag.
4. Runs terraform apply with the -auto-approve flag.
5. Runs a custom script after applying changes.

Blocking the Apply Path

Some teams plan with Terrateam but apply somewhere else. A common way to enforce that is an apply workflow whose run step exits non-zero, which fails the apply before Terraform is ever invoked. The apply steps must still contain an apply step, so put it after the run step that fails.

workflows:
  - tag_query: ""
    plan:
      - type: init
      - type: plan
    apply:
      - type: run
        cmd: ['sh', '-c', 'echo "Applies for this repository are performed outside of Terrateam."; exit 1']
      # Don't remove: the run step above always fails, so we never get here, but
      # Terrateam requires an apply step in the apply steps.
      - type: apply

This workflow:

1. Plans normally.
2. On apply, runs the run step, which prints a message and exits non-zero. A failed step aborts the workflow, so the apply step is never reached and terraform apply is never run. The message is reported on the pull request because a run step’s output is visible on failure by default.
3. Satisfies the requirement that the apply steps contain an apply step.

Caution

The apply step must come after the run step that fails. If it comes first, terraform apply runs before the run step has a chance to block it.

AWS OIDC Authentication

workflows:
  - tag_query: "dir:aws"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: init
      - type: apply

This workflow matches any directories tagged with dir:aws and:

1. Initiates an OIDC connection to AWS using the role ARN specified in the AWS_ROLE_ARN environment variable for both plan and apply.
2. Runs terraform init for both plan and apply.
3. Runs terraform plan.
4. Runs terraform apply.

GCP OIDC Authentication

workflows:
  - tag_query: "dir:gcp"
    plan:
      - type: oidc
        provider: gcp
        service_account: ${GCP_SERVICE_ACCOUNT}
        workload_identity_provider: ${GCP_WORKLOAD_IDENTITY_PROVIDER}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: gcp
        service_account: ${GCP_SERVICE_ACCOUNT}
        workload_identity_provider: ${GCP_WORKLOAD_IDENTITY_PROVIDER}
      - type: init
      - type: apply

This workflow matches any directories tagged with dir:gcp and:

1. Initiates an OIDC connection to GCP using the service account and workload identity provider specified in the GCP_SERVICE_ACCOUNT and GCP_WORKLOAD_IDENTITY_PROVIDER environment variables for both plan and apply.
2. Runs terraform init for both plan and apply.
3. Runs terraform plan.
4. Runs terraform apply.

Security Scanning with Checkov

workflows:
  - tag_query: ""
    plan:
      - type: init
      - type: plan
      - type: checkov

This workflow runs Checkov security scanning after generating the Terraform plan to detect misconfigurations and security issues.

Policy Validation with Conftest

workflows:
  - tag_query: ""
    plan:
      - type: init
      - type: plan
      - type: conftest

This workflow runs Conftest policy validation after generating the Terraform plan to ensure compliance with your organization’s policies.

Combined Security and Policy Checks

workflows:
  - tag_query: "env:production"
    plan:
      - type: env
        name: CKV_SKIP_CHECK
        cmd: ['echo', 'CKV_AWS_20,CKV_AWS_23']
      - type: env
        name: CONFTEST_POLICY
        cmd: ['echo', '$TERRATEAM_ROOT/policies/production/']
      - type: init
      - type: plan
      - type: checkov
      - type: conftest

This workflow for production environments:

1. Sets Checkov to skip specific checks
2. Configures Conftest to use production-specific policies
3. Runs both security scanning and policy validation

Using Gates for Manual Approval

workflows:
  - tag_query: "env:production"
    plan:
      - type: init
      - type: plan
      - type: checkov
        gate:
          token: "checkov-override"
          any_of: ["team:security", "team:platform"]
          any_of_count: 1
      - type: conftest
        gate:
          token: "policy-override"
          all_of: ["team:compliance"]
          any_of: ["user:cto", "user:security-lead"]
          any_of_count: 1

This workflow allows security or platform team members to approve Checkov failures, and requires both compliance team approval and either CTO or security lead approval for Conftest policy violations.

Gating Custom Validation Scripts

workflows:
  - tag_query: ""
    plan:
      - type: init
      - type: plan
      - type: run
        cmd: ['./scripts/cost-check.sh']
        on_error:
          - type: gate
            token: "cost-approval"
            any_of: ["team:finance", "user:budget-owner"]
            any_of_count: 1

This workflow runs a custom cost validation script and allows finance team members or the budget owner to approve if costs exceed thresholds.

Specifying a GitHub Environment

workflows:
  - tag_query: production
    environment: production

This workflow will run using the production GitHub Environment, ensuring that the secrets and variables defined in the production environment are accessible.

Considerations

When configuring and using workflows in Terrateam, keep the following considerations in mind:

• Be cautious when modifying the default workflow steps, such as removing the init or plan steps, as this can lead to unexpected behavior or errors. Ensure that your custom workflows include all the necessary steps for a successful Terraform operation.
• When defining custom steps using the run step type, make sure that the specified command or script is available and executable within the Terrateam environment. Consider using absolute paths or ensuring that the necessary dependencies are installed.
• If your custom steps require specific environment variables, use the env step type with the source method to set them before the relevant steps. Be mindful of the order in which environment variables are set and used within the workflow.
• When using the source method for setting environment variables, ensure that the executed script or command properly exports the desired variables. Test the script independently to verify that it generates the expected environment variables.
• Consider the security implications of using the capture_output option with the run step type, as it may expose sensitive information in the GitHub pull request comment if the command fails. Ensure that you properly sanitize or mask any sensitive data before enabling this option.
• Consider using Terrateam’s built-in environment variables (e.g., TERRATEAM_DIR, TERRATEAM_WORKSPACE) within your workflows to make them more dynamic and reusable across different directories and workspaces.