Terraform Provider Ona

Terraform provider for managing Gitpod resources on ona.com.

Requirements

• Terraform >= 1.7.0
• Go >= 1.26 (for building from source)

Quick Links

• Terraform Registry
• Provider Docs
• Project Resource Docs
• Runner Resource Docs
• Runner SCM Integration Resource Docs
• Secret Resource Docs
• Secret Resource Example
• Secret Import Example
• Authenticated Identity Data Source Docs
• Project Data Source Docs
• Runner Data Source Docs
• Group Data Source Docs
• Groups Data Source Docs
• Runner Environment Classes Data Source Docs
• Runners Data Source Docs
• Integration Example

Supported Types

Resources:

• ona_project
• ona_runner
• ona_runner_scm_integration
• ona_secret

Data sources:

• ona_authenticated_identity
• ona_group
• ona_groups
• ona_project
• ona_runner
• ona_runner_environment_classes
• ona_runners

Using the Provider

terraform {
  required_providers {
    ona = {
      source = "combor/ona"
    }
  }
}

provider "ona" {
  api_key = var.ona_api_key
  # optional:
  # base_url        = var.ona_base_url
  # max_retries     = 2
  # request_timeout = "20s"
}

Example

To find your runner manager ID, go to ona.com → Settings → Runners, click the ⋯ menu on any managed runner, and select Copy runner manager ID.

resource "ona_runner" "example" {
  name              = "my-runner"
  provider_type     = "RUNNER_PROVIDER_MANAGED"
  runner_manager_id = "<your-runner-manager-id>" # see above for how to find this

  spec = {
    variant = "RUNNER_VARIANT_STANDARD"
    configuration = {
      region                           = "eu-central-1"
      auto_update                      = true
      devcontainer_image_cache_enabled = true
      release_channel                  = "RUNNER_RELEASE_CHANNEL_STABLE"
      log_level                        = "LOG_LEVEL_INFO"
    }
  }
}

data "ona_runner_environment_classes" "example" {
  runner_id = ona_runner.example.id
}

data "ona_authenticated_identity" "current" {}

resource "ona_project" "example" {
  name = "terraform-provider-ona"

  initializer = {
    specs = [
      {
        git = {
          remote_uri = "https://github.com/combor/terraform-provider-ona"
        }
      }
    ]
  }

  prebuild_configuration = {
    enabled = true
    environment_class_ids = [
      for environment_class in data.ona_runner_environment_classes.example.environment_classes :
      environment_class.id
    ]
    executor = {
      id        = data.ona_authenticated_identity.current.id
      principal = data.ona_authenticated_identity.current.principal
    }
  }
}

data "ona_project" "example" {
  id = ona_project.example.id
}

resource "ona_secret" "example" {
  name       = "DATABASE_URL"
  value      = "postgres://user:pass@db.example.com/mydb"
  project_id = ona_project.example.id

  environment_variable = true
}

data "ona_runner" "example" {
  id = ona_runner.example.id
}

See examples/main.tf for the integration-test configuration, examples/resources/ona_secret/resource.tf for additional secret examples, and docs/index.md, docs/resources/project.md, docs/resources/runner.md, docs/data-sources/authenticated_identity.md, docs/data-sources/group.md, docs/data-sources/groups.md, docs/data-sources/project.md, docs/data-sources/runner.md, docs/data-sources/runner_environment_classes.md, and docs/data-sources/runners.md for the checked-in docs.

Importing Existing Resources

terraform import ona_runner.example <runner-id>
terraform import ona_runner_scm_integration.github <scm-integration-id>
terraform import ona_project.example <project-id>
terraform import ona_secret.example <project-id>/<secret-id>

Development

# Build
go build -o terraform-provider-ona .

# Run tests
go test ./...

# Run the local CI checks used in day-to-day development
act push -j govulncheck -j build -j test

Run integration tests against the real Gitpod API with:

act push -j integration \
  -P ubuntu-latest=catthehacker/ubuntu:act-latest \
  --action-offline-mode \
  -s GITPOD_API_KEY=<your-key> \
  -s RUNNER_MANAGER_ID=<runner-manager-id>

To test the provider locally, create a ~/.terraformrc with dev overrides:

provider_installation {
  dev_overrides {
    "combor/ona" = "/path/to/terraform-provider-ona"
  }
  direct {}
}

Contributing

Bug reports and feature requests should go to GitHub Issues. Code changes should be proposed through pull requests.

Before opening a pull request, run:

• gofmt -w on changed Go files
• go test ./...
• act push -j govulncheck -j build -j test
• If you changed provider behavior or examples, also run the integration job with GITPOD_API_KEY and RUNNER_MANAGER_ID