Overview

The Forge provider intentionally manages policies and policy-adjacent routing only. Identities, integrations, products, models, MCP servers, and skills stay server-owned and are referenced by readable names. The public provider is published in the Terraform Registry as a37ai/forge. The v0.3 release line includes signed checksums and provider packages for Darwin, Linux, and Windows on amd64 and arm64.

Configure the provider

terraform {
  required_version = ">= 1.8.0"

  required_providers {
    forge = {
      source  = "a37ai/forge"
      version = "~> 0.3.0"
    }
  }
}

provider "forge" {
  organization_id  = "org.example"
  manager_id       = "policy-repository"
  manager_instance = "production"
}

Set FORGE_API_TOKEN to a Forge service-account token with policies:read and policies:write. endpoint defaults to https://api.forge.ai and can be supplied with FORGE_ENDPOINT. Plain HTTP is accepted only for localhost development. manager_id identifies the durable policy manager, such as a repository. manager_instance distinguishes independent deployments, such as production and staging. Keep both stable; changing them makes existing authority checks fail. The server binds manager_id and manager_instance to the authenticated service-account principal that first claims or creates the policy. Matching headers from another credential cannot read, update, release, or delete that Terraform-owned policy. The values identify state ownership; they are not secrets and do not replace token authorization. The provider checks compatibility with Forge before planning a mutation. A connected plan validates readable references, policy structure, Rego, the current revision, and policy ownership. Apply rechecks the reviewed plan and fails before changing the policy if a relevant remote value changed. The provider refreshes short-lived validation automatically at apply while keeping the exact definition, references, revision, and manager binding unchanged.

Resources

Resource	Purpose
`forge_content_policy`	Content policy with either native conditions or `forge.rego.v1` match logic, typed scope, stages, action, approval, redaction, and filtering
`forge_access_policy`	Access policy with either native conditions or `forge.rego.v1` match logic, typed scope, action, approval, and remediation
`forge_llm_gateway_access_profile`	Native gateway access profile, model selectors, and atomic provider route plan used by the production gateway runtime; gateway keys assign callers
`forge_mcp_acl`	Readable MCP server/tool ACL compiled to a Content policy
`forge_skill_acl`	Readable skill grant or block
`forge_policy_authority`	Explicitly claim/release an existing Forge-managed policy at an expected revision

Typed data sources resolve one exact customer-visible selector through the same organization-scoped resolver used by connected plans:

Data source	Resolves
`forge_user`, `forge_group`	Active directory subjects; optional qualifier disambiguates duplicate labels
`forge_agent`, `forge_ai_product`	Inventory targets with actual Content-policy applicability
`forge_integration`	Connected integration or supported enforcement connection
`forge_mcp_server`, `forge_mcp_tool`, `forge_skill`	Approved registry objects; MCP tools require a resolved parent server
`forge_gateway_provider`	Configured LLM Gateway provider
`forge_rego_test`	Compiles and evaluates a module against native HCL input and asserts the expected match during `terraform test`

Missing and ambiguous references fail rather than selecting the first result.

Production validation

Qualify each resource against your target Forge environment before production rollout. Use the same provider version, service-account scopes, organization, manager identity, and remote state backend that you will use in production.

Resource	Required pre-production lifecycle checks
`forge_content_policy`	Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy.
`forge_access_policy`	Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy.
`forge_llm_gateway_access_profile`	Create, refresh/no-op, route-plan update, import, exclusive-ownership rejection, and destroy; verify the resulting live gateway route.
`forge_mcp_acl`	Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy; verify the resulting live MCP decision.
`forge_skill_acl`	Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy; verify the resulting live skill decision.
`forge_policy_authority`	Claim at the reviewed revision, reject stale revisions and other managers, import the matching policy, release, and confirm the policy remains.

For every row, confirm that failed validation or ownership checks leave the remote resource unchanged, the final no-op plan is empty, and the Forge audit trail identifies the expected service account and manager.

Import IDs

Every resource imports by its stable Forge identifier:

Resource	Import value
`forge_content_policy`	Policy `id`
`forge_access_policy`	Policy `id`
`forge_llm_gateway_access_profile`	Profile `id`
`forge_mcp_acl`	ACL `id`
`forge_skill_acl`	ACL `id`
`forge_policy_authority`	Existing policy `id`, loaded into `policy_id`

Import reads state; it never bypasses or implicitly claims policy authority.

Provider arguments

Argument	Required	Description
`organization_id`	Yes	Forge organization to manage
`manager_id`	Yes	Stable durable manager/repository identity
`manager_instance`	Yes	Stable deployment/state identity
`api_token`	No	Sensitive token; prefer `FORGE_API_TOKEN`
`endpoint`	No	Control-plane URL; defaults to `FORGE_ENDPOINT` then the hosted API

Reference

Policy Resources

Content and Access schemas, native conditions, actions, examples, and readable references.

Gateway Profile

LLM gateway access-profile and route-plan attributes with a complete example.

Registry ACLs

MCP and skill ACL resources, parameter descriptions, and examples.

Conditions

Canonical field types, exact meanings, operators, and history-aware matching.

Authority

Attribute	Requirement and type	Exact meaning
`policy_id`	Required string; forces replacement	Existing Forge-managed durable policy ID to claim.
`expected_revision`	Required integer; forces replacement	Revision reviewed by the operator. The claim fails atomically if the remote revision differs.
`id`	Computed string	Provider state identity for the authority binding.
`current_revision`	Computed integer	Revision present when the binding is read.
`management_mode`	Computed string	Must be `terraform` after a successful claim.
`manager_id` / `manager_instance`	Computed strings	Server-confirmed exclusive manager binding; must equal provider configuration.

Replacement or destroy releases the claim; it does not disable, delete, or tombstone the underlying policy.

Ownership, adoption, and import

New resources are atomically created as Terraform-managed. To adopt an existing Forge-managed policy:

resource "forge_policy_authority" "customer_export" {
  policy_id         = "customer-export"
  expected_revision = 7
}

Read the policy’s current revision and review its definition.
Apply forge_policy_authority; the claim fails if the revision changed.
Keep the authority resource in state.
Add the corresponding policy resource with the exact remote definition.
Import it, for example:

terraform import forge_content_policy.customer_export customer-export

Import never claims authority implicitly. Importing before a claim, using a different manager binding, or removing the authority resource while the policy remains in state produces an authority error. Destroying the authority resource releases ownership back to Forge; destroying a policy resource disables and tombstones the policy. An organization owner can use Break glass on the console’s read-only policy view during an active incident. Forge requires a 10–1,024 character reason, creates a new immutable revision, records the owner and reason in the audit trail, atomically changes authority to forge, and clears the Terraform binding. The old state cannot revert the emergency revision: refresh reports lost authority and recovery requires an explicit reviewed claim or transfer.

Drift, retries, and state

Updates use the last observed immutable revision for optimistic concurrency.
Refresh verifies the exact Terraform manager and restores readable selectors.
Remote 404 removes the resource from Terraform state.
Destroy records a forward-only tombstone. The same authenticated manager_id + manager_instance can recreate that resource from the same state after destroy; the server assigns the next revision and preserves the complete history. A different manager cannot reuse the tombstoned ID.
Reads, updates, and deletes have bounded retries for 429 and 5xx errors.

Use lifecycle { prevent_destroy = true } for policies that need a separate retirement review. Terraform state contains policy configuration, sensitive match values, and an expiring signed plan-binding token; store it in an encrypted backend with narrow access. Never put API tokens or secret material in Rego source, selector names, descriptions, or filter values. Terraform applies resources independently. A multi-resource plan is not an atomic policy bundle: earlier resources can commit while a later reference, validation, authority, or network error fails the apply. Use one remote state writer, preserve the saved plan, and run a refresh plus policy-impact review after any partial failure. This guide assumes state created with a v0.3.x provider. Review the release notes and a saved plan before upgrading earlier state. The provider rejects an incompatible Forge deployment before planning a mutation. Rego modules and readable references are validated by the target Forge server during planning. terraform validate and an offline terraform plan -refresh=false prove only HCL/provider schema validity. A connected saved plan validates references, policy semantics, revision, and manager compatibility. Apply refreshes the short-lived signature and fails without mutation if any validated fact changed.

CI workflow

terraform fmt -check
terraform init
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan

Pin the provider to a reviewed compatible minor line and commit the dependency lock file. Upgrade by changing the version constraint, running terraform init -upgrade, reviewing provider checksums and the complete plan, and applying a saved plan. Do not combine a provider upgrade with unrelated policy scope or action changes. Run plans with one writer per state backend. Review policy deletions, authority changes, scope expansion, stronger consequences, Rego source changes, and gateway limits as security-sensitive changes.

Troubleshooting

Error	What to check
Reference not found or ambiguous	Exact spelling, organization, directory qualification, and duplicates
Authority conflict	Claim resource, stable manager values, correct API organization, and current state
Revision conflict	Refresh and review the remote change before replanning
Rego validation failed	Package, fixed entrypoint, input fields, forbidden built-ins, and output schema
Destroy rejected	Current revision, authority binding, `prevent_destroy`, and API permission

Guides

REST API

Configure the provider

Resources

Production validation

Import IDs

Provider arguments

Reference

Policy Resources

Gateway Profile

Registry ACLs

Conditions

Authority

Ownership, adoption, and import

Drift, retries, and state

CI workflow

Troubleshooting

​Configure the provider

​Resources

​Production validation

​Import IDs

​Provider arguments

​Reference

Policy Resources

Gateway Profile

Registry ACLs

Conditions

​Authority

​Ownership, adoption, and import

​Drift, retries, and state

​CI workflow

​Troubleshooting

Configure the provider

Resources

Production validation

Import IDs

Provider arguments

Reference

Authority

Ownership, adoption, and import

Drift, retries, and state

CI workflow

Troubleshooting