Agent-Skills.md

Agent Skills: Terrateam Usage Guide

|

UncategorizedID: stakpak/community-paks/terrateam-usage-guide

Repository

stakpak/community-paks
stakpak
3

Install this agent skill to your local

pnpm dlx add-skill https://github.com/stakpak/community-paks/tree/HEAD/terrateam-usage-guide

Skill Files

Browse the full folder contents for terrateam-usage-guide.

Download Skill

Loading file tree…

terrateam-usage-guide/SKILL.md

Skill Metadata

Name
terrateam-usage-guide
Description
|

Terrateam Usage Guide

Overview

Terrateam is an open-source GitOps CI/CD platform that automates Terraform and OpenTofu workflows through GitHub pull requests. It provides intelligent locking, policy enforcement, OIDC authentication, drift detection, and cost estimation.

Key Capabilities:

  • Automatic plan/apply operations triggered by pull requests
  • Tag-based configuration for targeting specific environments
  • Fine-grained access control with team/role-based policies
  • OIDC authentication for AWS and GCP (no static credentials)
  • Drift detection with scheduled reconciliation
  • Security scanning with Checkov and policy validation with Conftest

Prerequisites

  • GitHub repository with Terraform/OpenTofu code
  • Terrateam installed (GitHub App or self-hosted)
  • Cloud provider credentials configured (OIDC recommended)

Workflow / Instructions

Step 1: Create Configuration File

Create .terrateam/config.yml in your repository root. Terrateam uses sensible defaults if this file doesn't exist.

Basic structure:

# .terrateam/config.yml
version: "1"

access_control:
  # Who can perform operations

apply_requirements:
  # Conditions before applying

dirs:
  # Directory-to-tag mappings

workflows:
  # Custom plan/apply steps

hooks:
  # Pre/post operation commands

Step 2: Configure Directory Mappings

Map repository directories to tags and workspaces using the dirs section:

dirs:
  # Production environment
  "environments/production":
    tags: [production, critical]
    workspaces:
      us-east-1:
        tags: [aws, us-east-1]
      eu-west-1:
        tags: [aws, eu-west-1]
    when_modified:
      file_patterns: ["${DIR}/*.tf", "${DIR}/*.tfvars"]
      autoplan: true
      autoapply: false

  # Staging environment
  "environments/staging":
    tags: [staging]
    when_modified:
      file_patterns: ["${DIR}/*.tf", "${DIR}/*.tfvars"]
      autoplan: true
      autoapply: true  # Auto-apply after merge

  # Shared modules (don't plan directly)
  "modules/*":
    tags: [module]
    when_modified:
      autoplan: false

Key concepts:

  • tags: Labels for targeting with policies and workflows
  • workspaces: Multiple Terraform workspaces per directory
  • ${DIR}: Variable representing the current directory path
  • autoplan: Automatically run plan on PR creation/update
  • autoapply: Automatically apply after PR merge

Step 3: Configure Access Control

Define who can perform plan and apply operations:

access_control:
  enabled: true
  policies:
    # Production: restricted apply access
    - tag_query: "production"
      plan: ['*']                           # Anyone can plan
      apply: ['team:sre', 'team:platform']  # Only specific teams can apply
      apply_autoapprove: ['user:lead-sre']  # Lead can skip approval
      apply_force: []                       # No one can force apply

    # Default policy for all other directories
    - tag_query: ""
      plan: ['*']
      apply: ['role:write']  # Anyone with write access

Access specifiers:

  • *: Anyone
  • team:name: GitHub team members
  • user:username: Specific user
  • role:write: Repository collaborators with write access

Step 4: Configure Apply Requirements

Set conditions that must be met before applying:

apply_requirements:
  create_pending_apply_check: true  # Prevents merge until applied

  checks:
    - tag_query: "production"
      approved:
        enabled: true
        any_of: ['team:sre', 'team:platform']
        any_of_count: 2           # Need 2 approvals
        all_of: ['user:security-lead']  # Always need security approval
      merge_conflicts:
        enabled: true
      status_checks:
        enabled: true
        ignore_matching: ["ci/.*"]  # Ignore CI checks

    - tag_query: ""  # Default
      approved:
        enabled: true
        any_of_count: 1
      merge_conflicts:
        enabled: true

Step 5: Configure Workflows with OIDC

Define custom plan/apply steps with cloud authentication:

workflows:
  # Production workflow with AWS OIDC
  - tag_query: "production"
    environment: "production"  # GitHub Environment
    plan:
      - type: oidc
        provider: aws
        role_arn: ${PROD_AWS_ROLE_ARN}
        region: us-east-1
        duration: 3600
      - type: init
        extra_args: ["-upgrade"]
      - type: plan
        extra_args: ["-var-file=prod.tfvars"]
      - type: checkov  # Security scanning
      - type: conftest  # Policy validation
    apply:
      - type: oidc
        provider: aws
        role_arn: ${PROD_AWS_ROLE_ARN}
        region: us-east-1
      - type: init
      - type: apply
        retry:
          enabled: true
          tries: 3

  # GCP workflow
  - tag_query: "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

  # Default workflow
  - tag_query: ""
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply

Workflow step types:

  • oidc: Cloud provider authentication
  • init: terraform init
  • plan: terraform plan
  • apply: terraform apply
  • run: Custom command
  • env: Set environment variable
  • checkov: Security scanning
  • conftest: OPA policy validation

Step 6: Configure Hooks

Run commands before/after operations:

hooks:
  all:
    pre:
      # Set environment variables
      - type: env
        name: TF_VAR_commit_sha
        cmd: ['git', 'rev-parse', 'HEAD']
      # Source secrets
      - type: env
        method: source
        cmd: ['./scripts/load-secrets.sh']
        sensitive: true
    post:
      - type: run
        cmd: ['rm', '-f', '*.tmp']
        run_on: always
        ignore_errors: true

  plan:
    post:
      - type: drift_create_issue  # Create issue on drift

  apply:
    post:
      - type: run
        cmd: ['./scripts/notify-slack.sh']
        run_on: success

Step 7: Configure Drift Detection

Enable scheduled drift detection:

drift:
  enabled: true
  schedules:
    production:
      schedule: "hourly"
      tag_query: "production"
      reconcile: false  # Don't auto-fix
      window:
        start: "09:00"
        end: "17:00"
    staging:
      schedule: "daily"
      tag_query: "staging"
      reconcile: true  # Auto-fix drift

Step 8: Configure Cost Estimation

Enable Infracost integration:

cost_estimation:
  enabled: true
  provider: infracost
  currency: USD

Pull Request Commands

Trigger operations via PR comments:

| Command | Description | |---------|-------------| | terrateam plan | Run plan for all changed directories | | terrateam plan dir:path | Plan specific directory | | terrateam apply | Apply all planned changes | | terrateam apply dir:path | Apply specific directory | | terrateam apply-autoapprove | Apply without approval (if permitted) | | terrateam apply-force | Force apply (if permitted) | | terrateam unlock | Release locks | | terrateam gate approve <token> | Approve gated step |

Tag Query Syntax

Target specific resources using tag queries:

# Single tag
tag_query: "production"

# AND logic
tag_query: "production AND aws"

# OR logic
tag_query: "staging OR development"

# Directory-based
tag_query: "dir:environments/production"

# Workspace-based
tag_query: "workspace:us-east-1"

# Combined
tag_query: "production AND aws AND dir:environments/*"

Common Patterns

Multi-Environment Setup

dirs:
  "env/prod": { tags: [prod, critical] }
  "env/staging": { tags: [staging] }
  "env/dev": { tags: [dev] }

workflows:
  - tag_query: "prod"
    plan:
      - type: init
      - type: plan
        extra_args: ["-var-file=prod.tfvars"]
  - tag_query: "staging"
    plan:
      - type: init
      - type: plan
        extra_args: ["-var-file=staging.tfvars"]

Layered Infrastructure with Dependencies

dirs:
  "network":
    when_modified:
      autoplan: true
  "compute":
    when_modified:
      depends_on: "dir:network"
  "applications":
    when_modified:
      depends_on: "dir:compute"

Security Scanning with Gates

workflows:
  - tag_query: "production"
    plan:
      - type: init
      - type: plan
      - type: checkov
        gate:
          token: "security-override"
          any_of: ["team:security"]
      - type: conftest
        gate:
          token: "policy-override"
          all_of: ["team:compliance"]

Terragrunt Support

engine:
  name: terragrunt
  version: "0.45.0"
  tf_version: "1.5.0"

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

Best Practices

  1. Start Simple: Begin with minimal configuration, add complexity as needed
  2. Use Tags: Organize resources with meaningful tags for policy targeting
  3. Layer Security: Combine access control, apply requirements, and workflows
  4. OIDC Over Static Credentials: Use OIDC for cloud authentication
  5. Environment Separation: Different policies for production vs staging
  6. Test Workflows: Validate complex workflows in non-production first
  7. Automate Wisely: Be cautious with autoapply and drift reconciliation
  8. Version Control: Always specify configuration version

Troubleshooting

| Issue | Solution | |-------|----------| | Plan not triggering | Check when_modified.file_patterns matches changed files | | Apply blocked | Verify apply_requirements conditions are met | | OIDC failing | Confirm role ARN and trust policy configuration | | Lock conflicts | Use terrateam unlock to release stale locks | | Drift not detected | Verify drift.schedules configuration and time window |

Environment Variables

Terrateam provides built-in variables:

| Variable | Description | |----------|-------------| | TERRATEAM_DIR | Current directory being processed | | TERRATEAM_WORKSPACE | Current Terraform workspace | | TERRATEAM_ROOT | Repository root path | | TERRATEAM_PLAN_FILE | Path to generated plan file |

References