Registered forge connections + their bound Projects and health (ADR-0060)

GET

/v1/connections

curl --request GET \
  --url https://example.com/v1/connections

Read-only, and Administer on the Org: a connection spans every Project it serves, so seeing the fleet is an org-level act, not a per-repo one. No credential material is ever returned — only whether the handle resolves.

Responses

200

Media typeapplication/json

Array<object>

One registered forge connection, as global Settings renders it (ADR-0060).

Carries the credential’s handle and whether it resolves — never the material. A connection is the unit an operator reasons about (“is my GitHub App still wired up?”), so the DTO answers that without becoming a way to read a secret back.

object

base_url

required

The API base URL the adapter talks to (GHES / a self-hosted Forgejo).

string

credential_present

required

Does credential_ref actually resolve to material right now? The single most common breakage (a DB restored without its secrets, a reseed that never happened) is invisible until a run fails — this surfaces it.

boolean

credential_ref

required

The _forge-scoped handle the credential lives under. An opaque name, not the secret.

string

id

required

string

kind

required

github | forgejo.

string

last_delivery_at

Unix-ms of the most recent accepted webhook delivery from this forge kind, if any. Deliveries are recorded per kind (the ADR-0046 replay guard is keyed that way), so with two connections of one kind this is a per-kind liveness signal, not a per-connection one.

integer | null format: int64

managed_by_config

required

Is this connection managed declaratively (config-owned) and therefore read-only here (ADR-0060 part D)? A connection has exactly one owner — the connections: config or the database — and this says which, so the UI never offers an edit the next boot would silently revert.

boolean

projects

required

The Projects this connection serves, from its repo bindings — a Project is a binding (ADR-0046), so this is the connection’s whole footprint.

Array<object>

A Project a connection serves, plus the forge coordinate it came from.

object

name

required

string

org

required

string

owner

required

string

project

required

string

supports_preflight

required

Can this connection’s app configuration be checked against what Scarab needs (GET …/preflight)? Decided from the kind, like supports_resync and for the same reason: the check is a live forge round-trip, so the list must not perform one per row just to discover the button is pointless. The endpoint itself remains the authority.

boolean

supports_resync

required

Can the forge enumerate what this credential reaches? Gates the re-sync affordance: GitHub can, so a drifted registry is healable; an adapter that cannot should not offer a button that always errors.

boolean

web_url

required

The forge’s own web host, for deep links out of the UI.

string

Example^generated

[
  {
    "base_url": "example",
    "credential_present": true,
    "credential_ref": "example",
    "id": "example",
    "kind": "example",
    "last_delivery_at": 1,
    "managed_by_config": true,
    "projects": [
      {
        "name": "example",
        "org": "example",
        "owner": "example",
        "project": "example"
      }
    ],
    "supports_preflight": true,
    "supports_resync": true,
    "web_url": "example"
  }
]

403

Requires Administer on the org

404

No connection registry wired