# External contributors

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).

## Pull requests from forks

1. Fork the repository (**Fork** on the repository page, or
   `POST /api/repos/:owner/:repo/forks`).
2. Push a branch to the fork.
3. Open **New pull request** on the original repository and choose the fork
   under **Source repository**. Only forks you can push to are listed
   (`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.

### How it works

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.

### Permissions

| 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 |

### Checks on fork pull requests

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.

## Sign in with GitHub

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`):

1. Create a GitHub OAuth app (GitHub → Settings → Developer settings → OAuth
   Apps) owned by the Forge organization:
   - Homepage URL: `https://forge.smol.ai`
   - Authorization callback URL: `https://forge.smol.ai/api/auth/better/callback/github`
   - Device flow: off. Better Auth requests the `read:user` and `user:email`
     scopes so private primary emails can be matched.
2. Set two secrets on the identity Worker (both are in its required secrets,
   `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 ID
   - `GITHUB_CLIENT_SECRET`: a client secret generated for the app
3. Release the identity Worker. The sign-in page and Settings then show a
   GitHub button; `/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 | `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` |

## OpenID Connect single sign-on (deferred, off by default)

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 keys (deferred, off by default)

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](../design/ssh-transport.md).
