# ForgeConnection

How the Software Factory reaches a git forge other than github.com.

How the Software Factory reaches a git forge other than github.com: a bot account's access token on Gitea, Forgejo or GitLab (or GitHub Enterprise Server), or a GitHub App registered on a GitHub Enterprise Server. github.com is reached through the Vulnesis GitHub App instead (GitHubInstallation). Apply asks the forge what it is and checks the credential can list repositories before anything is stored; the credential and the webhook secret are kept in the tenant's vault as a connector secret, never in the document, an export or a plan. The type, host and account identify the connection and cannot change: declare a new connection instead. Deleting the document removes the webhooks the factory created, revokes the stored credential and marks the connection deleted; managed scope and repository settings rows are kept, read-only, as for an uninstalled App.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `ForgeConnection` |
| Group | [Integrations](/platform-iac/kinds/catalogue.md#integrations) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | many, keyed by `metadata.name` |
| Token and role | An owner, or a service account with the developer role (its ApiKey), or an Authentik access token for either. A member is refused with HTTP 403. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Secret fields | `spec.token`, `spec.app.privateKey`, `spec.oauth.clientSecret`: read on the client from `valueFrom`, sent once, never exported or shown in a plan |
| Terraform resource | [`vulnetix_forge_connection`](/platform-iac/terraform/resources.md#vulnetix_forge_connection), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.168.0 and later. |
| Pinned schema | [`v1.19.1/ForgeConnection.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/ForgeConnection.schema.json) |
| Newest schema | [`latest/ForgeConnection.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/ForgeConnection.schema.json) |
| First released in | [`v1.5.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.5.0) |
| Print the built-in copy | `vulnetix config schema ForgeConnection` |

## Minimal

Only the fields the kind requires. From `examples/ForgeConnection/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/ForgeConnection.schema.json
apiVersion: vulnetix.com/v1
kind: ForgeConnection
metadata:
  name: codeberg
spec:
  type: forgejo
  host: codeberg.org
```

**HCL** (resource `vulnetix_forge_connection`)

```hcl
# Only the arguments the kind requires. From config-schemas examples/ForgeConnection/minimal.yaml.

resource "vulnetix_forge_connection" "codeberg" {
  name = "codeberg"
  host = "codeberg.org"
  type = "forgejo"
}
```

Every field that has a schema default, set to that default: [`terraform/forge_connection.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/forge_connection.tf) and [`yaml/ForgeConnection.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/ForgeConnection.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/ForgeConnection.schema.json
apiVersion: vulnetix.com/v1
kind: ForgeConnection
metadata:
  name: codeberg
spec:
  type: forgejo
  host: codeberg.org
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/ForgeConnection/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/ForgeConnection.schema.json
# A self-managed GitLab group reached with a bot token, with an OAuth
# application so members can link their own GitLab accounts, and a GitHub
# Enterprise Server reached through a GitHub App registered on it.
apiVersion: vulnetix.com/v1
kind: ForgeConnection
metadata:
  name: gitlab-platform
  labels:
    team: platform
  annotations:
    note: The bot account is vulnetix-bot, a Developer in the platform group.
spec:
  type: gitlab
  host: gitlab.example.com
  apiBase: https://gitlab.example.com/api/v4
  account: platform
  token: { env: VULNESIS_GITLAB_TOKEN }
  oauth:
    clientId: 6f1e2d3c4b5a69788796a5b4c3d2e1f0
    clientSecret: { env: VULNESIS_GITLAB_OAUTH_SECRET }
---
apiVersion: vulnetix.com/v1
kind: ForgeConnection
metadata:
  name: ghes-acme
spec:
  type: ghes
  host: github.acme.example
  account: acme
  app:
    appId: 12
    appSlug: vulnetix
    installationId: 3
    privateKey: { env: VULNESIS_GHES_APP_KEY }
```

**HCL** (resource `vulnetix_forge_connection`)

```hcl
# Every argument the kind supports. From config-schemas examples/ForgeConnection/advanced.yaml.

variable "gitlab_platform_oauth_client_secret" {
  type      = string
  sensitive = true
  ephemeral = true
}
variable "gitlab_platform_token" {
  type      = string
  sensitive = true
  ephemeral = true
}
variable "ghes_acme_app_private_key" {
  type      = string
  sensitive = true
  ephemeral = true
}

resource "vulnetix_forge_connection" "gitlab_platform" {
  name     = "gitlab-platform"
  account  = "platform"
  api_base = "https://gitlab.example.com/api/v4"
  host     = "gitlab.example.com"
  oauth = {
    client_id                = "6f1e2d3c4b5a69788796a5b4c3d2e1f0"
    client_secret_wo         = var.gitlab_platform_oauth_client_secret
    client_secret_wo_version = 1
  }
  token_wo         = var.gitlab_platform_token
  token_wo_version = 1
  type             = "gitlab"
  labels = {
    team = "platform"
  }
  annotations = {
    note = "The bot account is vulnetix-bot, a Developer in the platform group."
  }
}

resource "vulnetix_forge_connection" "ghes_acme" {
  name    = "ghes-acme"
  account = "acme"
  app = {
    app_id                 = 12
    app_slug               = "vulnetix"
    installation_id        = 3
    private_key_wo         = var.ghes_acme_app_private_key
    private_key_wo_version = 1
  }
  host = "github.acme.example"
  type = "ghes"
}
```

Every field that has a schema default, set to that default: [`terraform/forge_connection.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/forge_connection.tf) and [`yaml/ForgeConnection.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/ForgeConnection.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
export VULNESIS_GITLAB_TOKEN=...   # read on this machine by valueFrom, never written to the document
export VULNESIS_GITLAB_OAUTH_SECRET=...   # read on this machine by valueFrom, never written to the document
export VULNESIS_GHES_APP_KEY=...   # read on this machine by valueFrom, never written to the document
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/ForgeConnection.schema.json
# A self-managed GitLab group reached with a bot token, with an OAuth
# application so members can link their own GitLab accounts, and a GitHub
# Enterprise Server reached through a GitHub App registered on it.
apiVersion: vulnetix.com/v1
kind: ForgeConnection
metadata:
  name: gitlab-platform
  labels:
    team: platform
  annotations:
    note: The bot account is vulnetix-bot, a Developer in the platform group.
spec:
  type: gitlab
  host: gitlab.example.com
  apiBase: https://gitlab.example.com/api/v4
  account: platform
  token: { env: VULNESIS_GITLAB_TOKEN }
  oauth:
    clientId: 6f1e2d3c4b5a69788796a5b4c3d2e1f0
    clientSecret: { env: VULNESIS_GITLAB_OAUTH_SECRET }
---
apiVersion: vulnetix.com/v1
kind: ForgeConnection
metadata:
  name: ghes-acme
spec:
  type: ghes
  host: github.acme.example
  account: acme
  app:
    appId: 12
    appSlug: vulnetix
    installationId: 3
    privateKey: { env: VULNESIS_GHES_APP_KEY }
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Secret | Description |
|---|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` |  | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `ForgeConnection` |  | Always ForgeConnection. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys |  |  |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` |  | The object's name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name. |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` |  | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` |  | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) |  | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | yes |  | no other keys |  |  |
| <span id="spec-type"></span>`spec.type` | string | yes |  | `ghes`, `gitea`, `forgejo`, `gitlab` |  | The forge software. Gitea and Forgejo speak one API, so the server keeps whichever of the two the host answers as, and a plan does not count the other spelling as a change. |
| <span id="spec-host"></span>`spec.host` | string | yes |  | not `github.com`, `www.github.com`, `api.github.com`; pattern `^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?(:[0-9]{1,5})?$`; length 1 to 253 |  | The forge's host name, with a port when it is not 443: git.example.com, codeberg.org, gitlab.example.com:8443. No scheme or path. It is stored lower case. |
| <span id="spec-apiBase"></span>`spec.apiBase` | string | no |  | pattern `^https://`; format `uri`; length 0 to 1024 |  | The REST base, when it is not the forge's default (https://<host>/api/v4 for GitLab, /api/v1 for Gitea and Forgejo, /api/v3 for GitHub Enterprise Server). It must be https on the same host. |
| <span id="spec-account"></span>`spec.account` | string | no |  | length 1 to 255 |  | The organisation, group or user the connection is for. Left out, the connection covers every repository the credential reaches. |
| <span id="spec-token"></span>`spec.token` | object | no |  | 1 to 1 keys; no other keys | yes | Where the client reads the bot account's access token. Required when the connection is created, unless app is set; left out afterwards, the stored token is kept. The token is checked against the forge at apply. |
| <span id="spec-token-env"></span>`spec.token.env` | string | no |  | pattern `^[A-Za-z_][A-Za-z0-9_]*$` |  | Name of an environment variable. |
| <span id="spec-token-file"></span>`spec.token.file` | string | no |  | length 1 to any |  | Path to a file holding the value. Trailing newlines are trimmed. |
| <span id="spec-app"></span>`spec.app` | object | no |  | no other keys |  | A GitHub App registered on the GitHub Enterprise Server, instead of a bot token. ghes only. |
| <span id="spec-app-appId"></span>`spec.app.appId` | integer | yes |  | >= 1 |  | The App's id on the server. |
| <span id="spec-app-appSlug"></span>`spec.app.appSlug` | string | no |  | pattern `^[a-z0-9][a-z0-9-]{0,99}$` |  | The App's slug, which names the bot that commits (<slug>[bot]). |
| <span id="spec-app-installationId"></span>`spec.app.installationId` | integer | yes |  | >= 1 |  | The App's installation on the account. |
| <span id="spec-app-privateKey"></span>`spec.app.privateKey` | object | no |  | 1 to 1 keys; no other keys | yes | Where the client reads the App's private key (PEM). Required when the connection is created; left out afterwards, the stored key is kept. |
| <span id="spec-app-privateKey-env"></span>`spec.app.privateKey.env` | string | no |  | pattern `^[A-Za-z_][A-Za-z0-9_]*$` |  | Name of an environment variable. |
| <span id="spec-app-privateKey-file"></span>`spec.app.privateKey.file` | string | no |  | length 1 to any |  | Path to a file holding the value. Trailing newlines are trimmed. |
| <span id="spec-oauth"></span>`spec.oauth` | object | no |  | no other keys |  | An OAuth application made on the forge, so that members can link their own forge account to the connection: their commits from a factory page then carry an email the forge verifies, and their signing key can be added to their forge account. Each member signs in for themselves from the console. Register the redirect URI the object's status reports (status.oauthRedirectUri) on the application. Left out, the application stored on the connection is removed. |
| <span id="spec-oauth-clientId"></span>`spec.oauth.clientId` | string | yes |  | length 1 to 200 |  | The application's client id. |
| <span id="spec-oauth-clientSecret"></span>`spec.oauth.clientSecret` | object | no |  | 1 to 1 keys; no other keys | yes | Where the client reads the application's client secret. Required when sign-in is first set up; left out afterwards, the stored secret is kept. |
| <span id="spec-oauth-clientSecret-env"></span>`spec.oauth.clientSecret.env` | string | no |  | pattern `^[A-Za-z_][A-Za-z0-9_]*$` |  | Name of an environment variable. |
| <span id="spec-oauth-clientSecret-file"></span>`spec.oauth.clientSecret.file` | string | no |  | length 1 to any |  | Path to a file holding the value. Trailing newlines are trimmed. |

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): it shows each object as create, update, delete or no change, with a `planHash` that apply then holds to. Apply writes in one transaction.
- **Manager.** Each object records the manager that applied it (`terraform`, `console` or `gitops:<repo>`). `--prune` deletes only objects its own manager owns. See [The manager](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Status.** `connection`, `botLogin` and `version`. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).

## How apply treats it

The Resolve Platform's create and update writers, now transaction scoped. A bot token or a GitHub Enterprise Server App key is a `valueFrom` secret, kept as the Resolve Platform keeps it. GitHub.com is refused: use [`GitHubInstallation`](/platform-iac/kinds/git-hub-installation.md).

## Terraform and OpenTofu

The resource is `vulnetix_forge_connection` in the `vulnetix/resolve` provider. Its arguments are the `spec` in snake case, beside `name`, `labels` and `annotations` from `metadata`. The Minimal and Advanced HCL are above. The provider's own reference is [vulnetix_forge_connection](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/forge_connection).

Import an object that already exists by its name:

```shell
# Import an existing ForgeConnection by its name (metadata.name).
terraform import vulnetix_forge_connection.codeberg codeberg
```

A secret is two arguments, never stored in the plan or the state: `token_wo` (write-only) and `token_wo_version`, `private_key_wo` (write-only) and `private_key_wo_version`, `client_secret_wo` (write-only) and `client_secret_wo_version`. Change the version number to send a new value. See [Secrets](/platform-iac/terraform.md#secrets).

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
