Files
paseo/docs/forge-providers.md
T
Mohamed Boudra cf9eaa8d29 Forge links use the daemon-resolved host and parent repository (#9576)
* fix(forge): build web links from the host and repository the daemon resolves

The app built forge links by parsing the origin remote itself, so an SSH
config alias (git@github.com-work:...) produced https://github.com-work/...
and a fork checkout sent #123 to the fork instead of the repository that owns
the numbers.

The daemon now publishes `forgeWeb` { host, referenceRepository? } on the
workspace descriptor and on checkout status, and the app builds every forge URL
from it. The host is the ssh -G resolved cloud host. referenceRepository is the
fork's parent, read through an optional ForgeService.getReferenceRepository
(GitHub, GitLab, Gitea family). Branch and file links stay on the origin
repository because a feature branch usually exists only on the fork.

Old daemons omit the field and the app derives links from the remote as before
(tagged COMPAT(forgeWeb)).

* fix(forge): keep the published web location tied to its remote and retry failed parent lookups

- A web location resolved for one origin remote is no longer published after
  `git remote set-url`; it returns when the next forge refresh resolves the new remote.
- The GitHub parent lookup rejects on a gh failure instead of returning null, so a
  network error is retried rather than cached as "this repository has no parent".
- The pull request status poll retries a due lookup, so an idle workspace recovers
  without waiting for a forced refresh.
- Workspace snapshot fixtures now expect `forgeWeb` for github.com remotes.

* fix(forge): look up a fork's parent once per remote, on any checkout

- A successful parent lookup is kept for the life of the remote instead of being repeated by every
  forced refresh (each push, fetch and branch switch).
- The lookup no longer waits on the pull request status's auth state, which is "no_remote" on a
  detached HEAD; a failed or signed-out lookup is retried on the next forced refresh or poll.

* fix(forge): resolve the new remote's web location when origin changes

`git remote set-url` reaches the daemon as a git-only refresh, which stopped publishing the old
remote's forgeWeb but never resolved the new one, so links fell back to parsing the remote.
A git refresh that finds the remote changed since the last forge refresh now runs a forced forge
refresh, which also probes a newly seen SSH alias.

* fix(forge): keep the alias-resolved host when a failed parent lookup is retried

The poll's retry resolved the forge with the synchronous resolver, which reports the raw SSH alias
as the host. A lookup that settled on retry then published and kept `github.com-work` as the web
host. The retry now uses the async resolver, like the forge refresh, so the host means the same
thing on both paths.

* fix(forge): treat a Gitea or GitLab API error body as a failed parent lookup

`tea api` exits 0 on HTTP errors, so an error body parsed as a repository without a parent and was
cached as "not a fork". The repository schemas now require the repository's own name, so an error
body rejects and the lookup is retried. The shorthand provider also keys its context on the
forgeWeb strings, so unrelated workspace updates no longer re-render every Markdown message.

* fix(forge): keep the parent lookup off the workspace refresh path

* fix(forge): keep a parent answer that lands during a refresh

* test(forge): make the parent lookup tests Windows-safe

* fix(forge): drain the background parent lookup on dispose

* test(forge): retry temp cleanup after the poll lookup on Windows
2026-11-13 19:59:42 +07:00

13 KiB

Adding a Git Forge to Paseo

Paseo's forge layer is a registry/manifest system. A forge is a runtime concern: shared protocol messages carry neutral/open facts, the server adapter owns behavior, and the app owns bundled presentation/runtime interpretation.

The maintainer litmus test is the rule of thumb:

Adding a new forge means adding files in a new directory/module that implement an interface, plus one entry in the centralized registry/manifest for that package.

The Three Registrations

For forge acme, the expected end state is:

  1. Protocol manifest - optional, only when the forge should be presented by shared manifest data. Add one ForgeDefinition to packages/protocol/src/forge-manifest.ts.

  2. Server adapter - add packages/server/src/services/acme-service.ts implementing ForgeService, any adapter-owned fact types/guards/constants beside it, and one defaultForgeRegistry entry in packages/server/src/services/forge-registry.ts.

  3. App modules - a forge splits into a pure logic half and a view half so logic consumers (URL builders, merge-capability, native checks, and the Node-based e2e harness) never pull the client rendering stack:

    • packages/app/src/git/forges/acme.ts - logic: id, optional urlGrammar (source links and pasted issue/change-request reference paths), optional facts (schema, merge-capability, native-check fallbacks). No React/React-Native imports. Register in CLIENT_FORGE_LOGIC_MODULES in packages/app/src/git/forges/index.ts.
    • packages/app/src/git/forges/acme.view.tsx - view: icon (SVG component under packages/app/src/components/icons/), optional brandColor, optional paneContributions. Register in CLIENT_FORGE_VIEW_MODULES in packages/app/src/git/forges/view.ts.

There should be no protocol typed-union arm, no central app icon/color/url/facts map, and no central server union of known forge facts.

Protocol

forgeSpecific on PR status is an open envelope:

z.object({ forge: z.string() }).passthrough();

The forgeSpecific.forge field is a facts-family tag, not the workspace brand id. Gitea, Forgejo, and Codeberg can all emit forgeSpecific.forge === "gitea" when they share the same facts shape, while top-level status.forge keeps the brand id ("gitea", "forgejo", "codeberg").

Protocol does not validate per-forge fact fields. Consumers that understand a facts family validate at runtime with their own schema/guard. Unknown or schema-mismatched facts render neutrally instead of failing the whole message parse. This is the version-skew win: an old client can receive facts from a newer forge and still show the PR/MR in a neutral state.

Check results keep a stable normalized status for aggregation and an optional open traits: string[] for composable forge-neutral refinements such as manual, action_required, and warning. Consumers ignore unknown traits and fall back to status; rawStatus preserves provider-native detail. Do not add provider vocabulary to the normalized status union. Producers and the presentation layer share the trait constants in packages/protocol/src/check-traits.ts — use those instead of string literals so classification and emission cannot drift apart.

Shipped GitHub compatibility stays separate:

  • The forge compatibility layer first shipped in v0.2.0-beta.1. Its initial six-month cleanup target is 2027-01-17, after supported client and daemon floors reach stable v0.2.0.
  • status.github remains accepted for released peers.
  • The server keeps the COMPAT(forgeSpecific) mirror that copies GitHub facts into status.github for older clients.
  • Do not add a compatibility shim unless a released peer (<= 0.1.102) can actually produce the state.

Server

The server-wide status type only promises:

type ForgeSpecificStatusFacts = { forge: string } & Record<string, unknown>;

Adapter-owned files define the typed shapes and guards, for example github-facts.ts, gitlab-facts.ts, and gitea-facts.ts. The adapter can keep strong internal types for construction and command guards, but shared server code must not grow a central list of forge fact arms.

Register the adapter in defaultForgeRegistry with:

  • createService
  • matchesHost from manifest cloudHosts
  • probeHost when self-hosted/Enterprise detection is supported

Current change-request lookup matches the branch and repository for both open and terminal requests. Prefer an open request, then a terminal request at the local HEAD, then the most recently updated terminal request. A reused branch can show its previous request until a new one opens. Auto-archive separately requires an observed open-to-merged transition and a fresh exact match between checkout HEAD and the PR head, along with the existing workspace safety checks.

Keep checkout HEAD in adapter cache and poll identities so checkout changes refresh the facts used by archive eligibility.

Cloud hosts in the manifest are a bounded public-host list, not a self-host allowlist. Self-hosted detection is a trust gate: Paseo only talks to a forge host that is either a known cloud host or one the CLI is already authenticated to. Adapter probes must not make anonymous HTTP requests to remote-derived hosts, and adapters must not route credentials to an unauthenticated host.

The daemon publishes forgeWeb on the workspace descriptor and on checkout_status_response. The app builds every forge URL from it instead of parsing origin itself.

  • host is the browsable host: an ssh -G alias such as github.com-work and a cloud SSH host such as ssh.github.com resolve to the cloud host; self-hosted hosts pass through.
  • referenceRepository is the repository that owns issue and change-request numbers: the parent when origin is a fork. #123 links there; owner/repo#123 keeps the repository you wrote.
  • Branch and file links stay on the origin repository. A feature branch usually exists only on the fork.

An adapter opts into referenceRepository with the optional ForgeService.getReferenceRepository. GitHub reads parent from gh repo view, GitLab reads forked_from_project from glab api, and the Gitea family reads parent from tea api. The lookup always names the origin repository explicitly, so it does not depend on gh's default-repository choice, and it rejects on any CLI failure. packages/server/src/server/forge-web.ts keeps a successful answer for as long as the remote stays the same. The first snapshot publishes { host } immediately and the reference repository follows in a later update, so a slow or signed-out forge CLI never holds back the checkout's git state or pull request status. A failed lookup (signed out, network down) leaves links on origin and is retried by the next refresh or pull request status poll once a minute has passed.

Daemons older than v0.16.0 omit the field; the app then derives the host from the remote and links #N to origin. That fallback is tagged COMPAT(forgeWeb) in packages/app/src/git/forge-url.ts.

App

Each app forge splits into two modules so pure logic never imports the client rendering stack:

acme.ts exports a ClientForgeLogicModule:

  • id
  • optional urlGrammar (including referencePaths for composer auto-attachment and Markdown shorthand references)
  • optional facts registration (schema, merge-capability, native-check fallbacks)

acme.view.tsx exports a ClientForgeViewModule:

  • id
  • icon
  • brandColor (null for neutral; GitHub intentionally uses null)
  • optional paneContributions

Two registries live under packages/app/src/git/forges/: CLIENT_FORGE_LOGIC_MODULES (index.ts) drives URL grammar, merge-capability derivation, and native fallback checks; CLIENT_FORGE_VIEW_MODULES (view.ts) drives icon/color lookup and PR-pane contributions. Logic consumers must import the logic registry only — importing the view registry (or a .view.tsx module) from a logic path pulls react-native and breaks the Node-based e2e harness.

Per-forge brand colors live on the module, not in styles/theme.ts. Use the Unistyles-safe pattern from docs/unistyles.md: no useUnistyles(). Brand icon call sites use withUnistyles and a uniProps mapping such as:

(theme) => ({ color: theme.colorScheme === "light" ? colors.light : colors.dark });

Facts modules use one source of truth: a Zod schema. Helpers like defineForgeFacts, defineNativeFallbackCheck, and definePaneContribution derive guards from schema.safeParse and re-parse before invoking typed derivers/renderers. That keeps typed derivers away from the open wire envelope.

Checklist

To add acme:

  1. Add acme to FORGE_DEFINITIONS if the shared manifest should know its label, nouns, icon kind, sign-in CLI, or cloud hosts.
  2. Add acme-service.ts implementing ForgeService.
  3. Add acme-facts.ts beside the adapter if it reports native facts.
  4. Add one defaultForgeRegistry entry.
  5. Add packages/app/src/git/forges/acme.ts (logic) and packages/app/src/git/forges/acme.view.tsx (view).
  6. Add one CLIENT_FORGE_LOGIC_MODULES entry (index.ts) and one CLIENT_FORGE_VIEW_MODULES entry (view.ts).
  7. Add/update the icon component only if the client bundle should show a brand mark.
  8. If the forge's CI/data model does not fit an existing required ForgeService field, widen the shared interface (plus the protocol schema and its guards) instead of faking a value — e.g. Gitea Actions runs carry no check-run id, so GetCheckDetailsOptions.checkRunId became optional with workflowRunId as the alternative address. Expect this step to touch forge-service.ts, messages.ts, and the call-site guards of the other adapters. Widening a shared field is not forge-local: it also affects the already-shipped forges/GitHub call sites and the capability-gated RPC (e.g. forgeCheckDetails), so verify every consumer rather than assuming the change only reaches the new adapter.
  9. Run targeted tests: manifest/registry/resolver, the adapter test, protocol checkout PR schema, app forge URL/presentation tests, app merge capability, and any PR-pane native data tests touched.

Run npm run typecheck after each implementation slice. If protocol or client declarations are stale, run npm run build:client; if server/CLI declarations are stale, run npm run build:server.

Gotchas

  • GitHub is a normal registry entry plus released compatibility shims. Keep all real shims tagged with COMPAT(name).
  • Gitea-family facts use forgeSpecific.forge === "gitea" even when the top-level brand is Forgejo or Codeberg.
  • Gitea's legacy Actions task endpoint cannot filter by commit, may enforce a page size below the requested limit, and omits rerun-attempt numbers. Walk a bounded number of pages using total_count and filter locally. Preserve ambiguous same-run tasks: display names are not stable job identities, so name-based deduplication can hide a real failure.
  • A blocked Gitea Actions task is not necessarily manual: only add the action_required trait when the matching run metadata reports need_approval.
  • Brand icons are bundled React components, so they cannot come from protocol manifest data.
  • Source URL grammars are app-side because blob/tree path syntax is forge-specific. If a forge has no grammar, omit the "Open on ..." source link rather than constructing a wrong URL.
  • Pasted issue/change-request URL recognition is also app-side and registry driven. Put the forge's route infixes in urlGrammar.referencePaths; the neutral extractor matches the pasted host and full repository path against the current remote before it invokes cwd-routed forge search. Do not add a central forge switch or guess a self-hosted Gitea-family brand from URL shape.
  • Shorthand references in rendered Markdown (#12, GitLab and Gitea !12, cross-repository owner/repo#12) come from the sigil on each referencePaths entry. Leave sigil off a kind the forge does not link in prose: GitHub has no !, and its # targets /issues/, which GitHub redirects to the pull request. packages/app/src/git/forge-shorthand builds the recognition pattern from the workspace descriptor's forge and remote.
  • GitLab pipeline status constants belong to the GitLab adapter/client module, not protocol.
  • GitLab manual jobs need allow_failure to distinguish optional gray jobs (manual) from blocking jobs (manual plus action_required). A failed allowed-failure job carries the warning trait, and canceling remains active until GitLab reports a terminal status.
  • GitHub PR polling owns one account-wide GraphQL budget. Coordinate retained targets per host, batch their reads, and stop until GitHub's reset time when the reserve is exhausted. Never add a per-target GitHub request to the poll path. Resolve fork PRs through their parent repository without abandoning the shared batch.