Forge sources
A forge source answers Terminay's questions about the pull requests and issues on the forge accounts an extension can act as. Terminay uses the answers for the Pull Requests and Issues lists on Home and in project tabs. The bundled Gitea and GitHub extensions are built on this contribution. Added in API 3.7.
Manifest contribution
"api": "^3.7.0",
"permissions": ["network", "forge-source"],
"contributes": {
"forgeSources": [{
"id": "com.terminay.gitea/forge",
"displayName": "Gitea",
"description": "Pull requests and issues on the Gitea servers you have accounts on.",
"kinds": ["pullRequest", "issue"],
"allReach": "readable"
}]
}| Field | Meaning |
|---|---|
id | Required. Namespaced by the extension ID. |
displayName | Required label, at most 96 characters. |
description | Optional, at most 1,024 characters. |
kinds | Required. pullRequest, issue, or both, without repeats. |
allReach | Required. What the all scope covers: readable for everything the account can read (Gitea), or owners for the account's own and its organisations' repositories (GitHub). Where it is owners, Terminay says so beside the All filter and in Settings. |
Requires the forge-source permission. A manifest may declare up to 8.
Runtime contract
Register with context.forges.registerSource(sourceId, runtime). A source is pull-based:
Terminay asks, the source answers one call, and it keeps no list state.
import { defineExtension, defineForgeSource } from '@terminay/extension-api';
export default defineExtension({
activate(context) {
const { credentials } = context.forges;
const source = defineForgeSource({
async accounts(signal) {
// At most one account per origin.
return knownOrigins().map((origin) => account(origin, credentials, signal));
},
async claim(remote, signal) {
const repository = parseRemote(remote.url); // { origin, owner, name } or null
return repository && (await isMyForge(repository.origin, signal)) ? repository : null;
},
async query(query, signal) {
const token = await credentials.token(query.origin);
return searchItems(query, token, signal); // { items, nextCursor?, totalCount? }
},
async detail(reference, signal) {
const token = await credentials.token(reference.origin);
return fetchItem(reference, token, signal); // { summary, body, comments }
},
});
const registration = context.forges.registerSource('com.terminay.gitea/forge', source);
context.subscriptions.add(registration);
context.subscriptions.add(
credentials.onAvailable((origin) => registration.invalidate(origin)),
);
},
});| Method | Returns |
|---|---|
accounts(signal) | The accounts the source can act as, at most one per origin and 32 in all. Each has an HTTPS origin, a login, a credentialSource (environment, cli-config, cli, or sign-in), a state of ready or rejected, and owners: the login and its organisations, at most 50. |
claim(remote, signal) | The { origin, owner, name } repository a Git remote ({ name, url }) maps to on one of the source's origins, or null. The claimed origin's host must be the remote's host. |
query(query, signal) | One page of item summaries for one account's query. |
detail(reference, signal) | One item: its summary, its body (at most 65,536 characters), and at most the 10 most recent comments, oldest first, each with author, createdAt, and body. |
Each call has a 15-second deadline, and its signal aborts when Terminay cancels it.
The registration's invalidate(origin) hints that results for an origin changed;
Terminay refreshes the lists on screen. Registering an undeclared ID, the same ID twice, or after
deactivation is refused.
Queries and pages
TypeScript interface ForgeQuery {
kind: 'pullRequest' | 'issue';
scope: ForgeScope;
state: 'open' | 'merged' | 'closed' | 'all';
origin: string; // the account the query is for
repositories?: { owner: string; name: string }[];
owners?: string[];
text?: string;
cursor?: string;
pageSize: number; // 1 to 50
}
interface ForgePage {
items: ForgeItemSummary[]; // most recently updated first
nextCursor?: string;
totalCount?: number;
}
Field Rule scopeFor pull requests: reviewRequested, authored, involved, or all. For issues: assigned, authored, mentioned, or all. statemerged is valid only for pull requests. repositories, ownersAbsent means unrestricted. When present they are never empty, and hold at most 50 entries. textOptional search text, trimmed, at most 256 characters. Treat it as a search term; it must never widen the query. cursor, nextCursorOpaque to Terminay, at most 1,024 characters. Source cursors never reach clients.
A page holds at most 50 items, most recently updated first. A page may be short and still have a
nextCursor. totalCount is optional; Terminay uses it for badge counts.
forgeScopesFor(kind) and forgeStatesFor(kind) return the valid values.
Item summaries
TypeScript {
reference: { kind: 'pullRequest', origin: 'https://forge.example.net', owner: 'acme', name: 'app', number: 88 },
title: 'Add event stream',
url: 'https://forge.example.net/acme/app/pulls/88',
state: 'open',
author: 'octo',
labels: [{ name: 'feature', color: '0e8a16' }],
comments: 2,
createdAt: '2026-11-01T10:00:00Z',
updatedAt: '2026-11-10T10:00:00Z',
pullRequest: {
headBranch: 'change/13-events',
baseBranch: 'main',
headOwner: 'acme',
headName: 'app',
headCommit: 'abcdef1',
checks: { passed: 1, failed: 1, pending: 0, skipped: 0, total: 2, items: [
{ name: 'build', state: 'passed' },
{ name: 'test', state: 'failed', url: 'https://ci.example.org/build/7' },
] },
},
}
Field Rule referencekind, HTTPS origin, owner and name (no / or whitespace, at most 128 characters), and a positive number. titleNon-blank, at most 512 characters. urlCredential-free HTTPS URL on the item's own origin. statePull requests: open, draft, merged, or closed. Issues: open or closed. authorA login, at most 128 characters. labelsAt most 20, each a name of at most 128 characters and a six-hex-digit color without #. commentsA count. createdAt, updatedAtISO 8601 times. pullRequestRequired for a pull request and refused on an issue. headBranch and baseBranch (at most 256 characters), headOwner and headName (the head repository, which differs for forks), an optional hex headCommit, and optional checks in the worktree property shape. A check's URL may be on any HTTPS origin.
Accounts and credentials
context.forges.credentials is the same per-extension, per-origin token store a worktree insight source uses: token(origin), reject(origin), and onAvailable(listener). - A source may also find accounts in its forge's own CLI configuration or the environment, and reports where each came from in
credentialSource. Only a sign-in account can be removed from Terminay. - When an administrator adds an account with a token, Terminay first asks the extension's sources to claim a probe remote on that origin. If none claims it, the token is not stored.
- Report an account whose token the forge refused as
rejected rather than leaving it out.
Validation
Terminay validates every answer against its question and keeps nothing that fails. These
validators are exported for your tests:
Function Rule validateForgeAccounts(value)Two accounts for one origin refuse the whole list. validateForgeClaim(value, remote)A claim on another host than the remote's is refused. validateForgePage(value, query)Invalid items, and items outside the query's origin, kind, repositories, or owners, are dropped and counted; the rest of the page is kept. A malformed page is refused. validateForgeDetail(value, reference)A detail for a different item is refused. validateForgeSummary(), validateForgeQuery(), validateForgeReference(), validateForgeRepository()The single-value rules above.
sameForgeReference() compares references, ignoring owner and name case.
forgeRemoteHost(url) returns the lower-case host of an HTTPS, SSH, or scp-style remote.
What Terminay owns
The item model is closed. A source sends typed facts and never presentation. Terminay owns how
items look, matching pull requests to open projects' worktrees, and every action that touches Git
or terminals, such as Check out, Start work, and Review with agent. A source never learns about
projects, worktrees, terminals, or clients.
Terminay narrows every query by the caller's authority and the user's settings before it reaches
the source: a client bound to one project only ever queries that project's claimed repositories.
Answers are cached in memory for at most 60 seconds and fetched again when shown, on Refresh, on
focus, and on an invalidate() hint. Nothing refreshes them on a timer, so forge rate
limits are spent only while someone is looking.
There is no dedicated harness. Test with the validators above and the
validForgeManifestFixture, validForgeSourceContributionFixture,
validForgePullRequestFixture, and validForgeIssueFixture fixtures.