Authenticate

Every provider takes an auth option. The accepted types differ by forge, so check the provider page for yours.

Use a token

Most forges accept a token:

import { gitlab } from 'forges/gitlab'

const forge = gitlab({
  auth: { type: 'token', token: process.env.GITLAB_TOKEN! },
}).create()

The other types are basic for a username and password, app for GitHub App and Cursor Origin App credentials and app_password and oauth on Tangled.

Read without credentials

Leave out auth for an anonymous provider. It sends no credentials and makes public reads only. Writes, notifications and subscriptions report false:

import { github } from 'forges/github'

const publicGitHub = github({}).create()

Limit a credential to reads

Set readOnly: true to use a credential for reads only. Every write reports false and rejects with ReadOnlyError. This includes provider.request() with a method other than GET, HEAD or OPTIONS:

import { gitlab } from 'forges/gitlab'

const audit = gitlab({
  auth: { type: 'token', token: process.env.GITLAB_TOKEN! },
  readOnly: true,
}).create()

Pass mutates: false to provider.request() for a request that only reads, such as a GraphQL query.

Show the scopes an operation needs

provider.scopesFor(verb) returns the token scopes or app permissions that an operation needs on that forge. Use it for a consent screen or an error message:

const needed = forge.scopesFor('threads.merge')

The result has optional token, permissions and note fields. A verb with no mapping returns an empty object.

Authenticate as a GitHub App

Pass the app ID, the private key and an installation:

const app = github({
  auth: {
    type: 'app',
    appId: 123456,
    privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
    installationId: 7890,
  },
}).create()

The provider mints and caches installation tokens as it needs them. The GitHub provider page explains how to work with several installations.