forges

one client, every forge

A unified interface for issues, pull requests, notifications, checks and webhooks across 16 forges.

get started
Unified example
try it
import { createForges, github, gitlab } from 'forges'

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

for await (const notification of forges.notifications.list()) {
  console.log(notification.ref.forge, notification.title)
}

features

You write your code against one model, and forges takes care of the endpoints, pagination, authentication and rate limits of each forge.
one data model
Issues, pull requests, comments, checks and events have the same shape on every forge, and the original payload is still there in the raw field when you need it.
declared capabilities
Every provider declares what its forge supports, and we check those claims against the tests on every commit to forges. Ask provider.can() before you call an operation.
verified webhooks
The provider verifies each delivery for you and turns it into typed events, with the same kinds and actions on every forge.
small bundles
Bundles keep only the forges you import, and the code that translates webhook deliveries loads only when you ingest one. The GitHub provider is about 42 kB gzipped.
offline tests
Test your code against an in-memory forge or replayed responses, without ever touching the network.
typed errors and retries
Rate limits, revoked tokens and missing scopes each have their own error class, and after a short rate limit the provider retries once by itself.

see what each forge can do

Every provider declares what its forge supports, so your code can check before it makes a call.
Support for selected capabilities, by forge
CapabilityGitHubGitLabBitbucketForgejoGiteaGiteeAzure DevOpsCursor OriginPushin.euTangledCloudflare ArtifactsSourcehutEntireGitBucketGitCafeUpstream
threads.mergeNativeNativeNativeNativeNativeNativeNativeExperimentalNot applicableNativeNot availableNot availableNativeNativeUnverifiedNative
notifications.listNativeNativeNot applicableNativeNativeNativeNot availableNot applicableNativeExperimentalNot availableNot availableNot availableNot availableNot applicableNative
checks.listNativeNativeNativeNativeNativeNativeNativeExperimentalNot availableNot applicableNot availableNot availableNot availableNativeNativeNative
ci.runsNativeNativeNot availableNativeNativeNot availableNot availableNot availableNot availableNot availableNot availableEmulatedNot availableNot applicableNativeNative
releases.listNativeNativeNot applicableNativeNativeNativeNot availableNot applicableNativeNot applicableNot availableEmulatedNot applicableNativeNot applicableNative
webhooks.createNativeNativeNativeNativeNativeUnverifiedNot availableNot availableNot applicableUnverifiedNot availableNot availableNot availableNativeUnverifiedNative
search.threadsNativeNativeNativeNativeNativeNativeNativeNot availableNot availableNativeNot availableNot availableNot availableNot availableNot availableNative
  • Native and verified
  • Experimental
  • Emulated
  • Unverified
  • Not applicable
  • Not available

what you can build

Explore the examples and guides to get started on your next project.
a notification inbox
Merge the notifications of every forge you configure into one list.
a label bot
Label new threads, and close them from a comment command, on any forge.
a release digest
Show the latest release and the failing pull requests across repositories.
a webhook receiver
Turn the deliveries of any forge into a single event type.

make your first call

Install the package, read an issue and add a second forge.