Manage workflows with Terraform

​

What Terraform manages

• Who can run the workflow
• Service Catalog listing and the Service Catalog description
• The access package whose connections the workflow uses. Workflows created by Terraform start in the team’s default package.
• Approvals

​

Before you begin

• Terraform 1.11 or later
• Remote state storage that everyone running Terraform shares, such as an S3 bucket or HCP Terraform
• Two API keys, both restricted to the teams Terraform manages:
  • An apply key with the workflows:read, workflows:write, and workflows:deploy permission bundles. workflows:deploy is only needed to publish. Without it, applies save drafts.
  • A plan key with only workflows:read, for running terraform plan on pull requests.
  Org Admins create keys in Organization settings, and Team Managers create team-scoped keys in Team Settings → API Keys.
• The UUID of each team. Open Team Settings → Your Team and select Copy team UUID.

​

Set up the provider

terraform {
  required_version = ">= 1.11"

  required_providers {
    serval = {
      source  = "ServalHQ/serval"
      version = "~> 0.26.0"
    }
  }

  backend "s3" {
    bucket       = "example-terraform-state"
    key          = "serval/workflows.tfstate"
    region       = "us-east-1"
    use_lockfile = true
  }
}

provider "serval" {}

export SERVAL_CLIENT_ID="<client-id>"
export SERVAL_CLIENT_SECRET="<client-secret>"

export SERVAL_BASE_URL="https://public.eu1.serval.com"

​

Define a workflow

.
├── main.tf
└── workflows/
    └── onboard-employee/
        └── index.ts

locals {
  it_team_id = "<team-uuid>"
}

resource "serval_workflow" "onboard_employee" {
  team_id      = local.it_team_id
  name         = "Onboard employee"
  description  = "Creates accounts and assigns starter access for a new hire."
  content      = file("${path.module}/workflows/onboard-employee/index.ts")
  is_published = true
}

​

Bring existing workflows under Terraform

import {
  to = serval_workflow.onboard_employee
  id = "<workflow-id>"
}

​

Review changes in pull requests

• Repository secrets SERVAL_PLAN_CLIENT_ID and SERVAL_PLAN_CLIENT_SECRET for the plan key
• An environment named serval with secrets SERVAL_CLIENT_ID and SERVAL_CLIENT_SECRET for the apply key

name: serval-workflows

on:
  pull_request:
  push:
    branches: [main]

jobs:
  plan:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    env:
      SERVAL_CLIENT_ID: ${{ secrets.SERVAL_PLAN_CLIENT_ID }}
      SERVAL_CLIENT_SECRET: ${{ secrets.SERVAL_PLAN_CLIENT_SECRET }}
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init -input=false
      - run: terraform plan -input=false -lock=false

  apply:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: serval
    concurrency:
      group: serval-apply
      cancel-in-progress: false
    env:
      SERVAL_CLIENT_ID: ${{ secrets.SERVAL_CLIENT_ID }}
      SERVAL_CLIENT_SECRET: ${{ secrets.SERVAL_CLIENT_SECRET }}
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init -input=false
      - run: terraform apply -input=false -auto-approve -lock-timeout=5m

​

How applies behave

• Publishing: With is_published = true, each apply that changes the workflow publishes a new version, which appears in version history. With is_published = false, the change is saved as a draft. It doesn’t unpublish a live workflow, and on a live workflow every plan shows is_published changing, so keep it true once a workflow is published.
• Failed publishing: If Serval rejects the code, the apply fails before anything changes. If publishing fails for another reason, such as a connection the workflow can’t use, the new code can stay behind as a draft while the live version is unchanged.
• Edits made in Serval: Terraform compares your files with the workflow’s latest draft. Changes made in the app or with Catalyst show up in the next plan, and an apply replaces them with the code in your repository. Make changes to Terraform-managed workflows in the repository.
• Removing a resource: Deleting a serval_workflow block, or running terraform destroy, deletes the workflow in Serval. You can restore it from Team Settings → Recently deleted for 30 days. It comes back as an unpublished draft, so import it again before managing it with Terraform.
• Changing team_id: Terraform deletes the workflow and creates a new one with a new ID. Anything that refers to the old ID stops working.