Quick start
This page walks through the main calls on GitHub, then adds Codeberg as a second forge. You need a GitHub personal access token in the GITHUB_TOKEN environment variable, and a Codeberg access token in CODEBERG_TOKEN for the last steps.
Create a provider
Import a provider function, pass the credentials and call create():
import { github } from 'forges/github'
const gh = github({
auth: { type: 'token', token: process.env.GITHUB_TOKEN! },
}).create()
Read a thread
Issues, pull requests and discussions are all threads. A ref names the repository and the thread:
const repo = {
forge: 'github',
instance: 'github.com',
owner: 'nuxt',
name: 'nuxt',
} as const
const thread = await gh.threads.get({
forge: 'github',
instance: 'github.com',
repo,
kind: 'issue',
number: '1',
})
console.log(thread.title, thread.state)
List threads
Listings are async iterables. They fetch the next page when the loop needs it:
for await (const issue of gh.threads.list(repo, {
kind: 'issue',
state: 'open',
})) {
console.log(issue.ref.number, issue.title)
}
Write a comment
Write operations take the same refs. This call posts a real comment, so point repo at a repository you own before you run it:
await gh.threads.comment(thread.ref, 'Thanks for the report.')
Add a second forge
createForges() takes a list of factories. It routes each call to the provider that matches the ref, and it lists notifications from every provider:
import { createForges, forgejo, github } from 'forges'
const forges = createForges([
github({ auth: { type: 'token', token: process.env.GITHUB_TOKEN! } }),
forgejo({
baseUrl: 'https://codeberg.org',
auth: { type: 'token', token: process.env.CODEBERG_TOKEN! },
}),
])
for await (const notification of forges.notifications.list()) {
console.log(notification.ref.forge, notification.title)
}
Check support before you write
Not every forge supports every operation. Ask first when your code runs on more than one forge:
if (gh.can('threads.addLabels', thread.ref.kind)) {
await gh.threads.addLabels(thread.ref, ['triage'])
}
Next steps
- Learn how capabilities work.
- Receive webhooks from your forges.
- Read the provider page for your forge.