Skip to content

Terraform provider

Preview The official Terraform provider will let you declare your managed.dev fleet as code. It’s designed to be generated from the same OpenAPI spec as the Go SDK and the mf CLI, so its resources and arguments track the API instead of lagging it. The goal is the usual Terraform workflow — plan, apply, drift detection, state — over sites, environments, teams, and the scoped keys that drive your other automation.

The provider is designed to model the resource graph as Terraform resources, with the profiles and scopes the API treats as first-class declared right in HCL.

Resource Manages Key arguments
forge_site A site/app domain, profile (bedrock/vanilla/static), php_version, git_repo, git_branch
forge_environment An environment under a site site_id, type (staging/branch), branch
forge_team A team name, members
forge_api_key A scoped key for other automation scopes, expires_in_days, resource (a site pin)

A site whose runtime is static advertises a different capability set than wordpress, so the design has the provider validate that an argument you set is actually supported by the runtime before it ever calls the API.

This configuration provisions a WordPress site, a branch environment wired to a branch, and a least-privilege key for a deploy bot — all in one apply.

main.tf
terraform {
required_providers {
forge = {
source = "managed-dev/forge"
version = "~> 0.1"
}
}
}
provider "forge" {
# Reads FORGE_TOKEN from the environment by default —
# a dedicated, narrowly-scoped key, never your personal one.
version = "2026-06-23"
}
resource "forge_site" "store" {
domain = "acme-store.com"
profile = "bedrock"
git_repo = "git@github.com:acme/store.git"
git_branch = "main"
}
resource "forge_environment" "checkout_preview" {
site_id = forge_site.store.id
type = "branch"
branch = "feature/checkout"
}
# A least-privilege scope set for a deploy bot.
resource "forge_api_key" "deploy_bot" {
scopes = [
"sites:read",
"deployments:write",
"environments:write",
"jobs:read",
"observability:read",
]
expires_in_days = 90
# Pin the key to one site — the only resource pin mintable today.
resource {
type = "site"
id = forge_site.store.id
}
}
output "preview_url" {
value = forge_environment.checkout_preview.preview_url
}

Beyond terraform plan, the design includes a server-side propose / validate step (DigitalOcean app-spec style): the provider submits the desired configuration to the API, which returns the set of jobs it would run and any capability or scope conflicts — without changing anything. This catches a bad profile/argument combination or an insufficiently-scoped key before apply, not in the middle of it. Today you can approximate the dry-run idea for individual operations that support it — for example mf sites php-version <id> 8.4 --dry-run.

CI runners and the Terraform provider are hostile to long-lived SSE streams — connections get cut, proxies buffer, and there’s no terminal to tail. So when an apply triggers an async job, the provider is designed to wait with ETag long-poll instead: it polls GET /v1/jobs/{id} with If-None-Match, getting a cheap 304 Not Modified until the job’s state changes, then reads the new body. This is the same job, just consumed over a transport that survives CI. See async jobs for the full model and the other two consumption paths.