Gatekeeper - Manual Approval Gates

Gatekeeper allows you to create manual approval gates in your Terrateam workflows, enabling authorized users to override failures from security scans, policy checks, or custom validations. This is particularly useful when you need human judgment to determine if certain violations are acceptable given the context.

Understanding Gatekeeper

When a gated workflow step fails (such as a security scan detecting issues or a policy check finding violations), instead of immediately failing the entire workflow, Gatekeeper:

1. Pauses the workflow execution
2. Creates an approval request
3. Notifies authorized approvers
4. Waits for manual approval before continuing

This allows teams to maintain strict automated checks while providing flexibility for legitimate exceptions.

Gates can be associated with a token, which requires users to explicitly approve every gate that their approval has been requested on, using a pull request comment.

Gates that are not associated with a token require all requested approvers to approve the pull request in the VCS provider before changes can be applied.

How Gatekeeper Works

1. A gated step fails: A workflow step configured with a gate encounters a failure condition

2. Approval request created: Terrateam posts a comment in the pull request with:

   • Details about what failed
   • The gate token identifier
   • Who can approve the gate

3. Authorized user reviews: Team members review the failure and determine if it’s acceptable

4. Approval granted: An authorized user comments with the approval command:

   terrateam gate approve <token>

   Or approve the pull request if the gate does not have a token.

5. Workflow continues: Once approved, the workflow proceeds as if the step had succeeded

Configuring Gates

Gates can be added to the following workflow step types:

• run: Gate failures from custom scripts and commands
• checkov: Gate security scan violations
• conftest: Gate policy check failures

Gate Configuration Options

Key	Type	Description
token	String	A unique identifier for this gate request
name	String	A name to give the gate. This is useful for identifying why the gate was created when a token is not used
all_of	List	List of users/teams that must ALL approve the gate
any_of	List	List of users/teams where ANY ONE can approve the gate
any_of_count	Integer	Number of approvals required from the any_of list (default: 1)

Authorization Patterns

Gatekeeper supports flexible authorization patterns:

Single Approver:

gate:
  token: "security-override"
  any_of: ["user:security-lead"]

Any Team Member:

gate:
  token: "platform-approval"
  any_of: ["team:platform", "team:sre"]

Multiple Required Approvers:

gate:
  token: "critical-override"
  all_of: ["team:security", "team:compliance"]

N-of-M Approvals:

gate:
  token: "cost-approval"
  any_of: ["user:cfo", "user:cto", "user:eng-director", "user:finance-lead"]
  any_of_count: 2

Common Use Cases

Caution

Gates provide a powerful override mechanism. Configure them carefully to maintain security while enabling flexibility.

Require approval from specific team based on which resources were modified

Assuming a Rego policy file which defines a value networking_team_resources_modifed if any resources that the networking team manages have been modified, require someone from the networking team to approve the pull request before it can be applied.

workflows:
  - tag_query: ""
    plan:
      - type: init
      - type: plan
      - type: opa
        fail_on: defined
        extra_args: ['-d', 'policy.rego', 'data.terraform.networking_team_resources_modifed']
        gate:
          any_of: ["team:networking"]

Security Scan Overrides

Allow security teams to approve known false positives or accepted risks:

workflows:
  - tag_query: ""
    plan:
      - type: init
      - type: plan
      - type: checkov
        gate:
          token: "checkov-override"
          any_of: ["team:security", "team:platform"]

When Checkov detects issues, security or platform team members can review and approve if the findings are acceptable.

Policy Exception Handling

Enable compliance teams to grant exceptions to policy violations:

workflows:
  - tag_query: "production"
    plan:
      - type: init
      - type: plan
      - type: conftest
        gate:
          token: "policy-exception"
          all_of: ["team:compliance"]
          any_of: ["user:compliance-lead", "user:ciso"]

This requires both general compliance team approval and approval from either the compliance lead or CISO.

Cost Threshold Approvals

Require finance approval when infrastructure changes exceed cost thresholds:

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

If the cost check script fails (indicating costs exceed thresholds), finance team members can review and approve the changes.

Multi-Stage Validation

Combine multiple gated checks with different approval requirements:

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

      # Security scanning with override capability
      - type: checkov
        gate:
          token: "security-scan"
          any_of: ["team:security"]

      # Compliance validation with stricter approval
      - type: conftest
        gate:
          token: "compliance-check"
          all_of: ["team:compliance"]
          any_of: ["user:compliance-lead"]

      # Custom validation with multiple approvers required
      - type: run
        cmd: ['./scripts/validate-production.sh']
        gate:
          token: "prod-validation"
          any_of: ["team:platform", "team:sre", "team:devops"]
          any_of_count: 2