workflows

workflows sets the steps that Stategraph Orchestration runs to plan and apply a directory and workspace, in place of the default workflow. An entry can also set the engine, the GitHub environment, the runner, the lock policy, and the plan storage.

Default Configuration

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

Keys

workflows is a list. Orchestration uses the first entry whose tag_query matches the directory and workspace. Each entry has these keys:

Workflow Steps

Steps run in order. Both the plan and the apply list accept each step type:

• init, plan, apply: run that command of the engine, for example terraform plan.
• env: sets environment variables.
• run: runs a custom command.
• oidc: gets cloud credentials through OIDC.
• checkov: scans the plan with Checkov.
• conftest: checks the plan against Conftest policies.
• opa: evaluates an OPA policy against the plan.
• gates: runs a command that creates Gatekeeper gates.

Init, plan, and apply steps

Env

The env step sets environment variables for the steps after it, so put it before the steps that use them. It has two methods: a command, or a script with method: source.

Command

Sets the variable name to the output of cmd.

Source Method

Runs cmd and keeps the environment variables that it exports. The script must export them, so test it on its own first.

Run

The run step runs a custom command from the directory that Orchestration works on. The command must be available and executable on the runner: use absolute paths, or install what it needs. It can read the runner environment variables, such as TERRATEAM_DIR and TERRATEAM_WORKSPACE, so one workflow can serve many directories and workspaces.

Orchestration records the output of the command and masks secrets with ***. When the command fails, the output shows in the pull request comment by default, so remove or mask sensitive data in it.

Checkov

The checkov step runs Checkov on the JSON form of the plan, to find misconfigurations and security issues. The output goes into the results. The step fails when Checkov exits with an error.

Checkov reads its configuration from environment variables. Set them with an env step before the checkov step. Common variables:

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

For all options, see the Checkov documentation.

Conftest

The conftest step runs Conftest with Rego policies on the JSON form of the plan. The output goes into the results. The step fails when a policy is violated.

By default, Conftest reads policies from the policy/ directory, relative to the Terraform configuration. To change Conftest, set these environment variables with an env step:

• 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 policies and other options, see the Conftest documentation.

OPA

The opa step runs opa eval on the JSON form of the plan. Pass the policy and the query in extra_args, for example ['-d', 'policy.rego', 'data.terraform.deny'].

Gate

A gate asks for manual approval when a step fails, for example a security scan, a policy check, or a custom validation script. When a gated step fails, Orchestration records a gate instead of failing the plan, and blocks the apply until authorized users approve the gate. See Gatekeeper.

The checkov, conftest, and opa steps accept gate. The run step does not: use on_error with an entry of type: gate and the same keys.

To approve a gate with a token, an authorized user comments:

stategraph gate approve <token>

Gates

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

OIDC

The oidc step gets short-lived credentials from AWS, Azure, or GCP through OpenID Connect. For AWS, it sets AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, and AWS_REGION. Each string value except type and provider can come from a GitHub secret or an environment variable, as ${ENV_VAR}.

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

For directories that match dir:prod, the environment script exports environment variables before the plan, and again before the apply. Then terraform init runs, and terraform plan or terraform apply runs with these variables.

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']

For directories that match dir:production, this workflow runs terraform init for both plan and apply. It prints a message before terraform plan, plans with -input=false, applies with -auto-approve, and runs a custom script after the apply.

Blocking the apply path

Some teams plan with Orchestration but apply somewhere else. To enforce this, add a run step to apply that exits non-zero, so that the apply fails before Terraform runs. The apply steps must still contain an apply step.

workflows:
  - tag_query: ""
    plan:
      - type: init
      - type: plan
    apply:
      - type: run
        cmd: ['sh', '-c', 'echo "Applies for this repository are performed outside of Stategraph."; exit 1']
      # Required: the apply list must contain an apply step. The run step
      # above always fails first, so this step never runs.
      - type: apply

This workflow plans normally. On apply, the run step prints a message and exits non-zero. A failed step aborts the workflow, so the apply step never starts and terraform apply never runs. The pull request shows the message, because the output of a run step is visible on failure by default.

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

For directories that match dir:aws, the plan and the apply first get AWS credentials through OIDC, with the role ARN from the AWS_ROLE_ARN environment variable. Then terraform init runs, followed by terraform plan or 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

For directories that match dir:gcp, the plan and the apply first get GCP credentials through OIDC, with the service account and the workload identity provider from the GCP_SERVICE_ACCOUNT and GCP_WORKLOAD_IDENTITY_PROVIDER environment variables. Then terraform init runs, followed by terraform plan or terraform apply.

Security scanning with Checkov

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

Checkov scans the plan for misconfigurations and security issues.

Policy validation with Conftest

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

Conftest checks the plan against the policies of your organization.

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

For production, this workflow makes Checkov skip two checks, points Conftest at the production policies, and runs both after the plan.

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

A member of the security or platform team can approve a Checkov failure. A Conftest policy violation needs the approval of the compliance team, and of the CTO or the security lead.

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

A custom script checks the cost. When the cost exceeds the thresholds, a member of the finance team or the budget owner can approve.

Specifying a GitHub environment

workflows:
  - tag_query: production
    environment: production

The run uses the production GitHub environment, so it can read the secrets and variables of that environment.

Related

• hooks
• engine
• Custom commands
• Runs-on
• GitHub environments
• Gatekeeper
• Security scanning
• OPA
• Runner environment variables