Skip to content
Terrateam

Custom Runners with runs_on

The runs_on configuration allows you to specify which GitHub Actions runners your Terrateam workflows should execute on. This is particularly useful for organizations that need to use self-hosted runners for security, compliance, or performance reasons.

Overview

By default, Terrateam workflows run on ubuntu-latest GitHub-hosted runners. The runs_on configuration gives you flexibility to:

  • Use self-hosted runners for sensitive workloads
  • Target specific runner labels for specialized hardware or software requirements
  • Distribute workloads across different runner pools
  • Comply with organizational policies that require on-premises execution

Configuration

The runs_on parameter accepts any valid GitHub Actions runner specification. It can be configured at the workflow level in your .terrateam/config.yml:

workflows:
  - tag_query: ""
    runs_on: ubuntu-latest  # Default value

Basic Examples

Self-Hosted Runner

workflows:
  - tag_query: "production"
    runs_on: self-hosted
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply

Multiple Labels

When you need a runner with specific characteristics, you can specify multiple labels as an array:

workflows:
  - tag_query: "production"
    runs_on: [self-hosted, linux, x64, gpu]
    plan:
      - type: init
      - type: plan

Single Label as Array

You can also specify a single label as an array for consistency:

workflows:
  - tag_query: ""
    runs_on: ["self-hosted"]

Advanced Patterns

Environment-Specific Runners

Different environments often have different security and compliance requirements. You can configure separate runners for each environment:

workflows:
  # Development uses GitHub-hosted runners
  - tag_query: "dev"
    runs_on: ubuntu-latest
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply


  # Staging uses self-hosted runners with specific labels
  - tag_query: "staging"
    runs_on: [self-hosted, staging, linux]
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply


  # Production uses dedicated high-security runners
  - tag_query: "production"
    runs_on: [self-hosted, production, secure, linux]
    plan:
      - type: init
      - type: plan
    apply:
      - type: init
      - type: apply

Conclusion

The runs_on configuration provides powerful flexibility for controlling where your Terraform operations execute. By carefully planning your runner strategy, you can achieve the right balance of security, performance, compliance, and cost for your organization’s needs.