> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Terraform provider

> Manage runners, projects, organization settings, automations, and more.

Review, version, and apply organization configuration alongside your infrastructure with the [Terraform provider](https://registry.terraform.io/providers/gitpod-io/ona/latest).

<Warning>
  The provider is in beta. Pin an exact version, review each upgrade, and test upgrades outside production before broad rollout.
</Warning>

See the complete [resource reference and configuration examples](https://registry.terraform.io/providers/gitpod-io/ona/latest/docs).

## 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.

* Use the [AWS runner module](https://github.com/gitpod-io/terraform-aws-ona-runner) to deploy an AWS runner in your VPC.
* Use the [GCP runner module](https://registry.terraform.io/modules/gitpod-io/ona-runner/google/latest) to deploy a GCP runner in your project.
* Share the registered runner with groups as described in [Sharing resources](/docs/ona/organizations/sharing-resources).

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](/docs/ona/automations/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](/docs/ona/projects/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](https://registry.terraform.io/providers/gitpod-io/ona/latest) and pin your chosen version.

Create a read-and-write [personal access token](/docs/ona/integrations/personal-access-token) and keep it outside the configuration:

```bash theme={null}
export ONA_TOKEN="<personal-access-token>"
terraform init
terraform plan
```

Use a token owned by someone who can read and change every managed object.

<Info>
  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.
</Info>

If your organization uses a custom management-plane domain, set `ONA_HOST` to that origin:

```bash theme={null}
export ONA_HOST="https://<custom-domain>"
```

## 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](https://registry.terraform.io/providers/gitpod-io/ona/latest/docs/guides/state-secrets-and-safe-deletion) and every destroy plan before applying changes.

## Releases and support

* Review the [reference](https://registry.terraform.io/providers/gitpod-io/ona/latest) for supported resources, data sources, imports, and examples.
* Follow [releases](https://github.com/gitpod-io/terraform-provider-ona/releases) and the [changelog](https://github.com/gitpod-io/terraform-provider-ona/blob/main/CHANGELOG.md) before upgrading.
* Browse the [source repository](https://github.com/gitpod-io/terraform-provider-ona).
* Report security issues through the [security policy](https://github.com/gitpod-io/terraform-provider-ona/security/policy).
* For account access, organization setup, or product behavior, open **Support** from the organization menu in the dashboard.