Skip to main content
Review, version, and apply organization configuration alongside your infrastructure with the Terraform provider.
The provider is in beta. Pin an exact version, review each upgrade, and test upgrades outside production before broad rollout.
See the complete resource reference and configuration examples.

​
Common use cases

​
Deploy and share runner infrastructure

Create a runner record and registration token, then pass the runner ID and token to the cloud module that deploys its infrastructure. This keeps control-plane and cloud resources in one dependency graph. The registration token expires after 24 hours and can be used once. Terraform marks it as sensitive but stores it in state so a cloud module can consume it. Use an encrypted, access-controlled remote state backend.

​
Standardize organization settings

Manage organization-wide settings such as environment lifecycle limits, project creation rules, agent policies, security policies, identity configuration, custom domains, announcements, and terms of service. Some resources reset, disable, or preserve remote settings when destroyed, so review the Registry documentation and the destroy plan before applying a removal.

​
Manage and share automations

Define an Automation’s triggers, execution context, Codex settings, limits, and steps. Grant groups the Viewer, Executor, or Admin role as described in Sharing Automations.

​
Manage and share projects

Create projects with their repository, branch, environment classes, and prebuild configuration. Import existing projects without recreating them. Grant groups access as described in Project sharing.

​
Configure the provider

Terraform CLI 1.14 or later is required. Packages for Linux amd64 and Linux arm64 are available; macOS and Windows packages are not available. Follow the installation instructions and pin your chosen version. Create a read-and-write personal access token and keep it outside the configuration:
Use a token owned by someone who can read and change every managed object.
Service account token support varies by API. Use a personal access token for writes unless Support confirms that a service account token works for your use case.
If your organization uses a custom management-plane domain, set ONA_HOST to that origin:

​
Protect state and review destructive changes

The sensitive marker redacts values in normal command output but does not exclude ordinary attributes from state. Treat state and saved plans as sensitive data. Use write-only arguments and ephemeral resources when the Registry reference lists them. Managed resources support import. Terraform Query can discover many existing resources and generate import blocks, but not for every resource. Removing a resource block usually plans to delete the remote object. Use terraform state rm <address> to stop managing an object without deleting it. Review the state, secrets, and safe deletion guide and every destroy plan before applying changes.

​
Releases and support

  • Review the reference for supported resources, data sources, imports, and examples.
  • Follow releases and the changelog before upgrading.
  • Browse the source repository.
  • Report security issues through the security policy.
  • For account access, organization setup, or product behavior, open Support from the organization menu in the dashboard.