fremforges provider til Terraform og OpenTofu

fremforge-provideren styrer din organisations fremforge-indstillinger fra OpenTofu eller HashiCorp Terraform: godkendelses- og adgangspolitik, IP-tilladelseslisten, scannings- og scannerpolitik, uforanderlige releases, signaturregler for images og pakker, afhængighedsproxyen, pakkeadgang og registry-robotter.

Repositories, teams og regler for branchbeskyttelse er Forgejo-objekter og bliver hos community-provideren svalabs/forgejo, som beskrevet i Konfiguration som kode. De to providere fungerer side om side i én konfiguration.

Installation

Provideren er udgivet på selve frem.sh, så begge CLI’er installerer den uden ekstra opsætning:

terraform {
  required_providers {
    fremforge = {
      source  = "frem.sh/fremforge/fremforge"
      version = "~> 0.1"
    }
  }
}

tofu init (eller terraform init) finder registret på https://frem.sh/.well-known/terraform.json, henter zip-filen til din platform fra cli.frem.sh og kontrollerer den mod SHA256SUMS, hvis OpenPGP-signatur verificeres med fremforges release-nøgle. Der findes builds til Linux og macOS (amd64, arm64) samt Windows (amd64).

Release-nøglen:

Den private nøgle forlader aldrig fremforge-platformen: hver release signeres af platformen, og kun for providerens release-build.

Opsætning

provider "fremforge" {
  # endpoint = "https://frem.sh/_app/api/v1"   # the default
}

Provideren læser sit token fra FREMFORGE_TOKEN. Brug et API-token til organisationen for den organisation, du styrer, oprettet under Administration → API-tokens (frem.sh/<org>/_admin/api-tokens), med de scopes, dine ressourcer kræver. Hav et skrivebeskyttet token til plan og skrive-scopet til det job, der kører apply:

Ressourcer

Organisationsindstillinger er singletons: alle organisationer har dem altid, og API’et har ingen sletning. Alle argumenter er valgfrie. Kun de argumenter, du sætter, bliver skrevet; de øvrige læses tilbage i state og lades i fred, så en ændring, som nogen laver i konsollen af en indstilling, du ikke styrer, er ikke drift. Importér en singleton med organisationens slug.

Hver singleton er også en datakilde med samme navn.

Samlinger har rigtig oprettelse og sletning:

Et pakkenavn kan indeholde / (et npm-scope, en container-sti), og derfor står det sidst i import-ID’erne.

Eksempel

resource "fremforge_auth_policy" "this" {
  org                   = "acme"
  max_pat_lifetime_days = 30
  allow_user_pats       = false
  ssh_disabled          = true
}

resource "fremforge_ssh_ca" "this" {
  org          = "acme"
  ca_keys      = [file("ssh-ca.pub")]
  require_cert = true
}

resource "fremforge_scan_policy" "images" {
  org            = "acme"
  scanner        = "image_scan"
  mode           = "enforce"
  block_severity = "high"
}

Fjernede indstillinger

To indstillinger blev fjernet fra fremforge den 2026-10-14, fordi de blev gemt, men aldrig anvendt: principal_policy på fremforge_ssh_ca og default_template_repo på fremforge_branch_protection_defaults. Siden provider 0.1.1 er begge attributter forældede: provideren hverken sender eller læser dem, så en konfiguration, der stadig sætter dem, virker fortsat og giver en ren plan, og tofu plan udskriver en advarsel om, at de er forældede. Fjern dem fra din konfiguration; intet ændrer sig, når du gør det. Se Branchbeskyttelse og SSH-certifikatmyndighed.

Scoped CI-secrets: værdien kommer aldrig i state

fremforge_ci_secret (fra provider 0.9.0) styrer én scoped CI-secret. Værdien er et write-only-argument, value_wo: den sendes, når secreten oprettes, og ved hver ændring (API’et erstatter værdi og scope samlet), og den læses aldrig tilbage og gemmes aldrig i plan eller state. Write-only-argumenter kræver OpenTofu 1.11 eller Terraform 1.11 eller nyere. repository_id udelades for hele organisationen; hæv value_wo_version for at skrive en ny værdi.

variable "deploy_key" {
  type      = string
  sensitive = true
  ephemeral = true
}

resource "fremforge_ci_secret" "deploy" {
  org              = "acme"
  name             = "DEPLOY_KEY"
  repository_id    = 42
  value_wo         = var.deploy_key
  value_wo_version = 1
  workflows        = ["deploy.yaml"]
  refs             = ["refs/heads/main"]
  events           = ["push", "workflow_dispatch"]
  environment      = "production"
}

• Rotation: fremforge kan ikke vise værdien, så en ny value_wo alene er ikke en ændring. Hæv value_wo_version for at skrive den.
• Drift: en ændring af scope eller beskrivelse foretaget uden for din konfiguration vises i planen; en ændring af værdien gør ikke.
• Oprettelse overtager aldrig: findes der allerede en secret med det navn og repository, fejler apply og beder dig importere den.
• Import: <org>/<NAME> for en secret for hele organisationen, <org>/<repository id>/<NAME> for en, der er bundet til et repository. Sæt value_wo i konfigurationen før næste apply.
• Token-scopes: providerens token skal have ci-secrets:read og ci-secrets:write.

Scope-argumenterne afvises, før der sendes en forespørgsel, når de kunne udvide leveringen: et tomt element, et reserveret navn (FORGEJO_, GITHUB_, GITEA_) eller et repository-id, der ikke er et positivt tal.

Tokens til registry-robotter havner aldrig i state

API’et viser en registry-robots token én gang, når det udstedes. Provideren gemmer det aldrig i state, i nogen attribut. Den skriver tokenet én gang, når API’et udsteder det (ved oprettelse, og hver gang du ændrer rotation), til den fil, du angiver i token_file, med mode 0600, og overskriver aldrig en eksisterende fil:

resource "fremforge_registry_robot" "ci" {
  org        = "acme"
  name       = "ci-pull"
  access     = "read"
  token_file = "${path.module}/.robot-ci.token"
  rotation   = "2026-10"   # change to issue a new token; the old one is revoked at once
}

Uden token_file kasseres tokenet. Flyt filen væk, før du roterer igen.

Drift, import og destroy

• Drift: plan -detailed-exitcode afslutter med 2, når en indstilling, du styrer, er ændret uden for din konfiguration; apply sætter den tilbage.
• Import: import { to = fremforge_auth_policy.this; id = "acme" }, hvorefter tofu plan -generate-config-out=generated.tf skriver konfigurationen for dig.
• Destroy: for en singleton fjerner destroy den kun fra state og ændrer intet i organisationen: at skrive standardværdier ville i det stille svække en sikkerhedsindstilling. Samlinger slettes. fremforge_package_access fjerner pakkens indstillinger og alle tildelinger på den.

Skift fra modulet

Modulet forbliver dokumenteret, mens du skifter. For hver indstilling: tilføj providerens ressource, importér den med organisationens slug, tjek at plan ikke viser ændringer, fjern så modulets argument, og kør tofu state rm på dets restful_resource.

Sådan tester vi den

Ved hver ændring kører alle ressourcer og datakilder gennem den rigtige OpenTofu-CLI mod et optaget fremforge-API: kun de argumenter, du sætter, bliver skrevet, ændringer, der ikke styres, ignoreres, drift i det, der styres, kommer med i planen, import læser samme state tilbage, og destroy opfører sig som beskrevet ovenfor.

De indstillinger, der er sikre at ændre på en delt organisation, kører også live mod en testorganisation hver nat: apply, en ren plan, en ændring foretaget via API’et, en plan, der viser den, apply, import i en frisk state, en ren plan, destroy, en tilbagelæsning og gendannelse af den oprindelige værdi. Det gælder godkendelsespolitikken, SSH-CA’en, SLA-politikken og afhængighedsproxyens metadatafilter; pakkeadgang, beskyttelsesregler og registry-robotter blev kørt live på samme måde før udgivelsen. IP-tilladelseslisten og signaturpolitikkerne testes kun mod det optagede API, fordi en ændring af dem på en delt organisation ville forstyrre andre tests.