---
title: "Write a provider"
description: "Add a forge by declaring each operation once."
canonical_url: "https://docs-8831a2g1f-poetry.vercel.app/contributing/write-a-provider"
---
# Write a provider

> Add a forge by declaring each operation once.

A provider is one call to `defineForgeProvider()`. You declare each operation once, with `verb(support, run)`, or with `perKind(kinds, run)` when support depends on the thread kind. Each declaration produces both the method and its capability entry.

In this excerpt from a provider's `setup()`, issue reads are experimental and `getMany` is unsupported:

```ts
const threads = {
  get: perKind({ issue: 'experimental' }, getIssue),
  listPage: perKind({ issue: 'experimental' }, listIssues),
  getMany: verb(false, async () => []),
}
```

`forges` adds the rest of the provider: `capabilities`, `can()`, the iterables (`list` from `listPage`, for example), `readOnly`, anonymous handling and a `webhooks.ingest()` that verifies each delivery before it translates it.

## Declare operations

`ProviderSpec` in [`src/define.ts`](https://github.com/danielroe/forges/blob/main/src/define.ts) lists every operation and marks which ones are required. Declare a required operation that your forge lacks with `verb(false, ...)`. Any other operation that you leave out, and any thread kind that you don't list, is `false`.

[`src/pushin/index.ts`](https://github.com/danielroe/forges/blob/main/src/pushin/index.ts) is a short provider to read as an example.

## Handle webhooks

Webhook handlers go in the `webhooks` field of the definition. For a Lite variant, define a second factory from the same definition without `webhooks`.

## Send requests

Use `ctx.fetcher` for requests. It applies the base URL, auth header, user agent, timeout and the caller's `fetch`, and it maps rate limits and revoked tokens to `forges` errors.

## Run scripts without a build

Source files import each other with `.ts` extensions, so `node scripts/<name>.ts` runs without a build.

After you change a provider's capabilities, regenerate the [capability matrix](https://docs-8831a2g1f-poetry.vercel.app/reference/capability-matrix) and the table on each provider page:

```sh
pnpm capability-matrix
```

Then [record fixtures](https://docs-8831a2g1f-poetry.vercel.app/contributing/record-fixtures) so that capabilities can be `true`.


## Sitemap

See the full [sitemap](https://docs-8831a2g1f-poetry.vercel.app/sitemap.md) for all pages.