--- title: "Configure from the environment" description: "Create providers from FORGES_* environment variables." canonical_url: "https://forges.link/guides/environment" --- # Configure from the environment > Create providers from FORGES_* environment variables. If you are writing a CLI or a server that should work with whichever forges a user has credentials for, it would be tedious to write configuration code for each one. `forges/env` solves this by creating providers from environment variables. Every variable follows the form `FORGES__`, such as `FORGES_GITHUB_TOKEN` or `FORGES_GITLAB_BASE_URL`, and the forges that have variables set are the ones you get. ## Pick the variables for a task Which variables you need depends on what you want to do. Choose a forge and a task in the picker below, and it shows you the variables to set, the scopes or permissions the credential needs and how to create such a credential. The table lists the capabilities that each task covers:
Task Capabilities
Read: Repositories and people repos.get , repos.list , repos.byOwner , repos.labels , repos.milestones , repos.collaborators , repos.contributors , repos.contributorStats , repos.templates , repos.permissionFor , repos.assignableUsers , repos.reviewerCandidates , users.get , users.me , users.sponsorable
Read: Organisation teams orgs.teams , orgs.teamMembers
Read: Issues and PRs threads.get , threads.list , threads.getMany , threads.events , comments.list , comments.get , reactions.list , reviews.list , reviews.get , contents.threadFiles , contents.threadCommits
Read: Code and history contents.file , contents.tree , contents.branches , contents.tags , contents.resolveRef , contents.commits , contents.commit , contents.compare
Read: Releases releases.list , releases.get , releases.latest , releases.getByTag , releases.downloadAsset
Read: Checks and CI checks.thread , checks.list , checks.get , ci.runs , ci.run , ci.jobs , ci.job , ci.log
Read: Search search.threads , search.repos , search.commits , search.code
Read: Security alerts securityAlerts
Read: Notifications notifications.list , notifications.unreadCount , subscriptions.get
Write: Comment and react writes.comment , writes.upsertComment , comments.edit , comments.delete , writes.react
Write: Open, edit and close writes.create , writes.update , writes.close , writes.reopen , writes.transfer , writes.markDuplicate
Write: Labels, assignees and milestones writes.setLabels , writes.addLabels , writes.removeLabels , writes.setMilestone , writes.setAssignees , repos.createLabel
Write: Review PRs writes.requestReview , reviews.create , reviews.submit , reviews.approve , reviews.reply , reviews.resolveThread
Write: Merge PRs writes.merge , writes.approveAndMerge
Write: Report checks checks.report , checks.rerun
Write: Commit files contents.commitFiles
Write: Publish releases releases.create , releases.update
Write: Triage notifications notifications.markRead , notifications.markDone , notifications.unsubscribe , notifications.markAllRead , notifications.markAllDone , subscriptions.set
Events: Receive webhooks sources.webhook
Events: Poll or stream events sources.poll , sources.subscribe , repos.events , users.events
Administer: Manage webhooks webhooks.list , webhooks.create , webhooks.update , webhooks.delete , webhooks.rotateSecret , webhooks.deliveries , webhooks.redeliver
Administer: Add collaborators repos.addCollaborator
Administer: App installations installations
If you need the same information in your code, [`provider.scopesFor(verb)`](https://forges.link/guides/authentication#show-the-scopes-an-operation-needs) returns the scopes for a single verb. ## Create the providers To turn the variables into providers, pass them to `forgesFromEnv()`. It reads every set of variables, builds a provider for each forge that is configured and hands them all to `createForges()`: ```ts import { forgesFromEnv } from 'forges/env' const forges = forgesFromEnv(process.env) ``` ## Report skipped forges `forgesFromEnv()` silently leaves out any set of variables that can't configure a provider, for example because the token is missing. If you would rather tell the user, use `providersFromEnv()` instead. It returns one entry for each set of variables. An entry has a `factory` when the variables are enough to configure a provider, and a `skipped` reason when they aren't. The reason never contains a credential, so it is safe to log: ```ts 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.forge}: ${entry.skipped}`) } } const forges = createForges( entries.flatMap(entry => entry.factory ? [entry.factory] : []), ) ``` ## Variables In the variable names, `` is the name of the forge in upper case, with an underscore in place of a hyphen. That gives `GITHUB`, `GITLAB`, `BITBUCKET`, `FORGEJO`, `GITEA`, `GITEE`, `AZURE_DEVOPS`, `CURSOR_ORIGIN`, `TANGLED`, `PUSHIN` and `CLOUDFLARE_ARTIFACTS`. The following fields work for every forge. Most of them set the provider option of the same name, and the table describes what each one does:
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
A few forges need more than that, so they read additional 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
To learn what these options do on a particular forge, see its [provider page](https://forges.link/providers). ## Configure a second instance You might have credentials for two instances of one forge, such as github.com and a company's GitHub Enterprise Server. To configure the second one, add a suffix after the field name. This starts a new set of variables for the same forge. Every variable in a set carries the same suffix, and you can read it from `entry.suffix`: ```sh FORGES_GITHUB_TOKEN=ghp_... FORGES_GITHUB_TOKEN_WORK=ghp_... FORGES_GITHUB_BASE_URL_WORK=https://ghe.example.com/api/v3 ``` As with any other registration, `createForges()` throws when two providers share a forge and an instance. If two sets of variables point at the same host, give one of them a different `INSTANCE`. ## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.