scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-11-13 08:51:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

docs(github): document GitHub Enterprise Server and Enterprise Cloud setup

Browse source
This commit is contained in:
Dávid Balatoni 2026-10-25 01:25:28 +02:00
parent eb1d137124
commit 505e72119e
No known key found for this signature in database
2 changed files with 73 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
docs/public/administration/server-configuration.mdx
View file

@ -303,8 +303,8 @@ When a field is not set, Fabro derives it from the run's GitHub credential:
| Credential | Name | Email |
|---|---|---|
| GitHub App (`strategy = "app"`) | `<slug>[bot]` | `<id>+<slug>[bot]@users.noreply.github.com` |
| Token (`strategy = "token"`) | the token's user login | `<id>+<login>@users.noreply.github.com` |
| GitHub App (`strategy = "app"`) | `<slug>[bot]` | `<id>+<slug>[bot]@users.noreply.github.com` (`users.noreply.<host>` on an enterprise host) |
| Token (`strategy = "token"`) | the token's user login | `<id>+<login>@users.noreply.github.com` (`users.noreply.<host>` on an enterprise host) |
| None | `Fabro` | `noreply@fabro.sh` |
Setting both `name` and `email` skips the credential lookup. Setting one field overlays it on the derived identity. A lookup failure for the selected credential fails the run at setup; Fabro never silently switches to another author. The resolved identity is recorded in the run's event stream as `git.identity.resolved` and in the run state as `git_identity`.
@ -323,6 +323,15 @@ Configure GitHub integration auth. `strategy = "token"` is the default and uses
strategy = "token"
```
| Key | Description | Default |
|---|---|---|
| `strategy` | `token` or `app` | `token` |
| `app_id`, `client_id`, `slug` | GitHub App identity (App mode) | none |
| `web_url` | Web origin of the GitHub deployment, such as `https://ghe.example.com`. Override with `GITHUB_WEB_URL` | `https://github.com` |
| `api_url` | REST API base URL. Override with `GITHUB_BASE_URL` | derived from `web_url` (`https://api.github.com`, `https://api.<host>` for `*.ghe.com`, `<web_url>/api/v3` otherwise) |
For GitHub Enterprise Server or GitHub Enterprise Cloud, set `web_url` (see [GitHub Enterprise Server and GitHub Enterprise Cloud](/integrations/github#github-enterprise-server-and-github-enterprise-cloud)). The CLI and the run worker read the host from the local `settings.toml` or `GITHUB_WEB_URL`.
For GitHub App mode, set `strategy = "app"` and include `app_id`, `client_id`, and `slug`. Webhook delivery is configured under `[server.integrations.github.webhooks]`:
```toml title="settings.toml"

62
docs/public/integrations/github.mdx
View file

@ -121,6 +121,7 @@ slug = "fabro-a3f2"
| `app_id` | Numeric GitHub App ID |
| `client_id` | OAuth Client ID for the app |
| `slug` | App slug, used for linking to the GitHub App settings page |
| `web_url`, `api_url` | Optional. Target GitHub Enterprise Server or Enterprise Cloud instead of github.com; see [GitHub Enterprise Server and GitHub Enterprise Cloud](#github-enterprise-server-and-github-enterprise-cloud) |
### Server vault
@ -174,6 +175,67 @@ fabro install github
This walks through just the GitHub setup steps — choosing a strategy, registering an app, or storing a token — and restarts the server when done. Stale settings and secrets from the previous strategy are cleaned up automatically.
## GitHub Enterprise Server and GitHub Enterprise Cloud
Fabro talks to github.com by default. To use a GitHub Enterprise Server (GHES) instance, or a GitHub Enterprise Cloud tenant with data residency (`https://<subdomain>.ghe.com`), set the web origin of that deployment. Fabro derives every other URL from it.
```toml title="settings.toml"
[server.integrations.github]
web_url = "https://ghe.example.com"
# api_url = "https://ghe.example.com/api/v3" # optional override
```
| Setting | Environment override | Description |
|---|---|---|
| `server.integrations.github.web_url` | `GITHUB_WEB_URL` | Web origin of the GitHub deployment, for example `https://ghe.example.com`. Defaults to `https://github.com`. Must be `https` and must not contain a path, query or fragment (plain `http` is accepted only for loopback hosts such as `localhost` and `127.0.0.1`). |
| `server.integrations.github.api_url` | `GITHUB_BASE_URL` | REST API base URL. Optional: when unset it is derived from `web_url` as shown below. |
The environment variables win over `settings.toml`. `GITHUB_WEB_URL` alone re-derives the API URL from the new web origin; `GITHUB_BASE_URL` alone replaces only the API URL.
### Derived URLs
| | github.com | GitHub Enterprise Cloud (`https://octocorp.ghe.com`) | GitHub Enterprise Server (`https://ghe.example.com`) |
|---|---|---|---|
| REST API | `https://api.github.com` | `https://api.octocorp.ghe.com` | `https://ghe.example.com/api/v3` |
| GraphQL | `https://api.github.com/graphql` | `https://api.octocorp.ghe.com/graphql` | `https://ghe.example.com/api/graphql` |
| OAuth | `https://github.com/login/oauth/...` | `https://octocorp.ghe.com/login/oauth/...` | `https://ghe.example.com/login/oauth/...` |
| Repository clone URL | `https://github.com/owner/repo` | `https://octocorp.ghe.com/owner/repo` | `https://ghe.example.com/owner/repo` |
| Pull request link | `https://github.com/owner/repo/pull/7` | `https://octocorp.ghe.com/owner/repo/pull/7` | `https://ghe.example.com/owner/repo/pull/7` |
| Commit email domain | `users.noreply.github.com` | `users.noreply.octocorp.ghe.com` | `users.noreply.ghe.example.com` |
A host named `github.com` or `*.github.com` is treated as github.com, `ghe.com` or `*.ghe.com` as GitHub Enterprise Cloud, and any other host as GitHub Enterprise Server.
### Where the host is read
The server, the run worker and the CLI all need to agree on the host:
- The **server** reads `web_url` and `api_url` from its `settings.toml` and the environment overrides above. The server passes `GITHUB_WEB_URL` and `GITHUB_BASE_URL` on to run workers it starts.
- The **run worker** reads the same `settings.toml` (through `FABRO_HOME`) and the same environment variables.
- The **CLI** reads the host from the local `settings.toml` or from `GITHUB_WEB_URL`; it does not ask a remote server. If you run `fabro` against a remote server, set the same `web_url` in your local `settings.toml` (or export `GITHUB_WEB_URL`) so repository URLs, `fabro install` and `fabro doctor` target the enterprise host.
Set `web_url` before running `fabro install`. The installer uses it for `gh auth token --hostname <host>`, for the GitHub App manifest registration and for the links it prints.
### Authentication
- **Tokens.** Personal access tokens, fine-grained tokens and OAuth tokens use the same `ghp_`, `github_pat_`, `gho_`, `ghu_` and `ghs_` formats on GHES and GHEC. `fabro install` runs `gh auth token --hostname <host>`, so run `gh auth login --hostname ghe.example.com` first.
- **GitHub App.** `fabro install` registers the App through the manifest flow against `<web_url>/settings/apps/new` (or the organization equivalent) and exchanges the code on the host's API. This needs a GHES version that supports GitHub App manifests. If your instance does not, register the App by hand and set `app_id`, `client_id` and `slug` under `[server.integrations.github]`, then store the private key and client secret as described in [Server vault](#server-vault).
- **Browser sign-in.** OAuth login redirects to `<web_url>/login/oauth/authorize`, and sessions record the enterprise host as the identity issuer.
### Custom certificate authorities
Enterprise hosts often use a certificate from a private CA. Fabro always verifies TLS certificates and has no setting to disable verification. Install the CA certificate in the system trust store of the server host, the run worker host and the sandbox image, or point the processes at a CA bundle with `SSL_CERT_FILE` (or `SSL_CERT_DIR`). Git and the `gh` CLI inside sandboxes honor the same variables, so set them in the sandbox environment as well.
### The `gh` CLI in sandboxes
The `gh` CLI reads `GITHUB_TOKEN` only for github.com. For any other host Fabro also injects `GH_HOST=<host>` and `GH_ENTERPRISE_TOKEN=<token>` next to `GITHUB_TOKEN`, so `gh pr list` and similar commands in command stages work without `gh auth login`. Git's credential helper and the `git@<host>:` and `ssh://git@<host>/` rewrites are scoped to the configured host.
### Known limitations
- One GitHub host per server. Repositories on any other host (including github.com when `web_url` points at an enterprise host) are rejected.
- Features that an older GHES release does not provide, such as newer App permissions or auto-merge, surface as the error GitHub returns.
- Avatars and the Content Security Policy follow the configured host: for a non-github.com host, `img-src` allows the web origin and `https://avatars.<host>` instead of `avatars.githubusercontent.com`. A GHES instance that serves avatars from another origin shows broken avatar images.
- The Fabro CLI release channel and documentation links stay on github.com.
## `token` mode
Choose **GitHub CLI** in `fabro install` to use the default local-user flow. The installer: