---
title: "Providers and factories"
description: "How provider functions, factories and Lite variants fit together."
canonical_url: "https://docs-8831a2g1f-poetry.vercel.app/concepts/providers"
---
# Providers and factories

> How provider functions, factories and Lite variants fit together.

This page explains how you create a provider, what every provider contains and how the Lite factories differ.

## Factories

`github()` and the other provider functions return a factory. A factory holds the options and builds the provider when you call `create()`. No request goes out until you call a method on the provider.

```ts
import { github } from 'forges/github'

const factory = github({
  auth: { type: 'token', token: process.env.GITHUB_TOKEN! },
})
const gh = factory.create()
```

`createForges()` accepts factories and calls `create()` on each one. This lets you describe providers in one place and build them where you need them.

## The provider interface

Every provider has the same shape. It has `kind`, `instance`, `baseUrl` and `capabilities`, plus namespaces for the operations: `repos`, `threads`, `notifications`, `checks`, `ci`, `contents`, `releases`, `webhooks`, `search`, `securityAlerts`, `installations`, `users` and `sources`. Reviews live on `threads`. The [provider API reference](https://docs-8831a2g1f-poetry.vercel.app/reference/provider-api) lists them.

All namespaces exist on all providers. An operation the forge lacks is present and rejects, so TypeScript doesn't force a cast at each call site. Use [`can()`](https://docs-8831a2g1f-poetry.vercel.app/guides/capabilities) to decide at run time.

## Escape hatch

`provider.request()` sends a request to an endpoint relative to `baseUrl`, or to an absolute HTTP(S) URL, with the provider's authentication, user agent, timeout and error mapping. Use it for an endpoint that the model doesn't cover.

A request to another origin leaves out the provider's credentials and default headers.

## Lite factories

Every provider except pushin.eu has a second factory, such as `githubLite()`. It builds the same provider without webhook ingestion. A browser doesn't receive deliveries, so a Lite bundle leaves out signature verification and payload translation. See [Browser bundles](https://docs-8831a2g1f-poetry.vercel.app/guides/bundling).

## Subpath exports

Each provider has its own subpath, such as `forges/gitlab`. The root entry re-exports all of them. The package declares `sideEffects: false`, so bundlers can tree-shake the root entry, and a subpath import states the dependency.

## Writing your own

A provider is one call to `defineForgeProvider()`. See [Write a provider](https://docs-8831a2g1f-poetry.vercel.app/contributing/write-a-provider).


## Sitemap

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