Terraform provider

terraform-provider-orbitalreg lets you manage projects, repositories, service accounts, retention policies, security blocks, and webhook subscriptions from Terraform. The provider is the recommended path when your platform-management surface lives in Terraform alongside the rest of your infra.

The provider's source tree lives at tools/terraform-provider/. Auto-generated reference docs (the canonical per-resource argument schema) live under tools/terraform-provider/docs/.

Install

The provider is published to the Terraform Registry. Pin a version:

terraform {
  required_providers {
    orbitalreg = {
      source  = "orbitalreg/orbitalreg"
      version = "~> 1.0"
    }
  }
}

For air-gapped installs, use the GoReleaser-built tarballs from each release's GitHub asset list and either drop them into a private registry or wire them via a dev_overrides block in your CLI config.

Provider configuration

provider "orbitalreg" {
  endpoint = "https://orbitalreg.example.com"
  token    = var.orbitalreg_token   # never commit a token literal
}

Or via environment:

export ORBITALREG_ENDPOINT=https://orbitalreg.example.com
export ORBITALREG_TOKEN=orbsa_…

Resources

Resource	Purpose
orbitalreg_project	Top-level governance boundary
orbitalreg_repository	Typed package store inside a project
orbitalreg_service_account	Non-human principal
orbitalreg_service_account_token	Bearer token (created once, captured in state)
orbitalreg_retention_policy	Per-repo prune rules
orbitalreg_security_block	Pattern-match block rule
orbitalreg_webhook_subscription	Outbound HMAC-signed event delivery

Mutability:

• orbitalreg_project — slug, name, description rename in place.
• orbitalreg_repository — slug, name, description rename in place; format / kind force replacement.
• orbitalreg_service_account — name, description rename in place; enabled is mutable; project-id forces replacement.
• orbitalreg_security_block — mutable metadata (reason, cve_id, blocked_until, customer_message) PATCH in place; match expression (block_type, pattern, repo_id) forces replacement so the audit-log invariant holds.
• orbitalreg_retention_policy — name renames in place; repo_id forces replacement.

Data sources

Data source	Lookup keys
orbitalreg_project	slug
orbitalreg_repository	project_id, slug | name
orbitalreg_service_account	project_id, name

Data sources let downstream resources reference an entity managed outside Terraform without copy-pasting UUIDs. For example, a retention policy attached to a hand-created repository:

data "orbitalreg_repository" "external" {
  project_id = "0e2d…"
  slug       = "internal-maven"
}

resource "orbitalreg_retention_policy" "snapshots" {
  repository_id = data.orbitalreg_repository.external.id
  name          = "snapshots-keep-7d"
  rules = jsonencode({
    keep_by_age = {
      max_age_days        = 7
      match_path_regex    = "-SNAPSHOT/"
    }
  })
}

Importing existing state

Each resource supports terraform import:

terraform import orbitalreg_project.acme acme
terraform import orbitalreg_repository.maven 0e2d…/internal-maven
terraform import orbitalreg_retention_policy.snapshots <repo_id>/snapshots-keep-7d

Why use the provider over the operator?

• You already drive the rest of your infra from Terraform
• You want plan output before applying changes (the operator's reconcile is fire-and-forget)
• Your platform's source-of-truth repo is HCL, not YAML

Pick operator instead when:

• Your platform's source-of-truth repo is GitOps YAML (ArgoCD, Flux)
• You need namespace-scoped credential provisioning (the operator's OrbitalRegServiceAccountToken materialises tokens into Secrets)
• You prefer continuous reconciliation over apply-on-trigger

Versioning

Provider major version follows API major version one-to-one (provider 1.x ↔ API v1). Minor releases are forward-compatible within a major.