admin-guide/spaces-and-git-providers/index.md

id	title	description	tags	lang
spaces-and-git-providers	Spaces and Git providers	Configuring which repositories are wiki spaces, service tokens, webhooks, and how the index stays current.	admin spaces git	en

Spaces and Git providers

A space is one repository on Forgejo or GitHub, declared to f451 as one entry in F451_SPACES — a JSON array on the api service:

[
  {
    "id": "handbook",
    "name": "Handbook",
    "provider": "forgejo",
    "owner": "docs",
    "repo": "handbook",
    "defaultLang": "en"
  }
]

Without F451_SPACES set, the API starts in a minimal mode: only /healthz and /readyz respond, and no space is visible at all.

Service tokens are for indexing, not for user access

Each provider used by at least one space needs a service-account token:

Variable	Used for
F451_FORGEJO_URL	Base URL of the Forgejo instance (no /api/v1). Also the one source for the service-account registry, the write-permission check, and — if Forgejo doubles as identity provider — the OIDC issuer.
F451_FORGEJO_TOKEN	Service-account token Forgejo spaces are indexed with.
F451_GITHUB_TOKEN	Service-account token GitHub spaces are indexed with.

Note

These tokens exist purely so the indexer can read repository content to build the search index and page tree. They are never used to write on a user's behalf — every write is committed with the writer's own linked provider token (see sign-in-options). A misconfigured or missing service token breaks indexing for that provider's spaces, not writing.

Webhooks keep the index current

Configure a webhook in each space's repository pointing at f451, and set a matching secret on the api service so f451 can verify it:

Variable	Effect
F451_WEBHOOK_SECRET_FORGEJO	HMAC secret for Forgejo webhooks. Must match the secret entered when creating the webhook in the Forgejo repository.
F451_WEBHOOK_SECRET_GITHUB	Same, for GitHub webhooks.

Without the matching secret set, every webhook signature check fails (401) and pushes never trigger an incremental reindex — see operations for how that shows up and how it self-heals.

The drift job is the safety net

A background job compares each space's current main HEAD against the last fully indexed commit every 5 minutes, and triggers a full reindex on a mismatch. This means a webhook that never arrives — a firewall rule, a wrong secret, a Git provider outage — is not a lasting problem: the index catches up on its own within 5 minutes, no manual action required. See operations for how to observe this happening.

Templates across spaces

F451_GLOBAL_TEMPLATES optionally names one more repository ({"provider","owner","repo"}, same shape as an F451_SPACES entry) that supplies templates available to every space, in addition to a space's own _templates/*.md.