--- title: "Data model" description: "The objects that providers return, and the helpers for their keys." canonical_url: "https://forges.link/reference/data-model" --- # Data model > The objects that providers return, and the helpers for their keys. Every provider returns these shapes, whatever the forge. See [Data model](https://forges.link/concepts/data-model) for how they fit together. Most objects also carry `raw`, which is the forge's own representation of the object, unchanged. A normalised value often has a `Raw` twin that holds the forge's own value, such as `stateRaw` beside `state`. Events carry the unchanged delivery as `payload`. These fields are not listed below. ## Forges and refs ### `ForgeKind` Identifier of a forge implementation. Unknown forges are permitted so that third-party providers can be registered without a core release. **one of:** - [`KnownForgeKind`](https://forges.link/reference/data-model#knownforgekind) - `(string & {})` ### `KnownForgeKind` The forges this package ships providers for. **one of:** - `'github'` - `'gitlab'` - `'bitbucket'` - `'forgejo'` - `'gitea'` - `'tangled'` - `'gitee'` - `'azure-devops'` - `'cursor-origin'` - `'pushin'` - `'cloudflare-artifacts'` ### `ForgeInstance` Host of a single forge deployment, for example `github.com` or `codeberg.org`. **type:** `string` ### `ForgeOrigin` Where an object comes from: the forge and the instance of that forge.

Member	Type	Description
`forge`	`ForgeKind`
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` .

### `ThreadKind` Kind of thread. `'other'` holds forge-specific subjects with no shared kind (check suites, epics); `ThreadRef.typeRaw` names them. **one of:** - `'issue'` - `'pull_request'` - `'discussion'` - `'commit'` - `'other'` ### `RepoRef` Addresses a repository by its forge, instance, owner and name. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`owner`	`string`	Full namespace path. On forges with nested groups (GitLab) this contains slashes, for example `acme/platform` ; `name` never does.
`name`	`string`	Repository name. Empty for namespace-scoped refs.
`kind?`	`'repo' \| 'namespace'`	`'namespace'` for subjects that belong to a group rather than a repository (GitLab epics). Absent means a repository.
`externalId?`	`string`	Stable forge-native identifier that survives renames and transfers: a GitHub, Forgejo or Gitea numeric id, a GitLab project or group id, a Bitbucket UUID or a Tangled repo DID. `repoKey` prefers it over `owner` and `name` .
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `ThreadRef` Reference to a thread. A thread `number` is unique only within its repo, so the repo is always carried alongside it. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`repo`	`RepoRef`
`kind`	`ThreadKind`
`number?`	`string`	Per-repo thread number, the commit sha for `kind: 'commit'` , or the forge-native id for `kind: 'other'` . Absent when the forge did not identify the thread; such a ref cannot be fetched or keyed until enriched.
`displayNumber?`	`string`	Human-facing per-repo number, when it differs from `number` . Tangled identifies threads by AT-URI but shows numbers in its UI and webhooks.
`externalId?`	`string`	Globally unique forge-native identifier, where one exists: a GitHub `node_id` , a GitLab global id, or an atproto record URI.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `ResolvedThreadRef` A thread ref whose number is known, and which can therefore be keyed and fetched. Every thread, comment and review read from a forge carries one. **extends:** [`ThreadRef`](https://forges.link/reference/data-model#threadref)

Member	Type	Description
`number`	`string`	Per-repo thread number, the commit sha for `kind: 'commit'` , or the forge-native id for `kind: 'other'` .
`repo`	`RepoRef`	Inherited from `ThreadRef` .
`kind`	`ThreadKind`	Inherited from `ThreadRef` .
`displayNumber?`	`string`	Human-facing per-repo number, when it differs from `number` . Tangled identifies threads by AT-URI but shows numbers in its UI and webhooks. Inherited from `ThreadRef` .
`externalId?`	`string`	Globally unique forge-native identifier, where one exists: a GitHub `node_id` , a GitLab global id, or an atproto record URI. Inherited from `ThreadRef` .
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `CommentRef` Reference to a comment on a thread. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`thread`	`ThreadRef`
`id`	`string`	Forge-native comment id; an AT-URI on Tangled.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `ResolvedCommentRef` A comment ref whose thread is resolved, and which can therefore be keyed. Every comment read from a forge carries one. **extends:** [`CommentRef`](https://forges.link/reference/data-model#commentref)

Member	Type	Description
`thread`	`ResolvedThreadRef`
`id`	`string`	Forge-native comment id; an AT-URI on Tangled. Inherited from `CommentRef` .
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `NotificationRef` Reference to a notification. Distinct from [`ThreadRef`](https://forges.link/reference/data-model#threadref): a notification is a per-user delivery record whose lifetime and identity are independent of the thread it points at. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`id`	`string`	Forge-native notification identifier, used for read/done/unsubscribe writes.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `repoKey()` Stable identity key for a repository: by `externalId` when known, so renames and transfers keep the key, otherwise by path, lowercased on forges that ignore case. A hand-built ref without `externalId` therefore keys differently from the same repo as a provider returns it. ```ts function repoKey(repo: RepoRef): string ```

Parameter	Type
`repo`	`RepoRef`

**Returns:** `string` ### `parseRepoKey()` Reads a [`repoKey`](https://forges.link/reference/data-model#repokey) back. Keys built from an `externalId` carry no path, so `owner` and `name` are empty on those. ```ts function parseRepoKey(key: string): RepoRef | undefined ```

Parameter	Type
`key`	`string`

**Returns:** [`RepoRef | undefined`](https://forges.link/reference/data-model#reporef) ### `repoSlug()` The `owner/name` people read and type; the owner alone for a namespace. ```ts function repoSlug(repo: RepoRef): string ```

Parameter	Type
`repo`	`RepoRef`

**Returns:** `string` ### `repoRef()` The ref of a repository on `origin` from the `owner/name` that people type. The name is what follows the last slash, so a GitLab subgroup stays in `owner`. **Example** ```ts const repo = repoRef(provider, 'acme/widgets') ``` ```ts function repoRef(origin: ForgeOrigin, slug: string): RepoRef ```

Parameter	Type	Description
`origin`	`ForgeOrigin`	The forge and instance, such as a provider.
`slug`	`string`	The repository, such as `acme/widgets` or `acme/platform/widgets` .

**Returns:** [`RepoRef`](https://forges.link/reference/data-model#reporef) **Throws:** - {TypeError} When `slug` has no owner or no name. ### `threadKey()` Stable identity key for a thread. `'other'` threads are keyed by their forge-native type so unrelated subjects with the same id never collide. ```ts function threadKey(thread: ResolvedThreadRef): string ```

Parameter	Type
`thread`	`ResolvedThreadRef`

**Returns:** `string` ### `parseThreadKey()` Reads a [`threadKey`](https://forges.link/reference/data-model#threadkey) back. ```ts function parseThreadKey(key: string): ResolvedThreadRef | undefined ```

Parameter	Type
`key`	`string`

**Returns:** [`ResolvedThreadRef | undefined`](https://forges.link/reference/data-model#resolvedthreadref) ### `threadSlug()` `acme/widgets#42`, or `acme/widgets@abc1234` for a commit; uses the display number where the forge has one. ```ts function threadSlug(ref: ThreadRef): string ```

Parameter	Type
`ref`	`ThreadRef`

**Returns:** `string` ### `commentKey()` Stable identity key for a comment: the [`threadKey`](https://forges.link/reference/data-model#threadkey) of its thread and the comment's forge-native id. ```ts function commentKey(ref: ResolvedCommentRef): string ```

Parameter	Type
`ref`	`ResolvedCommentRef`

**Returns:** `string` ### `parseCommentKey()` Reads a [`commentKey`](https://forges.link/reference/data-model#commentkey) back. ```ts function parseCommentKey(key: string): ResolvedCommentRef | undefined ```

Parameter	Type
`key`	`string`

**Returns:** [`ResolvedCommentRef | undefined`](https://forges.link/reference/data-model#resolvedcommentref) ### `releaseKey()` Stable identity key for a release: the [`repoKey`](https://forges.link/reference/data-model#repokey) of its repository and the release's forge-native id. ```ts function releaseKey(ref: ReleaseRef): string ```

Parameter	Type
`ref`	`ReleaseRef`

**Returns:** `string` ### `parseReleaseKey()` Reads a [`releaseKey`](https://forges.link/reference/data-model#releasekey) back. The key carries no `tag`. ```ts function parseReleaseKey(key: string): ReleaseRef | undefined ```

Parameter	Type
`key`	`string`

**Returns:** [`ReleaseRef | undefined`](https://forges.link/reference/data-model#releaseref) ### `notificationKey()` A string that identifies a notification, for use as a key in a map or a store. ```ts function notificationKey(ref: NotificationRef): string ```

Parameter	Type
`ref`	`NotificationRef`

**Returns:** `string` ### `parseNotificationKey()` Reads a [`notificationKey`](https://forges.link/reference/data-model#notificationkey) back. ```ts function parseNotificationKey(key: string): NotificationRef | undefined ```

Parameter	Type
`key`	`string`

**Returns:** [`NotificationRef | undefined`](https://forges.link/reference/data-model#notificationref) ### `notificationThread()` The thread a notification concerns, or `undefined` for repo, actor and other subjects. ```ts function notificationThread(notification: Notification): ThreadRef | undefined ```

Parameter	Type
`notification`	`Notification`

**Returns:** [`ThreadRef | undefined`](https://forges.link/reference/data-model#threadref) ### `affectedKeys()` Lists the identity keys of the repositories, threads, comments, releases and notifications that an event or a notification concerns, so that a cache can drop or read again the rows that it holds for them. It sends no request. A push or a ref event concerns its repository only: a pull request whose head branch moved has no key here, as finding it takes a read. **Example** ```ts for (const event of await provider.webhooks.ingest(delivery)) { const affected = affectedKeys(event) for (const key of affected.threads) { cache.delete(key) } } ``` ```ts function affectedKeys(item: ForgeEvent | Notification): AffectedKeys ```

Parameter	Type
`item`	`ForgeEvent \| Notification`

**Returns:** [`AffectedKeys`](https://forges.link/reference/data-model#affectedkeys-1) ### `AffectedKeys` The identity keys of what an event or a notification concerns, grouped by the key function that built them. Each list holds a key once.

Member	Type	Description
`repos`	`string[]`	`repoKey` s of every repository the item concerns, including the repository of each thread, so that a listing keyed by repository is covered. For a renamed or transferred repository it also holds the key of the new path and, where the event names it, the old path.
`threads`	`string[]`	`threadKey` s.
`comments`	`string[]`	`commentKey` s of the comment that a `comment` or `review_comment` event names in `detail.comment` .
`releases`	`string[]`	`releaseKey` s.
`notifications`	`string[]`	`notificationKey` s.
`unresolved`	`ThreadRef[]`	Threads without a `number` , which have no key, and neither has a comment on one. Their repositories are in `repos` , and every thread and comment key starts with the key of its repository followed by `#` .

### `isNamespaceRef()` Whether `ref` addresses an organisation, group or workspace rather than a repository. ```ts function isNamespaceRef(ref: RepoRef): boolean ```

Parameter	Type
`ref`	`RepoRef`

**Returns:** `boolean` ### `isResolvedThread()` Whether a thread ref has a number, so that it is a `ResolvedThreadRef`. ```ts function isResolvedThread(thread: ThreadRef): thread is ResolvedThreadRef ```

Parameter	Type
`thread`	`ThreadRef`

**Returns:** [`thread is ResolvedThreadRef`](https://forges.link/reference/data-model#resolvedthreadref) ### `normaliseRepoName()` `repo` with `owner` and `name` lowercased where the forge ignores case, so equal repositories compare equal. ```ts function normaliseRepoName(repo: RepoRef): RepoRef ```

Parameter	Type
`repo`	`RepoRef`

**Returns:** [`RepoRef`](https://forges.link/reference/data-model#reporef) ### `namesAreCaseInsensitive()` Whether `forge` treats owner and repository names case-insensitively. Unknown forges are assumed not to. ```ts function namesAreCaseInsensitive(forge: ForgeKind): boolean ```

Parameter	Type
`forge`	`ForgeKind`

**Returns:** `boolean` ## Accounts and repositories ### `RepoVisibility` Who can see a repository. **one of:** - `'public'` - `'private'` - `'internal'` ### `RepoPermissions` The authenticated account's access to a repository.

Member	Type	Description
`admin`	`boolean`	Full administrative access.
`maintain`	`boolean`	Manage the repository without access to sensitive or destructive settings.
`push`	`boolean`
`triage`	`boolean`	Manage issues and pull requests without write access.
`pull`	`boolean`	Read and clone the repository.

### `RepoFeatures` Which subjects a repository has switched on, where the forge makes them per repository.

Member	Type
`issues`	`boolean`
`pullRequests`	`boolean`
`discussions`	`boolean`
`wiki`	`boolean`
`projects`	`boolean`
`releases`	`boolean`

### `RepoRole` A collaborator's role, highest first. `'none'` is an explicit absence of access. **one of:** - `'admin'` - `'maintain'` - `'write'` - `'triage'` - `'read'` - `'none'` ### `Collaborator` An account with a role on a repository.

Member	Type	Description
`actor`	`Actor`
`role`	`RepoRole`
`permissions?`	`RepoPermissions`	What the role allows.

### `Contributor` A commit author on a repository, as `repos.contributors()` reads it.

Member	Type	Description
`actor?`	`Actor`	The account, where the forge links the author to one.
`name?`	`string`	The git author name, where the forge reports one.
`email?`	`string`	The git author email, where the forge reports one.
`contributions`	`number`	Commits attributed to the contributor, as the forge counts them.

### `ContributorStats` A contributor's commit activity over time, as `repos.contributorStats()` reads it.

Member	Type	Description
`actor?`	`Actor`	The account, where the forge links the commits to one.
`commits`	`number`	Commits by the contributor across all weeks.
`weeks`	`ContributorWeek[]`	One entry per week, oldest first.

### `ContributorWeek` One week of a contributor's commit activity.

Member	Type	Description
`week`	`Date`	Start of the week.
`additions`	`number`	Lines added.
`deletions`	`number`	Lines deleted.
`commits`	`number`	Commits that week.

### `RepoTemplate` An issue or pull request template of a repository, as `repos.templates()` reads it.

Member	Type	Description
`kind`	`'issue' \| 'pull_request'`	What the template opens.
`name`	`string`	The name of the template, where the forge's API parses one, or its file name.
`path?`	`string`	The file the template lives in. Not available on GitLab.
`format`	`'markdown' \| 'form'`	`'form'` for a form written in YAML, `'markdown'` for the rest.
`body`	`string`	The template as the repository stores it: Markdown with any front matter, or the YAML of a form.
`title?`	`string`	The title a new thread starts with, where the forge parses one.
`about?`	`string`	What the template is for, where the forge parses it.
`labels?`	`string[]`	Labels a new thread gets, where the forge parses them.
`fields?`	`RepoTemplateField[]`	The fields of a form, where the forge parses them.
`source?`	`RepoRef`	Where the template comes from when the forge falls back to another repository, like GitHub's `.github` .

### `RepoTemplateField` One field of an issue form, as the forge parses it.

Member	Type	Description
`type`	`string`	The kind of input, such as `'input'` , `'textarea'` , `'dropdown'` , `'checkboxes'` or `'markdown'` .
`id?`	`string`
`attributes`	`Record`	The field's label, description, options and default value, as the form declares them.
`validations?`	`Record`	Whether the field is required, and other checks the form declares.

### `TeamRef` Reference to a team of an organisation. A team belongs to the organisation, not to a repository, so the ref carries the namespace ref of the organisation rather than a repository. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`org`	`RepoRef`	The organisation, group or workspace the team belongs to.
`id?`	`string`	Forge-native team id. Where it is set, `orgs.teamMembers()` prefers it to `slug` on forges that address teams by id.
`slug`	`string`	URL-safe identifier unique within the organisation. GitHub has a slug; on GitLab it is the subgroup's path below the group, such as `platform/web` ; Forgejo and Gitea have none, so the team's name stands in.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `Team` A team of an organisation, as `orgs.teams()` lists them. GitLab has no teams of its own, so a subgroup plays the role of one.

Member	Type	Description
`ref`	`TeamRef`
`name`	`string`
`description?`	`string`
`permission?`	`string`	Forge-native repository permission the team grants, where the forge reports one.
`parent?`	`TeamRef`	The team's parent team, where the forge nests teams: a GitHub parent team, or the GitLab subgroup a nested subgroup belongs to.
`url?`	`string`	Web page of the team, where the forge has one.

### `Repo` A repository as every forge reports it. Fields that not every forge has, such as `openPullCount`, are optional.

Member	Type	Description
`ref`	`RepoRef`
`displayName?`	`string`	The repository's name where `ref.name` is an identifier rather than the name (a Tangled record key).
`description?`	`string`
`defaultBranch?`	`string`
`visibility`	`RepoVisibility`	Who can see the repository.
`isFork`	`boolean`
`isArchived`	`boolean`	The repository is archived and read-only.
`parent?`	`RepoRef`	The repository that this one was forked from.
`topics`	`string[]`	Topics, also called tags, that describe the repository.
`url?`	`string`
`cloneUrls?`		Git remotes. Tangled maps the hosting knot to its SSH host.
`createdAt?`	`Date`
`updatedAt?`	`Date`
`pushedAt?`	`Date`	Last push, where the listing endpoint reports it.
`openIssueCount?`	`number`	Open issues only, never combined with pull requests. Absent where the forge reports only the combined count (GitHub).
`openPullCount?`	`number`	The number of open pull requests, where the forge reports it.
`owner?`	`Actor`	The account or organisation that owns the repository, where the forge reports one.
`language?`	`string`	Primary language, as the forge detects it.
`homepage?`	`string`	Project website, apart from the repository's own `url` .
`licence?`	`string`	SPDX identifier of the licence the forge detects, for example `MIT` . SPDX identifiers are case-insensitive, and GitLab reports them in lower case, such as `mit` .
`stars?`	`number`
`forks?`	`number`
`watchers?`	`number`	Accounts watching the repository's activity, apart from stars.
`permissions?`	`RepoPermissions`	What the authenticated account may do.
`mergeMethods?`	`MergeMethod[]`	Merge methods the repository allows, where the forge reports them. Empty means the forge reported none.
`defaultMergeMethod?`	`MergeMethod`	The repository's default merge method, where the forge reports one. On GitLab, a project that squashes by default reports `squash` , not its base method.
`deleteBranchOnMerge?`	`boolean`	The repository's setting for deleting the head branch after a merge, where the forge reports it. Forgejo and Gitea before 1.25 apply it only in their web UI, so `merge()` keeps the branch there. On GitLab it seeds merge requests when they are opened.
`mergeCommit?`		Default text of a merge commit (`merge` ) and a squashed one (`squash` ) as `MergeCommitDefaults` , where the forge reports it.
`features?`	`RepoFeatures`

### `Actor` An account: a user, an organisation or a bot. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`login`	`string`
`id`	`string`	Forge-native account id: the numeric id on GitHub (`databaseId` in its GraphQL API, not the node id), GitLab, Forgejo, Gitea and Gitee, the UUID on Bitbucket, the identity id on Azure DevOps and the DID on Tangled.
`name?`	`string`
`avatarUrl?`	`string`
`url?`	`string`
`isBotHint`	`boolean`	Hint derived from forge metadata that the actor is automation. Callers own the classification policy.
`app?`		The app behind a bot account, where the forge ties one to it (GitHub Apps' `slug[bot]` users).
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `User` A user or organisation account, as `users.get()` reads it. **extends:** [`Actor`](https://forges.link/reference/data-model#actor)

Member	Type	Description
`bio?`	`string`
`company?`	`string`
`location?`	`string`
`websiteUrl?`	`string`
`createdAt?`	`Date`
`followers?`	`number`
`following?`	`number`
`publicRepos?`	`number`
`login`	`string`	Inherited from `Actor` .
`id`	`string`	Forge-native account id: the numeric id on GitHub (`databaseId` in its GraphQL API, not the node id), GitLab, Forgejo, Gitea and Gitee, the UUID on Bitbucket, the identity id on Azure DevOps and the DID on Tangled. Inherited from `Actor` .
`name?`	`string`	Inherited from `Actor` .
`avatarUrl?`	`string`	Inherited from `Actor` .
`url?`	`string`	Inherited from `Actor` .
`isBotHint`	`boolean`	Hint derived from forge metadata that the actor is automation. Callers own the classification policy. Inherited from `Actor` .
`app?`		The app behind a bot account, where the forge ties one to it (GitHub Apps' `slug[bot]` users). Inherited from `Actor` .
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `RepoSearchQuery` A search for repositories. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Default	Description
`text?`	`string`
`queryRaw?`	`string`		Forge-native query syntax; see `SearchQuery.queryRaw` .
`owner?`	`string`		Limit to one account or namespace.
`language?`	`string`		The main language of the repository.
`sort?`	`'created' \| 'updated' \| 'stars' \| 'relevance'`		Defaults to the forge's relevance order.
`direction?`	`'asc' \| 'desc'`	`desc`
`perPage?`	`number`		How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`		Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `RepoTemplateOptions` Options for `repos.templates()`. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Description
`kind?`	`'issue' \| 'pull_request'`	Only templates for this kind of thread. Defaults to both.
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `RepoAffiliation` How the account is attached to the repositories it lists. **one of:** - `'owner'` - `'collaborator'` - `'organisation_member'` ### `RepoQuery` Filters for `repos.list()`. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Description
`affiliation?`	`RepoAffiliation[]`	Defaults to every affiliation the forge lists. Unsupported values produce a `filter_unsupported` warning.
`visibility?`	`RepoVisibility \| 'all'`	Only repositories with this visibility.
`sort?`	`'created' \| 'updated' \| 'pushed' \| 'name'`	Defaults to the forge's own order. Unsupported orders produce a `sort_unsupported` warning.
`direction?`	`'asc' \| 'desc'`	Defaults to the forge's own direction.
`perPage?`	`number`	How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`	Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `InstallationToken` A short-lived token that acts as one app installation.

Member	Type	Description
`token`	`string`
`expiresAt`	`Date`
`permissions`	`Record`
`repositorySelection?`	`string`	Whether the token reaches all repositories or only selected ones.

### `Installation` An app installation on an account, with its own credential scope. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`id`	`string`
`account?`	`Actor`
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `RepoGetOptions` Options for `repos.get()`. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Description
`licence?`	`boolean`	Includes the repository's licence in `Repo.licence` . GitLab reports it only on request, because detecting it scans the repository; other forges ignore this option.
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `RepoSection` A repository's section, for linking to the section itself rather than one entry in it. **one of:** - `'issues'` - `'pullRequests'` - `'compare'` - `'releases'` - `'stargazers'` - `'forks'` - `'watchers'` ### `OwnerRepoQuery` Filters for `repos.byOwner()`. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Default	Description
`visibility?`	`RepoVisibility \| 'all'`		Only repositories with this visibility.
`subgroups?`	`boolean`	`false`	Includes the repositories of nested groups, on forges that have them (GitLab).
`sort?`	`'created' \| 'updated' \| 'pushed' \| 'name'`		Defaults to the forge's own order. Unsupported orders produce a `sort_unsupported` warning.
`direction?`	`'asc' \| 'desc'`		Defaults to the forge's own direction.
`perPage?`	`number`		How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`		Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `AddCollaboratorResult` What `repos.addCollaborator()` did.

Member	Type	Description
`status`	`'invited' \| 'added'`	`'invited'` when the account has to accept an invitation before it has the role, `'added'` when it has the role now, including an account that already had access.

### `TextLimits` Maximum lengths the forge accepts, in characters.

Member	Type
`bodyLength?`	`number`
`commentLength?`	`number`
`labelLength?`	`number`

## Threads and comments ### `MergeBlockedError` The pull request cannot be merged yet, typically because of failing or pending checks or branch protection. **extends:** [`ForgeApiError`](https://forges.link/reference/errors#forgeapierror) ### `MergeConflictError` The merge conflicts with the base branch, or the head moved since `sha` was read. **extends:** [`ForgeApiError`](https://forges.link/reference/errors#forgeapierror) ### `MergeMethodRequiredError` No merge method was given, and the repository allows several or reports none. **extends:** [`ForgeError`](https://forges.link/reference/errors#forgeerror) ```ts new MergeMethodRequiredError(allowed: MergeMethod[], context?: ForgeErrorContext, options?: ErrorOptions) ```

Parameter	Type
`allowed`	`MergeMethod[]`
`context?`	`ForgeErrorContext`
`options?`	`ErrorOptions`

Member	Type	Description
`allowed`	`MergeMethod[]`	The merge methods that the repository allows.

### `Label` A label that a repository defines.

Member	Type	Description
`name`	`string`
`colour?`	`string`	The colour as hex digits, without a leading `#` .
`description?`	`string`

### `LabelInput` What a label is created or updated with.

Member	Type	Description
`name`	`string`
`colour?`	`string`	Six-digit hex, without the leading `#` .
`description?`	`string`

### `Milestone` A milestone that groups threads.

Member	Type	Description
`id`	`string`	Forge-native milestone id, as `threads.setMilestone` takes it.
`title`	`string`
`state`	`'open' \| 'closed'`
`description?`	`string`
`dueOn?`	`Date`
`url?`	`string`

### `ThreadState` Thread state. `'unknown'` is distinct from any real state and signals that the value was not present in the payload, so the caller may enrich it with `threads.get()`. Draft status is orthogonal; see `Thread.isDraft`. **one of:** - `'open'` - `'closed'` - `'merged'` - `'unknown'` ### `ThreadStack` Where a pull request sits in a stack of pull requests.

Member	Type	Description
`id?`	`string`	Forge-native stack id, where the forge names stacks.
`parent?`	`ResolvedThreadRef`	The pull request this one is stacked on. Absent for the root of the stack.

### `Thread` An issue, pull request, discussion or commit conversation.

Member	Type	Description
`ref`	`ResolvedThreadRef`
`kind`	`ThreadKind`
`title`	`string`
`body?`	`string`
`state`	`ThreadState`
`stateReason?`	`string`	Forge-native state qualifier, for example `completed` or `not_planned` .
`isDraft`	`boolean`
`author?`	`Actor`
`authorAssociation?`	`AuthorAssociation`	How the author relates to the repository, where the forge reports it.
`assignees`	`Actor[]`
`reviewers`	`Reviewer[]`	Reviewers the thread read reports. Some forges report outstanding requests only, others each reviewer's verdict; `threads.reviews()` has every submitted review.
`labels`	`Label[]`
`url?`	`string`
`createdAt?`	`Date`
`updatedAt?`	`Date`
`closedAt?`	`Date`
`mergedAt?`	`Date`	When the pull request was merged, where the forge reports it.
`mergedBy?`	`Actor`	The account that merged the pull request, where the forge reports it.
`lastActivityAt?`	`Date`	Latest activity the forge reports for the thread.
`locked?`	`boolean`
`commentCount?`	`number`
`participants?`	`Actor[]`	Everyone who authored or commented on the thread, where the forge reports them.
`subscription?`	`SubscriptionState`	The authenticated account's subscription, where the thread read already carries it.
`milestone?`	`Milestone`
`reactions?`	`ReactionSummary`
`branches?`	`PullBranches`	Pull requests only.
`checks?`	`ChecksSummary`	Pull requests only.
`stats?`	`PullStats`	Pull requests only, where the forge reports counts with the pull request.
`stack?`	`ThreadStack`	Pull requests in a stack: a chain of dependent pull requests, each based on the one before.
`warnings?`	`ForgeWarning[]`	Non-fatal problems hit while reading the thread, for example an unreachable record.

### `Comment` A comment on a thread.

Member	Type	Description
`ref`	`ResolvedCommentRef`
`body`	`string`
`author?`	`Actor`
`authorAssociation?`	`AuthorAssociation`	How the author relates to the repository, where the forge reports it.
`createdAt?`	`Date`
`updatedAt?`	`Date`
`url?`	`string`
`reactions?`	`ReactionSummary`
`thread?`		The resolvable conversation the comment belongs to, where the forge has one; `resolveReviewThread()` takes its id.

### `SubscriptionState` Whether the account gets notifications for a thread. **one of:** - `'subscribed'` - `'ignored'` - `'none'` ### `ThreadSnapshot` Fields of a [`Thread`](https://forges.link/reference/data-model#thread) that an event's source carries. A field is absent when the source does not report it; `labels: []` means the source listed no labels. `threads.get()` reads the rest.

Member	Type
`title?`	`string`
`body?`	`string`
`state?`	`Exclude`
`stateReason?`	`string`
`isDraft?`	`boolean`
`author?`	`Actor`
`labels?`	`Label[]`
`url?`	`string`
`branches?`	`PullBranches`
`stats?`	`PullStats`
`mergedBy?`	`Actor`

### `ThreadQuery` Filters for `threads.list()`. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Default	Description
`kind?`	`'issue' \| 'pull_request' \| 'discussion'`		Omitted lists every listable kind; forges that list kinds separately emit them one after another.
`state?`	`'open' \| 'closed' \| 'merged' \| 'all'`	`'open'`	`'closed'` includes merged pull requests; `'merged'` lists pull requests only, and lists nothing for another `kind` .
`labels?`	`string[]`		Threads carrying every one of these labels.
`author?`	`string`		Author login.
`assignee?`	`string`		Assignee login.
`involves?`	`string`		Threads the login authored, is assigned, commented on or was mentioned in. A listing without this filter ignores it and warns with `filter_unsupported` , as for `mentions` and `milestone` .
`mentions?`	`string`		Threads the login was mentioned in.
`milestone?`	`string`		Milestone title, or `'none'` for threads with no milestone.
`since?`	`Date`		Updated at or after.
`createdAfter?`	`Date`		Created at or after.
`sort?`	`'created' \| 'updated' \| 'comments'`	`'created'`	Unsupported orders produce a warning and the forge's own order.
`direction?`	`'asc' \| 'desc'`	`'desc'`
`perPage?`	`number`		How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`		Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `SearchQuery` A structured search. Providers translate it into their own syntax; a field the forge cannot filter on becomes a `filter_unsupported` warning on the page rather than a filter applied client-side. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Default	Description
`text?`	`string`		Free text, matched against title and body.
`queryRaw?`	`string`		Forge-native query syntax, added to the query as is, for qualifiers the other fields don't cover. Forges whose search has no query syntax ignore it with a `filter_unsupported` warning.
`repo?`	`RepoRef`		Limit to one repository.
`kind?`	`'issue' \| 'pull_request'`
`state?`	`'open' \| 'closed' \| 'all'`		Defaults to every state.
`author?`	`string`
`involves?`	`string`		Threads the login authored, is assigned, commented on or was mentioned in.
`assignee?`	`string`
`labels?`	`string[]`		Threads carrying every one of these labels.
`since?`	`Date`		Updated at or after.
`sort?`	`'created' \| 'updated' \| 'comments' \| 'relevance'`		Defaults to the forge's relevance order.
`direction?`	`'asc' \| 'desc'`	`'desc'`
`perPage?`	`number`		How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`		Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `UpsertCommentInput` What `threads.upsertComment()` needs.

Member	Type	Description
`key`	`string`	Identifies the comment to replace across runs. It is written into the body as an HTML comment, so it is invisible when rendered but matchable on the next run.
`body`	`string`
`since?`	`Date`	Only comments updated at or after this time are searched for the key. When retrying a change, pass the time of its first attempt, less a margin for clock skew, so the retry lists only recent comments. A comment with the same key from before `since` is not found, and a new one is created.

### `UpsertCommentResult` What `threads.upsertComment()` did.

Member	Type	Description
`comment`	`Comment`	The comment that was created or edited.
`created`	`boolean`	`false` when a comment with the same key already existed, and was edited or already had the body.

### `ThreadCreateInput` What `threads.create()` needs.

Member	Type	Description
`kind`	`'issue' \| 'pull_request' \| 'discussion'`
`title`	`string`
`body?`	`string`
`labels?`	`string[]`	Names of the labels to add.
`assignees?`	`Array`	Logins, or actors where the forge needs ids.
`head?`	`string`	Pull requests: source branch, optionally `owner:branch` for forks.
`base?`	`string`	Pull requests: target branch.
`draft?`	`boolean`	Open the pull request as a draft.
`category?`	`string`	Discussions: category name or id.

### `ThreadUpdateInput` The fields that `threads.update()` changes. Fields left out stay as they are.

Member	Type	Description
`title?`	`string`
`body?`	`string`
`state?`	`'open' \| 'closed'`	Closes or reopens the thread. To give a reason, use `threads.close()` .
`labels?`	`string[]`	Names of the labels to replace the current ones; `[]` clears them.
`assignees?`	`Array`	Logins, or actors where the forge needs ids, to replace the assignees; `[]` clears them.

### `GetManyResult` One `threads.getMany()` entry, in input order; narrow on `ok`. **one of:** - `{ ok: true, ref: ThreadRef, thread: Thread }` - `{ ok: false, ref: ThreadRef, warning: ForgeWarning }` ### `MergeMethod` How a pull request is merged. **one of:** - `'merge'` - `'squash'` - `'rebase'` - `'rebase_merge'` - `'fast_forward_only'` ### `MergeCommitDefaults` Where the default title and message of a merge or squash commit come from.

Member	Type	Description
`title?`	`'pull_request_title' \| 'commit_or_pull_request_title' \| 'merge_message'`	The pull request title, the commit's own title when there's just one, or the classic `Merge pull request #1 from acme/fix` .
`message?`	`'pull_request_body' \| 'pull_request_title' \| 'commit_messages' \| 'blank'`	The pull request body or title, its commit messages, or nothing at all.
`template?`	`string`	A template for the whole message, with placeholders such as GitLab's `%{title}` . Absent while the forge sticks to its built-in one.

### `MergeOptions` Options for `threads.merge()`. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Description
`method?`	`MergeMethod`	Defaults to the repository's only allowed method.
`sha?`	`string`	Expected head sha; the merge is refused if the branch has moved.
`title?`	`string`	Merge commit title. Where the forge takes a single message, it goes above `message` , separated by a blank line.
`message?`	`string`	Merge commit body, where the forge takes one. Where the forge takes a single message and `title` is unset, this is the whole message.
`whenChecksPass?`	`boolean`	Queue the merge until required checks pass, where the forge supports it.
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `ApproveAndMergeOptions` Options for `threads.approveAndMerge()`. **extends:** [`MergeOptions`](https://forges.link/reference/data-model#mergeoptions)

Member	Type	Description
`body?`	`string`	Review body sent with the approval. Rejected where approvals carry no body (Azure DevOps, Bitbucket, GitLab).
`method?`	`MergeMethod`	Defaults to the repository's only allowed method. Inherited from `MergeOptions` .
`sha?`	`string`	Expected head sha; the merge is refused if the branch has moved. Inherited from `MergeOptions` .
`title?`	`string`	Merge commit title. Where the forge takes a single message, it goes above `message` , separated by a blank line. Inherited from `MergeOptions` .
`message?`	`string`	Merge commit body, where the forge takes one. Where the forge takes a single message and `title` is unset, this is the whole message. Inherited from `MergeOptions` .
`whenChecksPass?`	`boolean`	Queue the merge until required checks pass, where the forge supports it. Inherited from `MergeOptions` .
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `MergeResult` What `threads.merge()` and `threads.approveAndMerge()` resolve with.

Member	Type	Description
`status`	`'merged' \| 'queued'`	`'merged'` once the pull request has merged. `'queued'` when the forge merges it later: with `whenChecksPass` , or where it completes the merge in the background (Azure DevOps, and Bitbucket when the merge outlasts its timeout).
`sha?`	`string`	The commit that the merge made on the base branch, where the response reports it.

### `CloseReason` Why a thread was closed. **one of:** - `'completed'` - `'not_planned'` - `'duplicate'` ### `CloseOptions` Options for `threads.close()`. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Description
`reason?`	`CloseReason`	Mapped to the forge's own reason where it has one; forges without close reasons close the thread without one.
`reasonRaw?`	`string`	Forge-native reason, sent as is; takes precedence over `reason` .
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `CommentOptions` Options for `threads.comment()`. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Description
`key?`	`string`	Writes the hidden marker of `upsertComment()` for this key into the body, so that `upsertComment()` with the same key edits this comment instead of posting another.
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `MilestoneListOptions` Options for `repos.milestones()`. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Default	Description
`state?`	`'open' \| 'closed' \| 'all'`	`'open'`
`perPage?`	`number`		How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`		Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `SubscribeOptions` Options for `sources.subscribe()`.

Member	Type	Description
`cursor?`	`string`	Resume after this cursor, as yielded by an earlier `SubscriptionItem` .
`signal?`	`AbortSignal`	Aborting closes the connection and ends iteration without an error.

### `SubscriptionItem` One item from a push subscription.

Member	Type	Description
`event`	`ForgeEvent`
`cursor`	`string`	Opaque position after `event` ; persist it and pass it back to resume.

### `AuthorAssociation` How the author of a thread or comment relates to its repository: - `owner` owns the repository. - `member` belongs to the organisation that owns it. - `collaborator` was invited to collaborate on it. - `contributor` has committed to it before. - `first_time_contributor` has not committed to it before. - `first_timer` has not committed to any repository on the forge before. - `none` has none of these, or is a placeholder for an unclaimed account. - `unknown` is an association with no normalised value; `authorAssociationRaw` names it. **one of:** - `'owner'` - `'member'` - `'collaborator'` - `'contributor'` - `'first_time_contributor'` - `'first_timer'` - `'none'` - `'unknown'` ### `commentMarker()` The hidden marker `threads.upsertComment()` writes into a comment body to find it again. It renders as nothing on every forge that renders Markdown as HTML. ```ts function commentMarker(key: string): string ```

Parameter	Type
`key`	`string`

**Returns:** `string` ### `hasCommentMarker()` Whether `body` carries the marker for `key`. ```ts function hasCommentMarker(body: string, key: string): boolean ```

Parameter	Type
`body`	`string`
`key`	`string`

**Returns:** `boolean` ## Reactions ### `ReactionContent` The reactions every forge with reactions has in common, named as GitHub names them. A [`Reaction`](https://forges.link/reference/data-model#reaction) whose forge-native name has no entry here has `content: 'other'`, with the forge-native name in `contentRaw`. **type:** [`(typeof REACTION_CONTENTS)[number]`](https://forges.link/reference/data-model#reaction_contents) ### `Reaction` One reaction left on a thread or a comment, as `threads.reactions()` lists them.

Member	Type	Description
`content`	`ReactionContent \| 'other'`	`'other'` where the forge's name has no entry in `ReactionContent` .
`actor`	`Actor`
`createdAt?`	`Date`

### `ReactionSummary` The reactions on a thread or comment, counted.

Member	Type	Description
`total`	`number`	The number of reactions of every kind.
`counts`	`Partial>`	The number of reactions of each kind. A reaction with no `ReactionContent` entry has no key here.
`viewerReacted?`	`ReactionContent[]`	Reactions the authenticated account has left. Absent when the forge does not report them.

### `REACTION_CONTENTS` Every name [`ReactionContent`](https://forges.link/reference/data-model#reactioncontent) covers. **type:** `readonly ["+1", "-1", "laugh", "confused", "heart", "hooray", "rocket", "eyes"]` ## Reviews ### `ReviewState` What a review or a reviewer says about a pull request. `unknown` is a state that the model does not name. **one of:** - `'approved'` - `'changes_requested'` - `'commented'` - `'pending'` - `'dismissed'` - `'unknown'` ### `ReviewRef` Reference to a review on a pull request. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`thread`	`ThreadRef`
`id`	`string`	Forge-native review id; a synthesised `approval:` where the forge has approvals but no review objects.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `ReviewComment` A comment left on a line of the diff as part of a review.

Member	Type	Description
`ref?`	`ResolvedCommentRef`
`body`	`string`
`author?`	`Actor`
`path?`	`string`
`line?`	`number`	Line in the file the comment is anchored to, in the side it is anchored to.
`side?`	`'left' \| 'right'`	`'left'` is the base of the diff, `'right'` the head.
`inReplyTo?`	`string`	Forge-native id of the comment this one replies to.
`thread?`		The resolvable conversation the comment belongs to, where the forge has one.
`createdAt?`	`Date`
`url?`	`string`

### `Review` A review of a pull request.

Member	Type	Description
`ref`	`ResolvedReviewRef`
`author?`	`Actor`
`state`	`ReviewState`
`body?`	`string`
`submittedAt?`	`Date`
`comments`	`ReviewComment[] \| false`	Inline comments submitted with the review. `false` where the forge has approvals but no review objects to hang comments on.
`url?`	`string`

### `ReviewEvent` What a review does when it is submitted. Omitted creates a pending review where the forge has them. **one of:** - `'approve'` - `'request_changes'` - `'comment'` ### `ReviewCommentInput` An inline comment to send with a review.

Member	Type	Description
`path`	`string`
`line?`	`number`	Line in the diff, in `side` .
`side?`	`'left' \| 'right'`
`startLine?`	`number`	First line of a multi-line comment.
`body`	`string`

### `ReviewInput` What `threads.createReview()` needs.

Member	Type	Description
`event?`	`ReviewEvent`	Omitted creates a pending review, where the forge has them; submit it with `submitReview` .
`body?`	`string`
`comments?`	`ReviewCommentInput[]`	Inline comments to send with the review.

### `Reviewer` A reviewer who was asked to review a pull request, and what they said.

Member	Type	Description
`actor`	`Actor`
`state`	`ReviewState`
`isTeam?`	`boolean`	True when the reviewer is a team rather than an account.
`requestedAt?`	`Date`	When the pending review was last requested. Absent where the forge doesn't report it; on GitHub, `threads.getMany()` reports it.

### `ResolvedReviewRef` A review ref whose thread is resolved. Every review read from a forge carries one. **extends:** [`ReviewRef`](https://forges.link/reference/data-model#reviewref)

Member	Type	Description
`thread`	`ResolvedThreadRef`
`id`	`string`	Forge-native review id; a synthesised `approval:` where the forge has approvals but no review objects. Inherited from `ReviewRef` .
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `PullBranches` The branches of a pull request.

Member	Type	Description
`head`		`sha` is absent on forges where a pull is a patch rather than a branch (Tangled).
`head.ref`	`string`
`head.sha?`	`string`
`head.repo?`	`RepoRef`	The repository that holds the head branch, which differs for a fork.
`base.ref`	`string`
`base.sha?`	`string`
`mergeCommitSha?`	`string`	The merge commit, once the pull request is merged.

### `PullStats` The size of a pull request's change. Each count is absent where the forge doesn't report it exactly.

Member	Type	Description
`additions?`	`number`	Lines added.
`deletions?`	`number`	Lines removed.
`changedFileCount?`	`number`	Files changed.
`commitCount?`	`number`	Commits on the pull request.

## Checks and CI ### `CheckRef` One check run, commit status or CI job. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`repo`	`RepoRef`
`id`	`string`
`type`	`'check_run' \| 'status' \| 'job' \| 'policy'`	What the id addresses: a check run, a commit status, a CI job, or a branch policy evaluation.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `ChecksSummary` Combined state of the checks on a pull request's head commit. `failure` when any check failed, else `pending` while any runs, else `success`.

Member	Type	Description
`state`	`'pending' \| 'success' \| 'failure' \| 'unknown'`
`total?`	`number`	Absent when the forge reports only a combined state.
`failed?`	`number`
`url?`	`string`

### `CheckState` `neutral` covers skipped and informational results, which neither pass nor fail. **one of:** - `'pending'` - `'success'` - `'failure'` - `'neutral'` - `'unknown'` ### `Check` One check on a commit: a check run, a commit status, a job or a policy evaluation.

Member	Type
`ref`	`CheckRef`
`name`	`string`
`state`	`CheckState`
`url?`	`string`
`startedAt?`	`Date`
`completedAt?`	`Date`

### `CheckReportInput` What `checks.report` writes: a commit status everywhere, a check run on GitHub under app auth.

Member	Type	Description
`name`	`string`	Status context or check run name.
`state`	`Exclude`
`description?`	`string`	A short description of the state.
`url?`	`string`	Where a person goes to see the detail.
`externalId?`	`string`	The caller's own id for the check, where the forge stores one.

### `CiRunRef` A CI run: a workflow run, a pipeline, or a build. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`repo`	`RepoRef`
`id`	`string`
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `CiJobRef` One job inside a run. `run` is absent when the job was addressed on its own. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`repo`	`RepoRef`
`id`	`string`
`run?`	`CiRunRef`
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `CiRun` A CI run, such as a workflow run or a pipeline.

Member	Type	Description
`ref`	`CiRunRef`
`name`	`string`
`state`	`CheckState`
`number?`	`string`	Per-repo run number, where the forge has one.
`branch?`	`string`
`sha?`	`string`	The commit that the run ran on.
`url?`	`string`
`actor?`	`Actor`
`createdAt?`	`Date`
`startedAt?`	`Date`
`completedAt?`	`Date`

### `CiJob` One job of a CI run.

Member	Type	Description
`ref`	`CiJobRef`
`name`	`string`
`state`	`CheckState`
`stage?`	`string`	Stage or group the job belongs to, where the forge has one.
`url?`	`string`
`startedAt?`	`Date`
`completedAt?`	`Date`

### `CiRunQuery` Filters for `ci.runs()`. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Description
`branch?`	`string`
`state?`	`Exclude`	Normalised state; forges that filter on their own names translate it.
`perPage?`	`number`	How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`	Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

## Files and commits ### `BranchMovedError` `contents.commitFiles()` was given an `expectedHead`, and the branch no longer points at it. **extends:** [`ForgeApiError`](https://forges.link/reference/errors#forgeapierror) ### `CommitRef` A commit addressed by its full sha. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`repo`	`RepoRef`
`sha`	`string`	The full sha of the commit.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `FileEncoding` `'binary'` carries bytes; `'utf-8'` carries text the forge reported as text. **one of:** - `'utf-8'` - `'binary'` ### `FileMetadata` What a forge reports about a file, apart from its content.

Member	Type	Description
`path`	`string`	The path from the repository root.
`sha?`	`string`	Blob sha, where the forge reports one.
`size?`	`number`
`url?`	`string`	Web page for the file at this ref, where the forge has one.

### `FileContent` A file's contents. Narrow on `encoding` to get text or bytes. **one of:** - [`FileMetadata & { encoding: 'utf-8', content: string }`](https://forges.link/reference/data-model#filemetadata) - [`FileMetadata & { encoding: 'binary', content: Uint8Array }`](https://forges.link/reference/data-model#filemetadata) ### `FileOptions` Options for `contents.file()`. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Default	Description
`ref?`	`string`		Branch, tag or sha. Defaults to the repository's default branch.
`as?`	`'text' \| 'binary'`	`'binary'`	`'text'` decodes as UTF-8 and rejects with `ContentNotTextError` when the bytes are not text.
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `FileChange` A file that `contents.commitFiles()` writes or deletes.

Member	Type	Description
`path`	`string`	The path from the repository root.
`content`	`string \| Uint8Array \| null`	The new contents, with a string written as UTF-8, or `null` to delete the file.

### `CommitFilesInput` The commit that `contents.commitFiles()` makes.

Member	Type	Description
`branch`	`string`	The branch to commit to.
`message`	`string`	The commit message.
`changes`	`FileChange[]`	The files to write or delete. A file that exists is overwritten.
`expectedHead?`	`string`	The sha that the branch must point at. When the branch has moved, the commit rejects with `BranchMovedError` .
`createFrom?`	`string`	Creates `branch` from this branch, tag or sha. The branch must not exist yet.
`author?`		Who wrote the change. Defaults to the account of the credential. Some forges record it as the committer too.

### `TreeEntryType` What a tree entry is. **one of:** - `'file'` - `'directory'` - `'symlink'` - `'submodule'` ### `TreeEntry` One entry of a repository tree.

Member	Type	Description
`path`	`string`	Path from the repository root, without a leading slash.
`type`	`TreeEntryType`
`sha?`	`string`
`size?`	`number`	The size in bytes, for a file.
`mode?`	`string`	POSIX mode as the forge reports it, for example `100644` .
`url?`	`string`

### `TreeOptions` Options for `contents.tree()`. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Description
`ref?`	`string`	Branch, tag or sha. Defaults to the repository's default branch.
`path?`	`string`	Subdirectory to list; the root when omitted.
`recursive?`	`boolean`	Every descendant rather than one level. Unsupported on some forges, which then warn.
`perPage?`	`number`	How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`	Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `Branch` A branch of a repository.

Member	Type	Description
`name`	`string`
`sha`	`string`	The commit that the branch points at.
`isDefault?`	`boolean`
`isProtected?`	`boolean`
`url?`	`string`

### `Tag` A tag of a repository.

Member	Type	Description
`name`	`string`
`sha`	`string`	Commit the tag points at, after dereferencing an annotated tag where the forge does so.
`url?`	`string`

### `CommitSignature` Git authorship, with the forge account behind it where the forge matched one.

Member	Type	Description
`actor?`	`Actor`	The account, where the forge can match it.
`name?`	`string`
`email?`	`string`
`date?`	`Date`	When the commit was authored or committed.

### `FileStatus` How a commit or pull request changed a file. **one of:** - `'added'` - `'modified'` - `'removed'` - `'renamed'` - `'copied'` - `'changed'` ### `ChangedFile` A file that a commit or pull request changed.

Member	Type	Description
`path`	`string`
`previousPath?`	`string`	Path before a rename or copy.
`status`	`FileStatus`
`additions?`	`number`
`deletions?`	`number`
`patch?`	`string`	Unified diff for the file, where the forge returns one inline.
`sha?`	`string`	Blob sha after the change.
`isBinary?`	`boolean`	The file is binary, so it has no patch.

### `Commit` A commit.

Member	Type	Description
`ref`	`CommitRef`
`sha`	`string`	The full sha.
`message`	`string`
`author?`	`CommitSignature`	Who wrote the change.
`committer?`	`CommitSignature`	Who recorded the change.
`parents`	`string[]`
`url?`	`string`
`files?`	`ChangedFile[]`	Present on `contents.commit` ; absent from listings.

### `CommitQuery` Filters for `contents.commits()`. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Description
`ref?`	`string`	Branch, tag or sha to walk back from.
`since?`	`Date`	Only commits at or after this time.
`until?`	`Date`	Only commits at or before this time.
`path?`	`string`	Only commits touching this path.
`author?`	`string`	Login or email, as the forge matches it.
`perPage?`	`number`	How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`	Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `CompareOptions` Options for `contents.compare()`. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Default	Description
`commitLimit?`	`number`		The most commits to return. The comparison keeps the newest ones. Where the forge can't send fewer, the provider drops the rest. `aheadBy` still counts every commit where the forge reports the count.
`files?`	`boolean`	`true`	Whether to read the changed files. With `false` , `files` is empty and the commits carry no files.
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `Comparison` The difference between two revisions.

Member	Type	Description
`base`	`string`	The revision that the comparison starts from.
`head`	`string`	The revision that the comparison ends at.
`aheadBy?`	`number`	The number of commits that `head` has and `base` lacks.
`behindBy?`	`number`	The number of commits that `base` has and `head` lacks.
`commits`	`Commit[]`	The commits between the two revisions, newest first. Forges that cap the list leave out the oldest.
`files`	`ChangedFile[]`
`mergeBaseSha?`	`string`	The merge base, where the forge reports it.

### `CodeMatch` A file that a code search found. A file whose excerpts span two pages comes back on both.

Member	Type	Description
`repo`	`RepoRef`
`path`	`string`
`ref?`	`string`	The branch, tag or sha the forge searched, where it reports one.
`fragments`	`CodeFragment[]`	The excerpts of the file that matched.
`url?`	`string`

### `CodeFragment` An excerpt of a file that matched a code search.

Member	Type	Description
`text`	`string`
`line?`	`number`	The line the excerpt starts on, where the forge reports it.

### `CommitSearchQuery` A search for commits. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Default	Description
`text?`	`string`		Free text, matched against the commit message.
`queryRaw?`	`string`		Forge-native query syntax; see `SearchQuery.queryRaw` .
`repo?`	`RepoRef`		Limit to one repository.
`author?`	`string`		Commits whose author is this login.
`committer?`	`string`		Commits whose committer is this login.
`since?`	`Date`		Authored or committed at or after.
`until?`	`Date`		Authored or committed at or before.
`sort?`	`'author_date' \| 'committer_date'`		Defaults to the forge's relevance order.
`direction?`	`'asc' \| 'desc'`	`'desc'`
`perPage?`	`number`		How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`		Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `CodeSearchQuery` A search for code. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Description
`text?`	`string`	Free text, matched against the contents of files.
`queryRaw?`	`string`	Forge-native query syntax; see `SearchQuery.queryRaw` .
`repo?`	`RepoRef`	Limit to one repository.
`owner?`	`string`	Limit to one account or namespace.
`perPage?`	`number`	How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`	Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

## Releases ### `ReleaseRef` A release, as a notification subject or event target. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`repo`	`RepoRef`
`id`	`string`	Forge-native release id; the tag name on forges that key releases by tag.
`tag?`	`string`
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `ReleaseAssetRef` A release asset, addressable for download with `releases.downloadAsset`. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`repo`	`RepoRef`
`release`	`ReleaseRef`
`id`	`string`	Forge-native asset id; the asset name, or the link id, on forges that have no asset id.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `ReleaseAsset` A file attached to a release.

Member	Type	Description
`ref?`	`ReleaseAssetRef`	Absent where the forge publishes a download URL but nothing to address the asset by.
`name`	`string`
`url`	`string`
`size?`	`number`
`downloadCount?`	`number`
`contentType?`	`string`	The media type.

### `Release` A release of a repository.

Member	Type	Description
`ref`	`ReleaseRef`
`name?`	`string`
`tag`	`string`
`body?`	`string`	The release notes.
`isDraft`	`boolean`
`isPrerelease`	`boolean`
`immutable?`	`boolean`	The release is immutable: its tag and assets are locked. `true` where the forge supports immutable releases and this one is published as immutable (GitHub). The name, notes, prerelease and latest flags stay editable.
`author?`	`Actor`
`publishedAt?`	`Date`
`createdAt?`	`Date`
`url?`	`string`
`assets?`	`ReleaseAsset[]`

### `ReleaseInput` The fields that `releases.create()` sets.

Member	Type	Description
`tag`	`string`	The tag to release. The forge creates it from `target` when it does not exist yet.
`name?`	`string`
`body?`	`string`	The release notes.
`draft?`	`boolean`	Saves the release unpublished. `true` rejects with `UnsupportedOperationError` on a forge without drafts.
`prerelease?`	`boolean`	Marks the release as a prerelease. `true` rejects with `UnsupportedOperationError` on a forge without prereleases.
`target?`	`string`	The branch or commit sha to create the tag from when it does not exist yet. GitHub, Forgejo and Gitea default to the default branch; GitLab requires it for a new tag.

### `ReleaseUpdate` The fields that `releases.update()` changes. Fields left out stay as they are. **type:** [`Partial`](https://forges.link/reference/data-model#releaseinput) ### `DownloadAssetOptions` Options for `releases.downloadAsset()`. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Default	Description
`as?`	`'stream' \| 'binary' \| 'text'`	`'stream'`	`'binary'` reads the whole asset into a `Uint8Array` , and `'text'` decodes it as UTF-8, rejecting with `ContentNotTextError` when the bytes are not text. `'stream'` returns the bytes as they arrive.
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

## Security alerts ### `SecurityAlertKind` What an alert is about. `other` is a kind that the model does not name. **one of:** - `'dependency'` - `'code_scanning'` - `'secret'` - `'advisory'` - `'other'` ### `SecurityAlertRef` A security alert: a vulnerable dependency, a code scanning result, a leaked secret or an advisory. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`repo`	`RepoRef`
`id`	`string`	Forge-native alert id. GitHub numbers each alert kind separately, so `kind` is needed to address one.
`kind?`	`SecurityAlertKind`
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `SecuritySeverity` How severe an alert is. `unknown` is a level that the model does not name. **one of:** - `'critical'` - `'high'` - `'medium'` - `'low'` - `'unknown'` ### `SecurityAlert` A security alert on a repository.

Member	Type	Description
`ref`	`SecurityAlertRef`
`kind`	`SecurityAlertKind`
`severity`	`SecuritySeverity`
`state`	`'open' \| 'fixed' \| 'dismissed' \| 'unknown'`
`title`	`string`	A short description of the problem.
`package?`		`ecosystem` is absent where the forge reports only the package name.
`url?`	`string`
`createdAt?`	`Date`
`updatedAt?`	`Date`
`dismissedAt?`	`Date`

### `SecurityAlertListOptions` Filters for `securityAlerts.list()`. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Default	Description
`kind?`	`Exclude`		Omitted lists every kind the provider can read, one after another.
`state?`	`'open' \| 'closed' \| 'all'`	`'open'`	`'closed'` is fixed or dismissed.
`perPage?`	`number`		How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`		Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

## Webhooks ### `WebhookVerificationError` A delivery's signature didn't match. **extends:** [`ForgeError`](https://forges.link/reference/errors#forgeerror) ### `WebhookRef` Reference to a registered webhook. `target` is the repository, or a namespace ref (`kind: 'namespace'`, empty `name`) for an organisation or workspace hook. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`target`	`RepoRef`	The repository or namespace that the hook is registered on.
`id`	`string`	Forge-native hook id.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `WebhookDeliveryRef` Reference to one delivery of a webhook. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`hook`	`WebhookRef`
`id`	`string`
`guid?`	`string`	Delivery guid, where the forge needs it to redeliver.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `WebhookEventType` A normalised event a provider can deliver, optionally narrowed to one action.

Member	Type
`kind`	`EventKind`
`action?`	`EventAction`

### `Webhook` A registered webhook. The secret is never readable, so it is never returned.

Member	Type	Description
`ref`	`WebhookRef`
`url`	`string`
`events`	`EventKind[]`	Normalised kinds the subscription covers, derived from `nativeEvents` .
`nativeEvents`	`string[]`	Forge-native event names exactly as the forge stores them.
`active`	`boolean`
`contentType?`	`'json' \| 'form'`	`'json'` or `'form'` where the forge offers a choice.
`createdAt?`	`Date`
`updatedAt?`	`Date`
`secret?`	`never`	Never returned: no forge reads a webhook secret back.

### `WebhookInput` What `webhooks.create()` needs to register a hook.

Member	Type	Default	Description
`url`	`string`
`events?`	`EventKind[]`		Normalised kinds, translated to the forge's own event names.
`nativeEvents?`	`string[]`		Forge-native event names, sent as given and merged with the translation of `events` .
`secret?`	`string`		The secret that signs the deliveries.
`contentType?`	`'json' \| 'form'`		How to encode the delivery body.
`active?`	`boolean`	`true`

### `WebhookUpdate` A change to a registered webhook. Fields left out are left as they are. **type:** [`Partial`](https://forges.link/reference/data-model#webhookinput) ### `WebhookDeliveryRecord` One recorded delivery attempt.

Member	Type	Description
`ref`	`WebhookDeliveryRef`
`event`	`string`	Forge-native event name of the delivery.
`status`	`number`	The HTTP status that the receiver answered with.
`ok`	`boolean`	`true` when the forge considered the delivery successful.
`deliveredAt?`	`Date`
`duration?`	`number`	Round trip in milliseconds, where the forge reports it.

### `WebhookDelivery` A webhook delivery as received: its headers, its raw body and, optionally, the secret to verify it with.

Member	Type	Description
`headers`	`Headers \| Record`	The request headers, which carry the signature and the event name.
`body`	`string \| Uint8Array`	Raw body exactly as received; signatures are computed over these bytes.
`secret?`	`string`	Overrides the provider-level `webhookSecret` for this delivery.

## Notifications and events ### `EventKind` What an event is about. **one of:** - `'comment'` - `'review'` - `'review_comment'` - `'commit'` - `'label'` - `'state_change'` - `'assignment'` - `'mention'` - `'referenced'` - `'reaction'` - `'push'` - `'ref'` - `'repo'` - `'installation'` - `'membership'` - `'release'` - `'star'` - `'fork'` - `'wiki'` - `'other'` ### `PushCommit` A commit as a push delivery reports it.

Member	Type
`sha`	`string`
`message?`	`string`
`author?`	`string`
`url?`	`string`

### `EventAction` What happened, independent of `kind`, so "anything that closed" is `action === 'closed'` whatever the subject. **one of:** - `'opened'` - `'closed'` - `'reopened'` - `'merged'` - `'edited'` - `'created'` - `'deleted'` - `'submitted'` - `'labelled'` - `'unlabelled'` - `'assigned'` - `'unassigned'` - `'review_requested'` - `'synchronised'` - `'ready_for_review'` - `'converted_to_draft'` - `'published'` - `'renamed'` - `'transferred'` - `'archived'` - `'unarchived'` - `'added'` - `'removed'` - `'other'` ### `EventDetail` Typed detail for an event. Discriminated by `type`. **one of:** - [`{ type: 'comment', comment?: CommentRef, body?: string }`](https://forges.link/reference/data-model#commentref) - [`{ type: 'review_comment', comment?: CommentRef, body?: string, path?: string, line?: number }`](https://forges.link/reference/data-model#commentref) - `{ type: 'review', state: ReviewState, stateRaw?: string, body?: string, review?: ReviewRef }` - [`{ type: 'state_change', state?: ThreadState, draft?: boolean, reason?: string }`](https://forges.link/reference/data-model#threadstate) - `{ type: 'label', label: string }` - [`{ type: 'assignment', assignee?: Actor }`](https://forges.link/reference/data-model#actor) - [`{ type: 'push', ref: string, before?: string, after?: string, commitCount?: number, forced: boolean, commits: PushCommit[] }`](https://forges.link/reference/data-model#pushcommit) - `{ type: 'ref', ref: string, refType: 'branch' | 'tag' | (string & {}) }` - `{ type: 'repo_renamed', from: string, to: string }` - `{ type: 'repo_transferred', fromOwner?: string, toOwner?: string }` - `{ type: 'repo_archived', archived: boolean }` - [`{ type: 'installation', actionRaw: string, installationId?: string, added: RepoRef[], removed: RepoRef[] }`](https://forges.link/reference/data-model#reporef) - [`{ type: 'membership', actionRaw: string, member?: Actor }`](https://forges.link/reference/data-model#actor) - [`{ type: 'release', release?: ReleaseRef, tag?: string, name?: string, body?: string, isPrerelease?: boolean, isDraft?: boolean, url?: string }`](https://forges.link/reference/data-model#releaseref) - [`{ type: 'fork', fork?: RepoRef }`](https://forges.link/reference/data-model#reporef) - `{ type: 'wiki', title?: string, url?: string }` - `{ type: 'repo_visibility', isPublic: boolean }` - `{ type: 'referenced', from?: ThreadRef | CommitRef, fromRepo?: RepoRef, text?: string }` ### `ForgeEvent` An event on a forge, such as a comment, a state change or a push. **extends:** [`ForgeOrigin`](https://forges.link/reference/data-model#forgeorigin)

Member	Type	Description
`id`	`string`
`kind`	`EventKind`
`action`	`EventAction`	Normalised verb; `other` when the forge's wording has no equivalent.
`summary`	`string`	Single line describing the event, suitable for a list row.
`occurredAt`	`Date`	When the event happened, from the forge's own timestamp unless `undated` is set.
`undated?`	`boolean`	Whether the forge reported no time for the event. `occurredAt` is then the time the event reached `forges` (or Jetstream, for a Tangled subscription), or the Unix epoch for an entry of a thread's timeline.
`actor?`	`Actor`
`repo?`	`RepoRef`
`thread?`	`ThreadRef`
`threadSnapshot?`	`ThreadSnapshot`	What the event's source says about `thread` , as of when the forge built the payload.
`isPublic?`	`boolean`	Whether anyone can see the event, where the forge says so. `false` covers private and internal repositories alike.
`detail?`	`EventDetail`	The details that belong to the kind of event.
`installationId?`	`string`	App installation the delivery belongs to, for app webhooks.
`source`	`SourceKind`	Delivery mechanism the event arrived through.
`forge`	`ForgeKind`	Inherited from `ForgeOrigin` .
`instance`	`ForgeInstance`	The host of the instance, such as `github.com` or `git.example.com` . Inherited from `ForgeOrigin` .

### `SourceKind` How an event reached the caller. **one of:** - `'poll'` - `'webhook'` - `'subscribe'` ### `NotificationReason` Why a notification was delivered. `'unknown'` covers forges that report no reason and native reasons with no normalised equivalent; `reasonRaw` keeps the original. **one of:** - `'access_requested'` - `'approval_requested'` - `'assigned'` - `'author'` - `'ci_activity'` - `'comment'` - `'followed'` - `'invitation'` - `'manual'` - `'mention'` - `'merge_blocked'` - `'review_requested'` - `'review_submitted'` - `'security_alert'` - `'starred'` - `'state_change'` - `'subscribed'` - `'team_mention'` - `'unknown'` ### `NotificationSubject` What a notification is about. Not every notification concerns a thread. **one of:** - [`{ type: 'thread', thread: ThreadRef }`](https://forges.link/reference/data-model#threadref) - [`{ type: 'repo', repo: RepoRef }`](https://forges.link/reference/data-model#reporef) - [`{ type: 'actor', actor: Actor }`](https://forges.link/reference/data-model#actor) - [`{ type: 'release', release: ReleaseRef }`](https://forges.link/reference/data-model#releaseref) - [`{ type: 'security_alert', alert: SecurityAlertRef }`](https://forges.link/reference/data-model#securityalertref) - [`{ type: 'other', typeRaw: string, repo?: RepoRef, id?: string, url?: string }`](https://forges.link/reference/data-model#reporef) ### `Notification` A notification of the authenticated account.

Member	Type	Description
`ref`	`NotificationRef`
`subject`	`NotificationSubject`
`reason`	`NotificationReason`	Why the account got the notification.
`unread`	`boolean`
`title`	`string`
`subjectState`	`ThreadState`	State of a thread subject as reported by the notification payload.
`updatedAt`	`Date`
`lastReadAt?`	`Date`
`url?`	`string`
`latestComment?`	`ResolvedCommentRef`	The latest comment on a thread subject, where the forge links it. Read it with `threads.getComment()` . Absent when the latest activity is not a comment on the thread, such as a review comment.

### `EventFeedOptions` Options for `repos.events()` and `users.events()`. **extends:** [`PageOptions`](https://forges.link/reference/requests#pageoptions)

Member	Type	Default	Description
`force?`	`boolean`	`false`	Read the first page even when the forge asked to wait longer between reads, as GitHub does with `X-Poll-Interval` . Without it, such a read returns a `throttled` page.
`perPage?`	`number`		How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`		Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `NotificationListOptions` Options for `notifications.list()`. **extends:** [`ListOptions`](https://forges.link/reference/requests#listoptions)

Member	Type	Default	Description
`all?`	`boolean`	`false`	Include notifications already marked read.
`force?`	`boolean`	`false`	Read the first page even when the forge asked to wait longer between reads, as GitHub does with `X-Poll-Interval` . Without it, such a read returns a `throttled` page.
`since?`	`Date`		Only items updated at or after this time. Inherited from `ListOptions` .
`perPage?`	`number`		How many items to ask for. The forge may return fewer. Inherited from `PageOptions` .
`cursor?`	`Cursor`		Resume after the page that returned this cursor. Inherited from `PageOptions` .
`signal?`	`AbortSignal`		Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `BulkNotificationOptions` Options for `markAllRead()` and `markAllDone()`. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Description
`repo?`	`RepoRef`	Limit to one repository.
`before?`	`Date`	Only notifications updated before this time.
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

### `NotificationWriteOptions` Options for changing one notification. **extends:** [`BaseOptions`](https://forges.link/reference/requests#baseoptions)

Member	Type	Description
`thread?`	`ThreadRef`	The thread the notification points at, when the caller already holds it. Providers that would otherwise look it up skip that request.
`signal?`	`AbortSignal`	Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from `BaseOptions` .

## Dates ### `reviveDates()` Turns the ISO strings `JSON.stringify` left in a model value back into `Date`s, at any depth, for every field in [`DATE_FIELDS`](https://forges.link/reference/data-model#date_fields), skipping `raw` and `payload`. Returns a copy. ```ts function reviveDates(value: T): T ```

Parameter	Type
`value`	`T`

**Returns:** `T` ### `DATE_FIELDS` Every `Date` field in the model, by name. **type:** `ReadonlySet` These exports are documented elsewhere: [`ReposApi`](https://forges.link/reference/repositories#providerrepos), [`InstallationsApi`](https://forges.link/reference/repositories#providerinstallations), [`UsersApi`](https://forges.link/reference/repositories#providerusers), [`ThreadsApi`](https://forges.link/reference/threads#providerthreads), [`ChecksApi`](https://forges.link/reference/notifications#providerchecks), [`CiApi`](https://forges.link/reference/notifications#providerci), [`ReleasesApi`](https://forges.link/reference/repositories#providerreleases), [`SecurityAlertsApi`](https://forges.link/reference/notifications#providersecurityalerts), [`WebhooksApi`](https://forges.link/reference/notifications#providerwebhooks), [`NotificationsApi`](https://forges.link/reference/notifications#providernotifications). ## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.