---
title: "Providers"
description: "Create providers and combine them in a registry."
canonical_url: "https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers"
---
# Providers

> Create providers and combine them in a registry.

Each forge has a factory such as `github()`, which creates a provider. Pass providers to `createForges()` to combine them.

## Options and authentication

### `ForgeOptionsBase`

Options that every provider accepts.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      API base URL. Defaults to the forge's public instance.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several.
    </td>
  </tr>
</tbody>
</table>

### `TokenAuth`

A bearer or personal access token.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        'token'
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        token
      </code>
    </td>
    
    <td>
      <code>
        string | (() => string | Promise<string>)
      </code>
    </td>
    
    <td>
      Personal access token or OAuth access token. A function is called before every request, so a refreshed token applies without a new provider.
    </td>
  </tr>
</tbody>
</table>

### `BasicAuth`

HTTP Basic credentials, for example a Bitbucket app password or Atlassian API token.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        'basic'
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        username
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        password
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The password, app password or API token.
    </td>
  </tr>
</tbody>
</table>

### `AppAuth`

App credentials. Omit `installationId` to act as the app itself.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        'app'
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        appId
      </code>
    </td>
    
    <td>
      <code>
        string | number
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        privateKey
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      PEM private key: RSA (PKCS#1 or PKCS#8) on GitHub, Ed25519 PKCS#8 on Cursor Origin.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        installationId?
      </code>
    </td>
    
    <td>
      <code>
        string | number
      </code>
    </td>
    
    <td>
      The installation to act as. Omit it to act as the app itself.
    </td>
  </tr>
</tbody>
</table>

### `AnonymousAuth`

No credentials: public reads only. Every write, notifications and subscriptions are unsupported.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        'anonymous'
      </code>
    </td>
  </tr>
</tbody>
</table>

### `AuthKind`

The credential types that a provider can accept.

**one of:**

- `'token'`
- `'basic'`
- `'app'`
- `'app_password'`
- `'oauth'`
- `'anonymous'`

## GitHub

### `GitHubTokenKind`

What a GitHub token can call:

- `classic`: a personal access token (classic) or an OAuth app token;
- `fine-grained`: a fine-grained personal access token;
- `app-user`: a GitHub App user access token;
- `installation`: a GitHub App installation access token, such as the `GITHUB_TOKEN` of a workflow.

**one of:**

- `'classic'`
- `'fine-grained'`
- `'app-user'`
- `'installation'`

### `GitHubTokenAuth`

A GitHub token.

**extends:** [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        kind?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#githubtokenkind">
        <code>
          GitHubTokenKind
        </code>
      </a>
    </td>
    
    <td>
      What kind of token <code>
        token
      </code>
      
       is. Read from the prefix of a string <code>
        token
      </code>
      
       when omitted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        'token'
      </code>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth">
        <code>
          TokenAuth
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        token
      </code>
    </td>
    
    <td>
      <code>
        string | (() => string | Promise<string>)
      </code>
    </td>
    
    <td>
      Personal access token or OAuth access token. A function is called before every request, so a refreshed token applies without a new provider. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth">
        <code>
          TokenAuth
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `GitHubAuth`

The credentials GitHub accepts: a token, a GitHub App, or none for anonymous reads.

**one of:**

- [`GitHubTokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#githubtokenauth)
- [`AppAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#appauth)
- [`AnonymousAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#anonymousauth)

### `GitHubOptions`

Options for `github()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#githubauth">
        <code>
          GitHubAuth
        </code>
      </a>
    </td>
    
    <td>
      <code>
        { type: 'anonymous' }
      </code>
    </td>
    
    <td>
      How to authenticate. Without credentials, only public reads work.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      API base URL. Defaults to the forge's public instance. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `TypedGraphQLDocument`

A GraphQL document that carries the types of its result and variables, such as a `TypedDocumentString`
from GraphQL Code Generator with `documentMode: 'string'`.

**type parameters:** `TResult, TVariables`

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        valueOf()
      </code>
    </td>
    
    <td>
      <code>
        () => string
      </code>
    </td>
    
    <td>
      The text of the document.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        __apiType()?
      </code>
    </td>
    
    <td>
      <code>
        (variables: TVariables) => TResult
      </code>
    </td>
    
    <td>
      Carries the types; it has no value at runtime.
    </td>
  </tr>
</tbody>
</table>

### `GitHubGraphQL`

`provider.graphql()`: the result type comes from a [`TypedGraphQLDocument`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#typedgraphqldocument), or from the type argument of a plain string.

### `GitHubProvider`

A provider that `github()` creates: every [`ForgeProvider`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider) member, and GitHub's GraphQL API.

**extends:** [`ForgeProvider<true>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        graphql
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#githubgraphql">
        <code>
          GitHubGraphQL
        </code>
      </a>
    </td>
    
    <td>
      Runs a GraphQL query or mutation against the provider's GitHub API and returns its <code>
        data
      </code>
      
      . A read-only provider runs queries and rejects mutations with <code>
        ReadOnlyError
      </code>
      
      . Variables are required when the document is typed and declares a required variable.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        request
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#forgerequest">
        <code>
          ForgeRequest
        </code>
      </a>
    </td>
    
    <td>
      Requests endpoints relative to <code>
        baseUrl
      </code>
      
       or absolute HTTP(S) URLs. Other origins omit default headers and provider credentials; explicit headers apply. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        forge
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgekind">
        <code>
          ForgeKind
        </code>
      </a>
    </td>
    
    <td>
      The forge this provider sends requests to; matches <code>
        forge
      </code>
      
       on every ref it returns. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgeinstance">
        <code>
          ForgeInstance
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        authKind
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#authkind">
        <code>
          AuthKind
        </code>
      </a>
    </td>
    
    <td>
      The <code>
        auth.type
      </code>
      
       the provider was created with; <code>
        'anonymous'
      </code>
      
       when it sends no credentials. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilities
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider#forgecapabilities">
        <code>
          ForgeCapabilities
        </code>
      </a>
    </td>
    
    <td>
      Static, no-network capabilities until <code>
        refreshCapabilities()
      </code>
      
       resolves. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refreshCapabilities()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider#forgecapabilities">
        <code>
          () => Promise<ForgeCapabilities>
        </code>
      </a>
    </td>
    
    <td>
      Re-derives capabilities from the instance version. The version is read once per provider (GHES <code>
        /meta
      </code>
      
      , GitLab, Forgejo and Gitea <code>
        /version
      </code>
      
      ). Updates <code>
        capabilities
      </code>
      
       and returns it. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rateLimits()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#ratelimit">
        <code>
          () => RateLimit[]
        </code>
      </a>
    </td>
    
    <td>
      The request budgets of the latest responses, one per <code>
        resource
      </code>
      
      , read without sending a request. GitHub keeps a budget per resource, such as <code>
        core
      </code>
      
      , <code>
        search
      </code>
      
       and <code>
        graphql
      </code>
      
      ; other forges report one budget with no <code>
        resource
      </code>
      
      . Empty until a response reports a budget. A budget whose <code>
        resetAt
      </code>
      
       has passed is left out. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        normaliseMarkdown()
      </code>
    </td>
    
    <td>
      <code>
        (body: string) => string
      </code>
    </td>
    
    <td>
      Rewrites Markdown into the dialect the forge renders; returns it unchanged where the forge renders CommonMark. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/repositories#providerrepos">
        <code>
          ReposApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notifications
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/notifications#providernotifications">
        <code>
          NotificationsApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sources
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/notifications#providersources">
        <code>
          SourcesApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        threads
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/threads#providerthreads">
        <code>
          ThreadsApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhooks
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/notifications#providerwebhooks">
        <code>
          WebhooksApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        installations
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/repositories#providerinstallations">
        <code>
          InstallationsApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        releases
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/repositories#providerreleases">
        <code>
          ReleasesApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contents
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/repositories#providercontents">
        <code>
          ContentsApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        commits
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/repositories#providercommits">
        <code>
          CommitsApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checks
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/notifications#providerchecks">
        <code>
          ChecksApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ci
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/notifications#providerci">
        <code>
          CiApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        users
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/repositories#providerusers">
        <code>
          UsersApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/repositories#providersearch">
        <code>
          SearchApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        securityAlerts
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/notifications#providersecurityalerts">
        <code>
          SecurityAlertsApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        orgs
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/repositories#providerorgs">
        <code>
          OrgsApi
        </code>
      </a>
    </td>
    
    <td>
      Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        can()
      </code>
    </td>
    
    <td>
      <code>
        (verb: ForgeVerb, kind?: ThreadKind | SecurityAlertKind) => boolean
      </code>
    </td>
    
    <td>
      Whether <code>
        verb
      </code>
      
       is supported, for <code>
        kind
      </code>
      
       where support differs by kind, including version gates. Every verb is always present and rejects with <code>
        UnsupportedOperationError
      </code>
      
       when this is <code>
        false
      </code>
      
      : the capability is the question, the method is the action. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        support()
      </code>
    </td>
    
    <td>
      <code>
        (verb: ForgeVerb, kind?: ThreadKind | SecurityAlertKind) => Support
      </code>
    </td>
    
    <td>
      How well <code>
        verb
      </code>
      
       is supported: <code>
        true
      </code>
      
      , <code>
        'emulated'
      </code>
      
      , <code>
        'not_applicable'
      </code>
      
       or <code>
        false
      </code>
      
      , for <code>
        kind
      </code>
      
       where support differs by kind. <code>
        can()
      </code>
      
       is <code>
        true
      </code>
      
       for every level but <code>
        false
      </code>
      
       and <code>
        'not_applicable'
      </code>
      
      . Without <code>
        kind
      </code>
      
      , a per-kind verb reports its strongest level across kinds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        urlFor()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          (target: { repo: RepoRef, section?: undefined }) => HasWeb extends true ? string : string | undefined
        </code>
      </a>
    </td>
    
    <td>
      The web page for <code>
        target
      </code>
      
      , built without a request; <code>
        undefined
      </code>
      
       when the forge has no such page. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webOrigin
      </code>
    </td>
    
    <td>
      <code>
        HasWeb extends true ? string : string | undefined
      </code>
    </td>
    
    <td>
      The canonical origin of the forge's website for this instance, such as <code>
        https://github.com
      </code>
      
       (without any deployment path), or <code>
        undefined
      </code>
      
       when the forge has no website. Useful for resolving root-relative links and for building a content security policy. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        scopesFor()
      </code>
    </td>
    
    <td>
      <code>
        (verb: ForgeVerb) => VerbScopes
      </code>
    </td>
    
    <td>
      Token scopes or app permissions <code>
        verb
      </code>
      
       needs on this forge, as data for a consent screen or a 403 explanation. Nothing in the library reads it, and an unmapped verb returns <code>
        {}
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseUrl()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#parsedforgeurl">
        <code>
          (url: string | URL) => ParsedForgeUrl | undefined
        </code>
      </a>
    </td>
    
    <td>
      Reads a web URL, clone URL or npm <code>
        repository
      </code>
      
       value (<code>
        git+https://
      </code>
      
      , <code>
        github:owner/name
      </code>
      
      ) on this provider's instance into refs; <code>
        undefined
      </code>
      
       for anything else. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        referenceFor()
      </code>
    </td>
    
    <td>
      <code>
        (ref: ThreadRef | CommitRef, options?: ReferenceOptions) => string | undefined
      </code>
    </td>
    
    <td>
      How to mention <code>
        ref
      </code>
      
       in Markdown on this forge (<code>
        #42
      </code>
      
      , <code>
        !42
      </code>
      
      , <code>
        acme/widgets#42
      </code>
      
      , <code>
        acme/widgets@abc1234
      </code>
      
      ), short when written in <code>
        from
      </code>
      
      ; the page URL where the forge has no reference syntax. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseReferences()
      </code>
    </td>
    
    <td>
      <code>
        (text: string, options: ParseReferencesOptions) => ParsedReference[]
      </code>
    </td>
    
    <td>
      The references to threads and commits in <code>
        text
      </code>
      
      , as <code>
        referenceFor()
      </code>
      
       writes them and people type them (<code>
        #42
      </code>
      
      , <code>
        !42
      </code>
      
      , <code>
        GH-42
      </code>
      
      , <code>
        acme/widgets#42
      </code>
      
      , <code>
        acme/widgets@abc1234
      </code>
      
       or a bare sha), with their offsets, in order. <code>
        #42
      </code>
      
       reads as an issue where issues and pull requests share numbers; <code>
        threads.get()
      </code>
      
       returns the thread with its kind. A bare sha has 7 to 40 hex characters, with a letter and a digit. Text inside a URL is skipped, but code spans are not, so leave them out of <code>
        text
      </code>
      
      . Empty when <code>
        from
      </code>
      
       is on another instance, or the forge has no reference syntax. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `github()`

Creates a GitHub provider for github.com or a GitHub Enterprise Server instance.

```ts
function github(options?: GitHubOptions): GitHubProvider & { readonly forge: "github"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#githuboptions">
        <code>
          GitHubOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`GitHubProvider & { readonly forge: "github"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#githubprovider)

## GitLab

### `GitLabAuth`

Personal, project, group or OAuth access token.

**one of:**

- [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)
- [`AnonymousAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#anonymousauth)

### `GitLabOptions`

Options for `gitlab()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#gitlabauth">
        <code>
          GitLabAuth
        </code>
      </a>
    </td>
    
    <td>
      <code>
        { type: 'anonymous' }
      </code>
    </td>
    
    <td>
      How to authenticate. Without credentials, only public reads work.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Instance root, for example <code>
        https://gitlab.com
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `gitlab()`

Creates a GitLab provider for gitlab.com or a self-managed instance.

```ts
function gitlab(options?: GitLabOptions): ForgeProvider<true> & { readonly forge: "gitlab"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#gitlaboptions">
        <code>
          GitLabOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<true> & { readonly forge: "gitlab"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Bitbucket

### `BitbucketAuth`

Bitbucket Cloud credentials.

- `token`: an OAuth access token or a repository, project or workspace
access token, sent as a bearer token.
- `basic`: an Atlassian account email and API token.

**one of:**

- [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)
- [`BasicAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#basicauth)
- [`AnonymousAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#anonymousauth)

### `BitbucketOptions`

Options for `bitbucket()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#bitbucketauth">
        <code>
          BitbucketAuth
        </code>
      </a>
    </td>
    
    <td>
      <code>
        { type: 'anonymous' }
      </code>
    </td>
    
    <td>
      How to authenticate. Without credentials, only public reads work.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://api.bitbucket.org/2.0
      </code>
    </td>
    
    <td>
      API base.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `bitbucket()`

Creates a Bitbucket Cloud provider.

```ts
function bitbucket(options?: BitbucketOptions): ForgeProvider<true> & { readonly forge: "bitbucket"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#bitbucketoptions">
        <code>
          BitbucketOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<true> & { readonly forge: "bitbucket"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Forgejo

### `ForgejoAuth`

Forgejo and Gitea have no app-installation credential, so only tokens are accepted.

**one of:**

- [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)
- [`AnonymousAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#anonymousauth)

### `ForgejoOptions`

Options for `forgejo()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgejoauth">
        <code>
          ForgejoAuth
        </code>
      </a>
    </td>
    
    <td>
      <code>
        { type: 'anonymous' }
      </code>
    </td>
    
    <td>
      How to authenticate. Without credentials, only public reads work.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Instance root, for example <code>
        https://codeberg.org
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `forgejo()`

Creates a Forgejo provider for Codeberg or any self-hosted Forgejo instance.

```ts
function forgejo(options?: ForgejoOptions): ForgeProvider<true> & { readonly forge: "forgejo"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgejooptions">
        <code>
          ForgejoOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<true> & { readonly forge: "forgejo"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Gitea

### `GiteaOptions`

Options for `gitea()`, the same as for `forgejo()`.

**type:** [`ForgejoOptions`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgejooptions)

### `gitea()`

Creates a Gitea provider for gitea.com or any self-hosted Gitea instance.

```ts
function gitea(options?: ForgejoOptions): ForgeProvider<true> & { readonly forge: "gitea"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgejooptions">
        <code>
          ForgejoOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<true> & { readonly forge: "gitea"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Gitee

### `GiteeAuth`

A personal access token or OAuth access token, sent as `Authorization: token`.

**one of:**

- [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)
- [`AnonymousAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#anonymousauth)

### `GiteeOptions`

Options for `gitee()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#giteeauth">
        <code>
          GiteeAuth
        </code>
      </a>
    </td>
    
    <td>
      <code>
        { type: 'anonymous' }
      </code>
    </td>
    
    <td>
      How to authenticate. Without credentials, only public reads work.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://gitee.com
      </code>
    </td>
    
    <td>
      Instance root. <code>
        /api/v5
      </code>
      
       is appended.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `gitee()`

Creates a Gitee provider for gitee.com. The enterprise edition (`e.gitee.com`) is not covered.

```ts
function gitee(options?: GiteeOptions): ForgeProvider<true> & { readonly forge: "gitee"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#giteeoptions">
        <code>
          GiteeOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<true> & { readonly forge: "gitee"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Azure DevOps

### `AZURE_DEVOPS_API_VERSION`

The REST API version sent with every request; preview endpoints set their own.

**type:** `"7.1"`

### `AzureDevOpsAuth`

A personal access token (sent as basic auth with an empty user name), or explicit basic credentials.

**one of:**

- [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)
- [`BasicAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#basicauth)
- [`AnonymousAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#anonymousauth)

### `AzureDevOpsOptions`

Options for `azureDevOps()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#azuredevopsauth">
        <code>
          AzureDevOpsAuth
        </code>
      </a>
    </td>
    
    <td>
      <code>
        { type: 'anonymous' }
      </code>
    </td>
    
    <td>
      How to authenticate. Without credentials, only public reads work.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        organization
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The organization (or Azure DevOps Server collection) that <code>
        repos.list()
      </code>
      
       lists.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://dev.azure.com
      </code>
    </td>
    
    <td>
      For Azure DevOps Server, the server root, for example <code>
        https://tfs.example.com/tfs
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        issueType?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        Issue
      </code>
    </td>
    
    <td>
      Work item type <code>
        threads.create({ kind: 'issue' })
      </code>
      
       creates, read back as <code>
        thread.issueType
      </code>
      
      . Scrum projects use <code>
        Impediment
      </code>
      
       or <code>
        Product Backlog Item
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      <code>
        username:password
      </code>
      
       the service hook subscription sends as basic auth.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `azureDevOps()`

Creates an Azure DevOps provider for one organization on dev.azure.com, or a collection on Azure DevOps Server.

```ts
function azureDevOps(options: AzureDevOpsOptions): ForgeProvider<true> & { readonly forge: "azure-devops"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#azuredevopsoptions">
        <code>
          AzureDevOpsOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<true> & { readonly forge: "azure-devops"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Cursor Origin

### `CursorOriginAuth`

A user access token (what the Origin CLI sends, for example
`CURSOR_AUTH_TOKEN`), or an Origin App: its id and Ed25519 PKCS#8 private
key, optionally scoped to one installation. Personal Cursor API keys are
not Origin bearer tokens.

**one of:**

- [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)
- [`AppAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#appauth)

### `ORIGIN_API_VERSION`

The Origin API version this provider was built against. See `docs/content/4.providers/cursor-origin.md`.

**type:** `"v1alpha1"`

### `CursorOriginOptions`

Options for `cursorOrigin()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth?
      </code>
    </td>
    
    <td>
      <code>
        CursorOriginAuth | AnonymousAuth
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Token or app credentials. Cursor Origin's API has no anonymous access, so without <code>
        auth
      </code>
      
       the provider only verifies and translates webhook deliveries.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://api.cursor.com
      </code>
    </td>
    
    <td>
      API root. <code>
        /v1/origin
      </code>
      
       is appended.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `cursorOrigin()`

Creates a Cursor Origin provider. Experimental: built against the
`v1alpha1` API, which Cursor publishes as Early Beta.

```ts
function cursorOrigin(options?: CursorOriginOptions): ForgeProvider<boolean> & { readonly forge: "cursor-origin"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#cursororiginoptions">
        <code>
          CursorOriginOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<boolean> & { readonly forge: "cursor-origin"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Pushin.eu

### `PushinAuth`

A personal access token created in Settings (`pun_pat_…`), sent as `Authorization: Bearer`.

**one of:**

- [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)
- [`AnonymousAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#anonymousauth)

### `PushinOptions`

Options for `pushin()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#pushinauth">
        <code>
          PushinAuth
        </code>
      </a>
    </td>
    
    <td>
      <code>
        { type: 'anonymous' }
      </code>
    </td>
    
    <td>
      How to authenticate. Without credentials, only public reads work.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://pushin.eu
      </code>
    </td>
    
    <td>
      Instance root. <code>
        /api/v1
      </code>
      
       is appended.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `pushin()`

Creates a Pushin.eu provider.

```ts
function pushin(options?: PushinOptions): ForgeProvider<true> & { readonly forge: "pushin"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#pushinoptions">
        <code>
          PushinOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<true> & { readonly forge: "pushin"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Tangled

### `TangledAuth`

Credentials for writing records. Reads are public and need none.

- `app_password` creates a session on the account's PDS.
- `oauth` takes a `fetch` from an atproto OAuth client that already signs
requests (DPoP) for `pds`.

**one of:**

- [`AnonymousAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#anonymousauth)
- `{ type: 'app_password', identifier: string, password: string, pds?: string }`
- [`{ type: 'oauth', did: string, pds: string, fetch: FetchLike }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike)

### `TangledOptions`

Options for `tangled()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tangledauth">
        <code>
          TangledAuth
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      An app password session, an OAuth client that signs requests, or none for anonymous reads.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://tangled.org
      </code>
    </td>
    
    <td>
      Appview web root, used for links and as the <code>
        instance
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        apiUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Base for <code>
        request()
      </code>
      
      : a Bobbin-compatible XRPC index. Defaults to <code>
        https://api.tangled.org
      </code>
      
      , Tangled's public instance.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        plcUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      PLC directory for <code>
        did:plc
      </code>
      
       resolution. Defaults to the public directory, which is community infrastructure.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        backlinksUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Constellation-compatible backlink index.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        handleResolverUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Service for <code>
        com.atproto.identity.resolveHandle
      </code>
      
      , so a <code>
        RepoRef.owner
      </code>
      
       can be a handle. Defaults to <code>
        https://public.api.bsky.app
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        recordsUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Slingshot-compatible record cache, for example <code>
        https://slingshot.microcosm.blue
      </code>
      
      . By default records are read from each author's PDS.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        jetstreamUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Jetstream <code>
        subscribe
      </code>
      
       endpoint.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webSocket?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#websocketfactory">
        <code>
          WebSocketFactory
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Defaults to the global <code>
        WebSocket
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notificationsUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Base URL of a service implementing the experimental <code>
        org.tangled.temp.notification.*
      </code>
      
       lexicons (Tangled's deliberi). Its service DID is derived as <code>
        did:web:<host>
      </code>
      
      . Requires <code>
        auth
      </code>
      
      . The lexicons live in Tangled's <code>
        temp
      </code>
      
       namespace and may change or disappear.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        resolveDisplayNumber()?
      </code>
    </td>
    
    <td>
      <code>
        (repo: RepoRef, kind: ThreadKind, displayNumber: string) => Promise<string | undefined>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Maps a per-repo display number (as carried by webhooks) to the thread's AT-URI. When provided, <code>
        webhooks.ingest()
      </code>
      
       uses it to fill <code>
        number
      </code>
      
      . Records carry no numbers; the mapping exists only in an index of the appview's numbering.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sshHosts?
      </code>
    </td>
    
    <td>
      <code>
        Record<string, string>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Maps a knot host to the host that accepts git over SSH for it. <code>
        knot1.tangled.sh
      </code>
      
       maps to <code>
        tangled.org
      </code>
      
       by default.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        listSource?
      </code>
    </td>
    
    <td>
      <code>
        'records' | 'index'
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Where <code>
        threads.list
      </code>
      
       reads from. <code>
        'records'
      </code>
      
       (the default) reads every record and computes state with the appview's rule. <code>
        'index'
      </code>
      
       reads the Bobbin index at <code>
        apiUrl
      </code>
      
       instead: one request per page, but its states may lag behind the records, and every listing carries an <code>
        index_possibly_stale
      </code>
      
       warning.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `tangled()`

Creates a Tangled provider. Records are read from PDSes; pushes arrive through Jetstream.

```ts
function tangled(options?: TangledOptions): ForgeProvider<true> & { readonly forge: "tangled"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tangledoptions">
        <code>
          TangledOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<true> & { readonly forge: "tangled"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

### `WebSocketLike`

The subset of the WHATWG `WebSocket` the stream uses.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        addEventListener()
      </code>
    </td>
    
    <td>
      <code>
        (type: 'open' | 'message' | 'error' | 'close', listener: (event: { data?: unknown, code?: number, reason?: string }) => void) => void
      </code>
    </td>
    
    <td>
      Registers a listener for a socket event.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        close()
      </code>
    </td>
    
    <td>
      <code>
        (code?: number, reason?: string) => void
      </code>
    </td>
    
    <td>
      Closes the socket, optionally with a close code and reason.
    </td>
  </tr>
</tbody>
</table>

### `WebSocketFactory`

Opens a WebSocket for a URL, such as `url => new WebSocket(url)`.

**type:** [`(url: string) => WebSocketLike`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#websocketlike)

## Cloudflare Artifacts

### `CloudflareArtifactsAuth`

A Cloudflare API token with **Artifacts** > **Read**, sent as `Authorization: Bearer`.

**type:** [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)

### `CloudflareArtifactsOptions`

Options for `cloudflareArtifacts()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#cloudflareartifactsauth">
        <code>
          CloudflareArtifactsAuth
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      How to authenticate. Artifacts has no anonymous reads.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accountId
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The account that holds the namespaces. Its Git host is the instance of every ref.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://api.cloudflare.com
      </code>
    </td>
    
    <td>
      The Cloudflare API root. <code>
        /client/v4
      </code>
      
       is appended.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `cloudflareArtifacts()`

Creates a Cloudflare Artifacts provider for one account. A ref's instance is the
account's Git host, `<accountId>.artifacts.cloudflare.net`, and its owner a namespace.

```ts
function cloudflareArtifacts(options: CloudflareArtifactsOptions): ForgeProvider<false> & { readonly forge: "cloudflare-artifacts"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#cloudflareartifactsoptions">
        <code>
          CloudflareArtifactsOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<false> & { readonly forge: "cloudflare-artifacts"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Sourcehut

### `SourcehutAuth`

A Sourcehut personal access token or OAuth bearer token, sent as `Authorization: Bearer`.

**type:** [`TokenAuth`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#tokenauth)

### `SourcehutOptions`

Options for `sourcehut()`.

**extends:** [`ForgeOptionsBase`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        auth
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#sourcehutauth">
        <code>
          SourcehutAuth
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      How to authenticate. Every Sourcehut service refuses reads without a token.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://sr.ht
      </code>
    </td>
    
    <td>
      Instance root; each service is a subdomain of its host (<code>
        sr.ht
      </code>
      
       gives <code>
        meta.sr.ht
      </code>
      
      , <code>
        git.sr.ht
      </code>
      
      , <code>
        todo.sr.ht
      </code>
      
      , <code>
        lists.sr.ht
      </code>
      
      , <code>
        builds.sr.ht
      </code>
      
      ). <code>
        request()
      </code>
      
       takes an absolute URL and sends it to the service it names.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookPublicKey?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Base64 ed25519 public key used to verify inbound webhook deliveries. Defaults to the public key of <code>
        sr.ht
      </code>
      
      ; set it for a self-hosted instance.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A <code>
        fetch
      </code>
      
       to use instead of the global one, for tests and for runtimes without one. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        30000
      </code>
    </td>
    
    <td>
      Request timeout in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webhookSecret?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Shared secret used to verify inbound webhook deliveries. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The <code>
        user-agent
      </code>
      
       header. Defaults to <code>
        forges
      </code>
      
      , except in a browser, which sends its own. Setting it in a browser can trigger a CORS preflight that some forges reject. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instanceVersion?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Version of the forge instance, when the caller already knows it. Gates version-dependent capabilities without the network call <code>
        refreshCapabilities()
      </code>
      
       makes. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readOnly?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Every write, including a mutating <code>
        request()
      </code>
      
      , rejects with <code>
        ReadOnlyError
      </code>
      
       and reports <code>
        false
      </code>
      
      . Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRetry?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRetry']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called before a request is retried after a rate limit that names a wait of at most a minute, with the wait in milliseconds. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onRateLimit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/provider-kit#fetcheroptions">
        <code>
          FetcherOptions['onRateLimit']
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Called with the rate limit of every API response that reports one, so that you can follow the budget without reading <code>
        page.rateLimit
      </code>
      
      . <code>
        rateLimit.resource
      </code>
      
       names the budget where the forge has several. Inherited from <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeoptionsbase">
        <code>
          ForgeOptionsBase
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `sourcehut()`

Creates a Sourcehut provider. Sourcehut cannot write, so `readOnly` is always
set: it reports `subscriptions.set` unsupported, which no write is declared to
do, and it cannot be turned off.

```ts
function sourcehut(options: SourcehutOptions): ForgeProvider<true> & { readonly forge: "sourcehut"; }
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#sourcehutoptions">
        <code>
          SourcehutOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider<true> & { readonly forge: "sourcehut"; }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

## Forges registry

A registry routes each ref to the provider it belongs to.

### `createForges()`

Combines providers into a registry.

**Example**

```ts
import { createForges, github, gitlab, UnknownForgeError } from 'forges'

const forges = createForges([
  github({ auth: { type: 'token', token: process.env.GITHUB_TOKEN! } }),
  gitlab(),
])

const ref = { forge: 'github', instance: 'github.com', owner: 'danielroe', name: 'forges' } as const
const provider = forges.for(ref)
if (!provider) {
  throw new UnknownForgeError(`No provider registered for ${ref.forge} on ${ref.instance}`, ref)
}
const repo = await provider.repos.get(ref)
```

```ts
function createForges<const T extends readonly ForgeProvider[]>(providers: T): Forges<RegisteredKinds<T>>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        providers
      </code>
    </td>
    
    <td>
      <code>
        T
      </code>
    </td>
    
    <td>
      Providers such as <code>
        github()
      </code>
      
       creates.
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Forges<RegisteredKinds<T>>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers)

### `ProviderFactoryFunction`

The function `defineForgeProvider()` returns. Options are optional when every option is.

**type parameters:** `TOptions, HasWeb extends boolean = boolean, Forge extends ForgeKind = ForgeKind, TProvider extends ForgeProvider<HasWeb> = ForgeProvider<HasWeb>`

**type:** `Record<never, never> extends TOptions ? (options?: TOptions) => TProvider & { readonly forge: Forge } : (options: TOptions) => TProvider & { readonly forge: Forge }`

## Registry methods

### `providers`

**type:** [`ForgeProvider[]`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

### `get()`

First provider for `forge`, optionally narrowed to a single instance host. Typed as present for a forge in `Kind`.

**Overload 1 of 2**

```ts
get(forge: Kind): ForgeProvider
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        forge
      </code>
    </td>
    
    <td>
      <code>
        Kind
      </code>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

**Overload 2 of 2**

```ts
get(forge: ForgeKind, instance?: ForgeInstance): ForgeProvider | undefined
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        forge
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgekind">
        <code>
          ForgeKind
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgeinstance">
        <code>
          ForgeInstance
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider | undefined`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

### `all()`

Every provider for a forge.

```ts
all(forge: ForgeKind): ForgeProvider[]
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        forge
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgekind">
        <code>
          ForgeKind
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider[]`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

### `for()`

The provider a ref belongs to, by `forge` and `instance`.

```ts
for(ref: ForgeOrigin): ForgeProvider | undefined
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgeorigin">
        <code>
          ForgeOrigin
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider | undefined`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

### `forUrl()`

The provider whose instance serves `url`.

```ts
forUrl(url: string | URL): ForgeProvider | undefined
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      <code>
        string | URL
      </code>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider | undefined`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

### `parseUrl()`

Reads a web URL, clone URL or npm `repository` value on any registered instance.

```ts
parseUrl(url: string | URL): (ParsedForgeUrl & { provider: ForgeProvider }) | undefined
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      <code>
        string | URL
      </code>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `(ParsedForgeUrl & { provider: ForgeProvider }) | undefined`

### `parseReferences()`

The references in `text`, read by the provider of `options.from`; empty when none is registered.

```ts
parseReferences(text: string, options: ParseReferencesOptions): ParsedReference[]
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#parsereferencesoptions">
        <code>
          ParseReferencesOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ParsedReference[]`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#parsedreference)

### `notifications.list()`

Lists the notifications of every provider, provider by provider.

```ts
notifications.list(options?: Omit<NotificationListOptions, 'cursor'>): ForgeIterable<Notification>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#notificationlistoptions">
        <code>
          Omit<NotificationListOptions, 'cursor'>
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeIterable<Notification>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#notification)

### `threads.getMany()`

Reads threads from several forges at once: groups the refs by the provider each belongs to, batches each group
with that provider's `threads.getMany()`, and returns the results in input order. A ref whose origin is not
registered becomes a per-item warning.

```ts
threads.getMany(refs: ThreadRef[], options?: BaseOptions): Promise<GetManyResult[]>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        refs
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#threadref">
        <code>
          ThreadRef[]
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<GetManyResult[]>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#getmanyresult)

### `search.threads()`

Searches issues and pull requests on every provider that supports search.

```ts
search.threads(query?: Omit<ThreadSearchQuery, 'cursor' | 'sort'> & { sort?: 'created' | 'updated' }): ForgeIterable<Thread>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#threadsearchquery">
        <code>
          Omit<ThreadSearchQuery, 'cursor' | 'sort'> & { sort?: 'created' | 'updated' }
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeIterable<Thread>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#thread)

### `search.repos()`

Searches repositories on every provider that supports search.

```ts
search.repos(query?: Omit<RepoSearchQuery, 'cursor' | 'sort'> & { sort?: 'created' | 'updated' }): ForgeIterable<Repo>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reposearchquery">
        <code>
          Omit<RepoSearchQuery, 'cursor' | 'sort'> & { sort?: 'created' | 'updated' }
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeIterable<Repo>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#repo)

## Create from the environment

Import from `forges/env`. The variable names are listed under [Environment variables](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/environment-variables).

### `EnvProvider`

One set of variables that `providersFromEnv()` reads, and the provider it created from them.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        forge
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        suffix
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The part after the field, for example <code>
        WORK
      </code>
      
       in <code>
        FORGES_GITHUB_TOKEN_WORK
      </code>
      
      . Empty for the unsuffixed set.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        provider?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
    </td>
    
    <td>
      The provider to pass to <code>
        createForges()
      </code>
      
      . Missing when the set was skipped.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        skipped?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Why the set was skipped, when it was. Never contains a credential.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        demoRepo?
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      <code>
        DEMO_REPO
      </code>
      
      : a repository to show, as <code>
        owner/name
      </code>
      
      . GitLab owners may contain slashes.
    </td>
  </tr>
</tbody>
</table>

### `FromEnvOptions`

Options for `providersFromEnv()` and `forgesFromEnv()`.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        fetch?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#fetchlike">
        <code>
          FetchLike
        </code>
      </a>
    </td>
    
    <td>
      Passed to every provider, for tests and runtimes without a global <code>
        fetch
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `providersFromEnv()`

Reads provider sets from `FORGES_<KIND>_<FIELD>[_<SUFFIX>]` variables. A
suffix starts another instance of the same forge.

```ts
function providersFromEnv(env: Record<string, string | undefined>, options: FromEnvOptions = {}): EnvProvider[]
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        env
      </code>
    </td>
    
    <td>
      <code>
        Record<string, string | undefined>
      </code>
    </td>
    
    <td>
      The variables to read, such as <code>
        process.env
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#fromenvoptions">
        <code>
          FromEnvOptions
        </code>
      </a>
    </td>
    
    <td>
      Options that every provider is created with. Defaults to <code>
        {}
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`EnvProvider[]`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#envprovider)

### `forgesFromEnv()`

Builds `Forges` from environment variables; see [`providersFromEnv`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#providersfromenv).

**Example**

```ts
import { forgesFromEnv } from 'forges/env'

// FORGES_GITHUB_TOKEN=... FORGES_GITLAB_TOKEN=...
const forges = forgesFromEnv(process.env)
```

```ts
function forgesFromEnv(env: Record<string, string | undefined>, options: FromEnvOptions = {}): Forges
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        env
      </code>
    </td>
    
    <td>
      <code>
        Record<string, string | undefined>
      </code>
    </td>
    
    <td>
      The variables to read, such as <code>
        process.env
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#fromenvoptions">
        <code>
          FromEnvOptions
        </code>
      </a>
    </td>
    
    <td>
      Options that every provider is created with. Defaults to <code>
        {}
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Forges`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers)

## Web links without a client

Import from `forges/web`. Each factory takes the `baseUrl` and `instance` of its provider and reads and builds web URLs and references, with no API client. See [Links without a client](https://forgeslink-3mwmle35v-poetry.vercel.app/guides/bundling#links-without-a-client).

### `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'`

### `UrlTarget`

Something with a web page. A revision (`at`, `base` or `head`) is a branch,
tag or commit sha; Azure DevOps reads anything but a full commit sha as a branch.

**one of:**

- [`{ repo: RepoRef }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef)
- `{ repo: RepoRef, section: RepoSection }`
- [`{ thread: ThreadRef }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#threadref)
- [`{ comment: CommentRef }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commentref)
- [`{ release: ReleaseRef }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#releaseref)
- [`{ file: { repo: RepoRef, path: string, at: string, line?: number } }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef)
- [`{ raw: { repo: RepoRef, path: string, at: string } }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef)
- [`{ commit: { repo: RepoRef, sha: string } }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef)
- [`{ compare: { repo: RepoRef, base: string, head: string } }`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef)

### `ParsedForgeUrl`

What a forge web URL points at. `repo` is always set; the rest when the URL is that specific.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        thread?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#threadref">
        <code>
          ThreadRef
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        comment?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commentref">
        <code>
          CommentRef
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        commit?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitref">
        <code>
          CommitRef
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        release?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#releaseref">
        <code>
          ReleaseRef
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tag?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The tag of a tag page that is not a release page, such as GitLab's <code>
        -/tags/{tag}
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compare?
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The revisions of a page that compares two, such as <code>
        compare/{base}...{head}
      </code>
      
       or <code>
        compare/{base}..{head}
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        file?
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      A file page: the repository-relative <code>
        path
      </code>
      
      , the revision <code>
        at
      </code>
      
       and the first selected <code>
        line
      </code>
      
      . <code>
        at
      </code>
      
       is unset when the URL leaves the revision to the default branch. An unencoded <code>
        /
      </code>
      
       in a branch name reads as the start of <code>
        path
      </code>
      
      . Forges that address files and folders alike, such as Forgejo, Bitbucket and Azure DevOps, also set this for a folder.
    </td>
  </tr>
</tbody>
</table>

### `ReferenceOptions`

Options for `provider.referenceFor()`.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        from?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      Repository the reference is written in; a reference within it is the short form.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        expand?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Request the reference expanded to its title, where the forge supports it (GitLab's <code>
        +
      </code>
      
       suffix).
    </td>
  </tr>
</tbody>
</table>

### `ParseReferencesOptions`

Options for `provider.parseReferences()`.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        from
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      Repository the text is written in, which a short reference such as <code>
        #42
      </code>
      
       points into.
    </td>
  </tr>
</tbody>
</table>

### `ParsedReference`

A reference that `parseReferences()` found in text.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        start
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      The offset of the reference's first character.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        end
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      The offset just past the reference.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <code>
        ThreadRef | CommitRef
      </code>
    </td>
    
    <td>
      The thread or commit it refers to. A commit <code>
        sha
      </code>
      
       is as written, so it can be abbreviated.
    </td>
  </tr>
</tbody>
</table>

### `WebOptions`

Where a forge's instance is, as a provider's options give it.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        baseUrl?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      API base URL. Defaults to the forge's public instance.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance?
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Host used in refs and keys. Defaults to the host of <code>
        baseUrl
      </code>
      
      , with API subdomains mapped to the public host.
    </td>
  </tr>
</tbody>
</table>

### `ForgeWeb`

The web pages and references of one forge instance, without an API client.

**type parameters:** `Forge extends ForgeKind = ForgeKind`

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        forge
      </code>
    </td>
    
    <td>
      <code>
        Forge
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgeinstance">
        <code>
          ForgeInstance
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        webOrigin
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The origin of the forge's website, such as <code>
        https://github.com
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        urlFor()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          (target: { repo: RepoRef, section?: undefined }) => string
        </code>
      </a>
    </td>
    
    <td>
      The web page for <code>
        target
      </code>
      
      ; <code>
        undefined
      </code>
      
       when the forge has no such page.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseUrl()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#parsedforgeurl">
        <code>
          (url: string | URL) => ParsedForgeUrl | undefined
        </code>
      </a>
    </td>
    
    <td>
      Reads a web URL, clone URL or npm <code>
        repository
      </code>
      
       value on this instance into refs; <code>
        undefined
      </code>
      
       for anything else.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        referenceFor()
      </code>
    </td>
    
    <td>
      <code>
        (ref: ThreadRef | CommitRef, options?: ReferenceOptions) => string | undefined
      </code>
    </td>
    
    <td>
      How to mention <code>
        ref
      </code>
      
       in Markdown on this forge, short when written in <code>
        from
      </code>
      
      ; the page URL where the forge has no reference syntax.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseReferences()
      </code>
    </td>
    
    <td>
      <code>
        (text: string, options: ParseReferencesOptions) => ParsedReference[]
      </code>
    </td>
    
    <td>
      The references to threads and commits in <code>
        text
      </code>
      
      , with their offsets, in order.
    </td>
  </tr>
</tbody>
</table>

### `RoutedForge`

What `createForges()` routes between.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        forge
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgekind">
        <code>
          ForgeKind
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instance
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgeinstance">
        <code>
          ForgeInstance
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseUrl()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#parsedforgeurl">
        <code>
          (url: string | URL) => ParsedForgeUrl | undefined
        </code>
      </a>
    </td>
    
    <td>
      Reads a web URL, clone URL or npm <code>
        repository
      </code>
      
       value on this instance into refs; <code>
        undefined
      </code>
      
       for anything else.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseReferences()
      </code>
    </td>
    
    <td>
      <code>
        (text: string, options: ParseReferencesOptions) => ParsedReference[]
      </code>
    </td>
    
    <td>
      The references to threads and commits in <code>
        text
      </code>
      
      , with their offsets, in order.
    </td>
  </tr>
</tbody>
</table>

### `WebForges`

A registry of forges that routes each ref, URL or text to the forge it belongs to.

**type parameters:** `T extends RoutedForge = ForgeWeb`

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        providers
      </code>
    </td>
    
    <td>
      <code>
        T[]
      </code>
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        get()
      </code>
    </td>
    
    <td>
      <code>
        (forge: ForgeKind, instance?: ForgeInstance) => T | undefined
      </code>
    </td>
    
    <td>
      The first forge of kind <code>
        forge
      </code>
      
      , optionally on one instance.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        all()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgekind">
        <code>
          (forge: ForgeKind) => T[]
        </code>
      </a>
    </td>
    
    <td>
      Every instance of a forge.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        for()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#forgeorigin">
        <code>
          (ref: ForgeOrigin) => T | undefined
        </code>
      </a>
    </td>
    
    <td>
      The forge a ref belongs to, by <code>
        forge
      </code>
      
       and <code>
        instance
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        forUrl()
      </code>
    </td>
    
    <td>
      <code>
        (url: string | URL) => T | undefined
      </code>
    </td>
    
    <td>
      The forge whose instance serves <code>
        url
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseUrl()
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#parsedforgeurl">
        <code>
          (url: string | URL) => (ParsedForgeUrl & { provider: T }) | undefined
        </code>
      </a>
    </td>
    
    <td>
      Reads a web URL, clone URL or npm <code>
        repository
      </code>
      
       value on any registered instance.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseReferences()
      </code>
    </td>
    
    <td>
      <code>
        (text: string, options: ParseReferencesOptions) => ParsedReference[]
      </code>
    </td>
    
    <td>
      The references in <code>
        text
      </code>
      
      , read by the forge of <code>
        options.from
      </code>
      
      ; empty when none is registered.
    </td>
  </tr>
</tbody>
</table>

### `azureDevOps()`

The web links of Azure DevOps Services, or an Azure DevOps Server collection.

```ts
function azureDevOps(options?: WebOptions): ForgeWeb<"azure-devops">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"azure-devops">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `bitbucket()`

The web links of Bitbucket Cloud.

```ts
function bitbucket(options?: WebOptions): ForgeWeb<"bitbucket">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"bitbucket">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `forgejo()`

The web links of Codeberg or another Forgejo instance.

```ts
function forgejo(options?: WebOptions): ForgeWeb<"forgejo">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"forgejo">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `gitea()`

The web links of gitea.com or another Gitea instance.

```ts
function gitea(options?: WebOptions): ForgeWeb<"gitea">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"gitea">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `gitee()`

The web links of Gitee.

```ts
function gitee(options?: WebOptions): ForgeWeb<"gitee">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"gitee">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `github()`

The web links of github.com or a GitHub Enterprise instance.

```ts
function github(options?: WebOptions): ForgeWeb<"github">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"github">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `gitlab()`

The web links of gitlab.com or a self-managed GitLab instance.

```ts
function gitlab(options?: WebOptions): ForgeWeb<"gitlab">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"gitlab">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `pushin()`

The web links of Pushin.eu.

```ts
function pushin(options?: WebOptions): ForgeWeb<"pushin">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"pushin">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `sourcehut()`

The web links of sr.ht or another Sourcehut instance.

```ts
function sourcehut(options?: WebOptions): ForgeWeb<"sourcehut">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"sourcehut">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `tangled()`

The web links of Tangled.

```ts
function tangled(options?: WebOptions): ForgeWeb<"tangled">
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#weboptions">
        <code>
          WebOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeWeb<"tangled">`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#forgeweb)

### `createForges()`

Combines forges into a registry that reads URLs and references on any of them.

**Example**

```ts
import { createForges, github, gitlab } from 'forges/web'

const forges = createForges([github(), gitlab({ baseUrl: 'https://gitlab.example.com' })])
const parsed = forges.parseUrl('https://gitlab.example.com/acme/widgets/-/merge_requests/3')
```

```ts
function createForges<const T extends ForgeWeb>(forges: readonly T[]): WebForges<T>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        forges
      </code>
    </td>
    
    <td>
      <code>
        readonly T[]
      </code>
    </td>
    
    <td>
      Forges that the factories of <code>
        forges/web
      </code>
      
       create, or providers.
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`WebForges<T>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/providers#webforges)


## Sitemap

See the full [sitemap](https://forgeslink-3mwmle35v-poetry.vercel.app/sitemap.md) for all pages.