---
title: "Providers and factories"
description: "How provider functions and factories fit together."
canonical_url: "https://forgeslink-3mwmle35v-poetry.vercel.app/concepts/providers"
---
# Providers and factories

> How provider functions and factories fit together.

This page explains how you create a provider and what every provider contains.

## Factories

Each forge has a factory function, such as `github()`, that takes your options and returns a provider. Creating a provider sends no request. Nothing goes out until you call one of its methods.

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

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

To work with several forges at once, pass the providers to `createForges()`.

## The provider interface

Every provider has the same shape, whichever forge it talks to. It has `forge`, `instance`, `baseUrl` and `capabilities`, along with namespaces for the operations: `repos`, `threads`, `notifications`, `checks`, `ci`, `contents`, `releases`, `webhooks`, `search`, `securityAlerts`, `installations`, `users` and `sources`. Reviews live on `threads`. The [provider reference](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider) lists everything in them.

All of the namespaces exist on all of the providers. If a forge lacks an operation, the method is still there and rejects when you call it, which means TypeScript doesn't force you to cast at every call site. To find out whether an operation will work, use [`can()`](https://forgeslink-3mwmle35v-poetry.vercel.app/guides/capabilities) at run time.

## Escape hatch

The model doesn't cover every endpoint of every forge. When you need one that it doesn't, `provider.request()` lets you call it directly. It sends a request to an endpoint relative to `baseUrl`, or to an absolute HTTP(S) URL, and applies the provider's authentication, user agent, timeout and error mapping, just as it does for its own calls.

If you send a request to a different origin, the provider leaves out its credentials and default headers, so a token for one host is never sent to another.

## Subpath exports

Each provider has a subpath of its own, such as `forges/gitlab`, and the root entry re-exports all of them. The package declares `sideEffects: false`, so a bundler drops the providers you don't use from either entry. A server build that copies dependencies instead of bundling them copies every provider for the root entry and only one for a subpath. See [Server builds](https://forgeslink-3mwmle35v-poetry.vercel.app/guides/bundling#server-builds).

## Writing your own

If you need a forge that `forges` doesn't support, a provider is a single call to `defineForgeProvider()`. See [Write a provider](https://forgeslink-3mwmle35v-poetry.vercel.app/contributing/write-a-provider) to learn how.


## Sitemap

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