Forge supports the open-source contribution model: people without write access fork a repository, push to their fork, and open a pull request against the original. Maintainers review, run checks, and merge. Contributors can sign in with GitHub. OpenID Connect single sign-on and Git over SSH are built in but off by default (see below).
POST /api/repos/:owner/:repo/forks).GET /api/repos/:owner/:repo/forks returns viewer_can_push).API: POST /api/repos/:owner/:repo/pulls with
{ "title", "source_branch", "target_branch", "head_repo": "you/repo" }.
GET /api/repos/:owner/:repo/pulls/compare?base=main&head=feature&head_repo=you/repo
shows the diff before you open the request.
Forge works the way GitHub does. When the pull request is opened, Forge
copies the fork head's new objects into the original repository and records
them under the read-only ref refs/pull/<number>/head. Each push to the fork
branch refreshes that ref. You can fetch the ref like any other:
git fetch origin pull/7/head. Pushes to refs/pull/* are rejected. Diffs,
merge status, and fast-forward merges read the original repository only.
Pull request responses include from_fork and
head_repo: { id, full_name }. If the fork is deleted, head_repo becomes
null and the last imported head stays reviewable.
| Action | Who |
|---|---|
| Open a fork pull request | Anyone who can read the original and push to the fork |
| Close, reopen, or toggle draft | The author, or anyone with write access to the original |
| Merge | Write access to the original only |
| Approve a waiting fork check run | Write access to the original |
The original repository's on: pull_request workflows run against the fork
head with trigger ref refs/pull/<n>/head. These runs are recorded with
from_fork = 1, and the flag is sent to the runner dispatch (fromFork).
Re-runs keep the flag. Fork runs never produce the signed evidence that
unlocks preview deployments, and the runner must not give them repository
secrets.
A contributor's runs start as waiting until they have had a pull request
merged or have write access to the original. A maintainer starts them with
POST /api/repos/:owner/:repo/actions/runs/:run_id/approve. The exact-SHA
merge gate accepts a passing fork run for the exact head.
GitHub sign-in is on for forge.smol.ai. Providers sign in existing Forge
accounts only (disableSignUp); people still join through the invite flow.
A GitHub identity links automatically on sign-in when its verified primary
email matches a Forge account; otherwise connect it from Settings →
Sign-in security after signing in.
Setup for the identity Worker (packages/identity):
https://forge.smol.aihttps://forge.smol.ai/api/auth/better/callback/githubread:user and user:email
scopes so private primary emails can be matched.packages/identity/wrangler.toml and config/forge-releases/identity.json,
so a release fails until they exist):GITHUB_CLIENT_ID: the OAuth app's client IDGITHUB_CLIENT_SECRET: a client secret generated for the app/api/auth/login-options lists { "id": "github" }.The callback origin is PUBLIC_APP_ORIGIN; a staging Worker needs its own
OAuth app with that origin's callback URL.
| Provider | Configuration | Callback URL |
|---|---|---|
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET (secrets) |
https://<origin>/api/auth/better/callback/google |
|
| GitHub | GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET (secrets) |
https://<origin>/api/auth/better/callback/github |
| OpenID Connect (deferred) | OIDC_LOGIN_ENABLED="true", OIDC_DISCOVERY_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, optional OIDC_PROVIDER_NAME |
https://<origin>/api/auth/better/callback/oidc |
The OIDC code path is present but stays off unless OIDC_LOGIN_ENABLED is
exactly "true" and its three credentials are set; the credentials alone do
not enable it. When enabled it uses the authorization code flow with PKCE and
the scopes openid email profile, verifies ID tokens against the provider's
JWKS from discovery, and namespaces accounts by the issuer derived from the
discovery URL. The identity Worker fetches the discovery document whenever it
builds its auth handler, so use an IdP with a fast, highly available discovery
endpoint (Okta, Entra ID, Google Workspace, Keycloak, Authentik).
SAML is not supported: Better Auth's SAML support is a separate package
(@better-auth/sso) that Forge does not include. Most SAML identity providers
also offer OIDC.
SSH key management is off unless SSH_KEYS_ENABLED is "true" on the
identity Worker: until then /api/users/me/ssh-keys answers 404 and the
Settings panel is hidden, so nobody registers keys no gateway accepts. When
enabled, add public keys under Settings → SSH keys, or via
/api/users/me/ssh-keys. Git over SSH needs a gateway outside Workers; see
Git over SSH.