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.
resources
Section titled “resources”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.
a worked example
Section titled “a worked example”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.
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}propose and validate (dry-run)
Section titled “propose and validate (dry-run)”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.
jobs in CI: ETag long-poll, not SSE
Section titled “jobs in CI: ETag long-poll, not SSE”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.