Configure from the environment
forges/env creates providers from environment variables, so a CLI or a server can pick up credentials for any forge without code for each one. Each variable has the form FORGES_<KIND>_<FIELD>, such as FORGES_GITHUB_TOKEN or FORGES_GITLAB_BASE_URL.
Create the providers
forgesFromEnv() reads the variables and passes every configured provider to createForges():
import { forgesFromEnv } from 'forges/env'
const forges = forgesFromEnv(process.env)
Report skipped forges
providersFromEnv() returns one entry for each set of variables. An entry has a factory when the variables configure a provider, and a skipped reason when they don't. The reason never contains a credential:
import { createForges } from 'forges'
import { providersFromEnv } from 'forges/env'
const entries = providersFromEnv(process.env)
for (const entry of entries) {
if (entry.skipped) {
console.warn(`Skipping ${entry.kind}: ${entry.skipped}`)
}
}
const forges = createForges(
entries.flatMap(entry => entry.factory ? [entry.factory] : []),
)
Variables
<KIND> is the forge in upper case, with underscores for hyphens: GITHUB, GITLAB, BITBUCKET, FORGEJO, GITEA, GITEE, AZURE_DEVOPS, CURSOR_ORIGIN, TANGLED or PUSHIN.
These fields set the shared provider options:
| Field | Effect |
|---|---|
TOKEN | Sets auth to a token |
BASE_URL | Sets baseUrl |
INSTANCE | Sets instance |
INSTANCE_VERSION | Sets instanceVersion |
WEBHOOK_SECRET | Sets webhookSecret |
READ_ONLY | Sets readOnly: true when the value is 1 or true |
ENABLED | 1 or true creates an anonymous provider without a token. 0 or false skips the forge |
DEMO_REPO | Sets entry.demoRepo to an owner/name repository for your code to use, and enables anonymous reads |
Some forges read more fields:
| Forge | Fields |
|---|---|
| GitHub, Cursor Origin | APP_ID, PRIVATE_KEY and INSTALLATION_ID for app auth. Write the newlines in PRIVATE_KEY as \n |
| Bitbucket, Azure DevOps | USERNAME and PASSWORD for Basic auth |
| Azure DevOps | ORGANIZATION, which is required |
| Tangled | IDENTIFIER, PASSWORD and an optional PDS for an app password. API_URL and NOTIFICATIONS_URL set the service URLs |
The provider page for each forge explains what these options do.
Configure a second instance
Add a suffix after the field to start another set of variables for the same forge. Every variable in a set has the same suffix, and entry.suffix holds it:
FORGES_GITHUB_TOKEN=ghp_...
FORGES_GITHUB_TOKEN_WORK=ghp_...
FORGES_GITHUB_BASE_URL_WORK=https://ghe.example.com/api/v3
createForges() throws when two providers share a forge and an instance. If two sets point at the same host, give one of them a different INSTANCE.