> For the complete documentation index, see [llms.txt](https://docs.pagerly.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagerly.io/getting-started/terraform.md).

# Terraform

Keep teams, rotations, PagerDuty and Opsgenie syncs, escalation policies, alert integrations, services and group on-calls in Terraform, and let plan show anything changed by hand.

The Pagerly Terraform provider keeps your on-call configuration in code. Changes go through a pull request, CI applies them, and `terraform plan` shows anything someone changed in Slack or the dashboard. It works with Terraform and OpenTofu.

{% hint style="success" %}
The provider is published as `pagerly/pagerly` on the [Terraform Registry](https://registry.terraform.io/providers/pagerly/pagerly/latest) and the [OpenTofu Registry](https://search.opentofu.org/provider/pagerly/pagerly/latest), so `terraform init` and `tofu init` both download it.
{% endhint %}

## 1. Create a key

An **org admin** opens **MCP, API & Terraform** in the dashboard's main menu, switches to the **API Keys** tab and clicks *Generate API key*. Store it in your CI secrets as `PAGERLY_API_KEY`. The key acts as the admin who created it.

## 2. Add the provider

```hcl
terraform {
  required_providers {
    pagerly = {
      source  = "pagerly/pagerly"
      version = "~> 0.1"
    }
  }
}

provider "pagerly" {}   # reads PAGERLY_API_KEY
```

## 3. Describe a team

A team either runs a Pagerly rotation, or follows a schedule in PagerDuty, Opsgenie, Datadog, JSM Ops or Google Calendar.

```hcl
resource "pagerly_team" "payments" {
  name     = "Payments"
  timezone = "Europe/London"
  rotation = {
    users     = ["alice@example.com", "bob@example.com"]
    frequency = "Weekly"
    day       = "Monday"
    time      = "09:00"
  }
}

resource "pagerly_team" "platform" {
  name = "Platform"
  sync = {
    source      = "pagerduty"
    schedule_id = "PABC123"
  }
}
```

People are email addresses, never Slack ids. A synced team's source must be connected under **Scheduling Integrations** first.

## Already have teams?

The dashboard's **Terraform** tab lists an `import` block for every team. Paste them and run:

```bash
terraform plan -generate-config-out=teams.tf
```

Terraform writes the matching configuration, and the plan shows nothing to change.

## What else it manages

Escalation policies, alert integrations (with their webhook URL as an output), services, group on-calls and the user directory. Overrides, swaps and incidents stay in Slack and the dashboard.

The full reference, with an example for every resource, is at [www.pagerly.io/docs/terraform](https://www.pagerly.io/docs/terraform).
