Spacelift Terraform

Spacelift

Spacelift orchestrates Terraform via GitOps: GitHub pushes trigger runs, policies govern behavior, contexts inject config, workers execute runs.

• API: https://<account>.app.spacelift.io/graphql
• Terraform provider: spacelift-io/spacelift
• spacectl: brew install spacelift-io/spacelift/spacectl

Core Concepts

GitOps Workflow

feature branch push
  → push policy → propose
  → proposed run: terraform plan
  → commit status reported to PR

PR merged to tracked branch (e.g., main)
  → push policy → track
  → tracked run: terraform plan
  → if autodeploy: auto-apply
  → else: unconfirmed state → human confirms → apply

Run States

spacectl Quick Reference

Auth (CI/Agent — non-interactive)

export SPACELIFT_API_KEY_ENDPOINT=https://myorg.app.spacelift.io
export SPACELIFT_API_KEY_ID=$SECRET_KEY_ID
export SPACELIFT_API_KEY_SECRET=$SECRET_KEY_SECRET

GitHub Actions

- uses: spacelift-io/setup-spacectl@main
- run: spacectl stack deploy --id my-stack --auto-confirm --tail
  env:
    SPACELIFT_API_KEY_ENDPOINT: https://myorg.app.spacelift.io
    SPACELIFT_API_KEY_ID: ${{ secrets.SPACELIFT_API_KEY_ID }}
    SPACELIFT_API_KEY_SECRET: ${{ secrets.SPACELIFT_API_KEY_SECRET }}

Key Commands

spacectl stack list
spacectl stack deploy --id <stack> --auto-confirm --tail
spacectl stack task --id <stack> --tail 'terraform output -json'
spacectl run list --stack <stack>
spacectl run logs --stack <stack> --run <run-id>
spacectl run confirm --stack <stack> --run <run-id>
spacectl workerpool list
spacectl profile export-token          # get bearer token for API calls

Stack Settings Quick Reference

Policy Types Quick Reference

All policies use Rego v1 (package spacelift). Auto-attach via label autoattach:<label>.

Most Common Patterns

# Push: standard GitOps
track if input.push.branch == input.stack.branch
propose if not is_null(input.pull_request)
ignore if { not track; not propose }

# Plan: block deletions
deny contains sprintf("Deletion not allowed: %s", [c.entity.address]) if {
  some c in input.spacelift.run.changes; c.action == "deleted"
}

# Plan: manual review for drift
warn contains "Drift reconciliation requires manual approval" if {
  input.spacelift.run.drift_detection
}

# Approval: require 1 reviewer
approve if count(input.reviews.current.approvals) >= 1

Reference Files