Configuration

Githome's core is configured in three places: Worker variables in apps/githome/wrangler.jsonc, Worker secrets that the operator sets through the Cloudflare door, and the Cloudflare bindings in the same wrangler.jsonc. This page lists the settings the core reads, their defaults and what they change, and says which values are fixed on git.pkgforge.dev. To see how the deploy uses them, read Deploy and update Githome.

#Where configuration lives

The settings of the other Workers are separate: the dash has its own wrangler.jsonc in apps/dash, and each module its own.

#Worker variables

Set under vars in wrangler.jsonc. All values are strings. The last column says what the deployment of git.pkgforge.dev has.

wrangler.jsonc also carries BOOTSTRAP_ADMINS, ACCESS_TEAM_DOMAIN and ACCESS_AUD, all empty. BOOTSTRAP_ADMINS is empty on git.pkgforge.dev, so no account becomes an administrator at its first sign-in, and the instance has no Cloudflare Access sign-in: the superadmin works in the dash (https://dash.git.pkgforge.dev), with its own passkey sign-in, and there is no "Make admin" action in the core. With ACCESS_TEAM_DOMAIN or ACCESS_AUD empty, /auth/access answers "Account recovery by email is not set up on this instance. Ask an administrator for a sign-in link." A person who lost their passkeys asks the superadmin for a sign-in link.

#PUBLIC_URL

PUBLIC_URL must be the exact origin people and tools use, with https:// and no path. Githome uses it for:

• Passkeys. The WebAuthn relying party ID is the hostname of PUBLIC_URL, and the expected origin is its origin. Passkeys only work on that hostname.
• Every generated link: emails, invitation and sign-in links, html_url and clone_url in API responses, webhook payloads, the sitemap and canonical tags.
• Workflows: github.server_url is PUBLIC_URL and github.api_url is PUBLIC_URL/api/v3.
• OIDC: the issuer (iss) of workflow ID tokens, and their default audience.
• The container registry host name, the hostname of PUBLIC_URL (images are <hostname>/<owner>/<name>).
• The cross-site check: a cookie-authenticated write with an Origin other than this origin is refused.

Important: Changing PUBLIC_URL on a running instance breaks every existing passkey (they are bound to the old hostname), changes the OIDC issuer that cloud providers trust, and changes every image name.

#SIGNUP

With SIGNUP=open, the sign-in page links to Create an account (/signup). Someone enters their email address, gets a 6-digit code by email, enters it, picks a username and creates a passkey; their account is active at once. Unset, or any other value, the instance is invite-only: /signup answers 404 (or, where Turnstile is set, leads to /early-access) and the sign-in page says so. The code exists in Githome, and the deployment of git.pkgforge.dev keeps it off: accounts are invited by the superadmin, who sends the one-time invitation link by hand.

Open sign-up needs Cloudflare Turnstile, so scripts can't use it to send email. Without both Turnstile keys, /signup answers 503 with "Sign-up needs Turnstile configured", except when PUBLIC_URL is on the local machine. The limits on codes are in Limits.

#EGRESS

EGRESS=web limits hosted job and sandbox containers to ports 80 and 443 and DNS, and forwards HTTP and HTTPS through the Worker. It applies only where hosted compute runs. On git.pkgforge.dev the forge CI is off and no Container starts, so the setting does nothing there, and it is not set.

#Security contact

/.well-known/security.txt (RFC 9116) tells security researchers where to report a problem. Githome always serves it, with:

The report form needs no setup: reports go to the superadmin, who reads them in the dash. People who are signed in can always send one. People who aren't pass Cloudflare Turnstile first, with TURNSTILE_SITE_KEY and TURNSTILE_SECRET. Without both keys, the form asks visitors to sign in, except on the local machine. SECURITY_CONTACT is optional; use an address someone reads.

#Turnstile

The security report and contact forms, and open sign-up when it's on, check with Cloudflare Turnstile that a visitor without an account is a person. The site key is the variable TURNSTILE_SITE_KEY, and the secret key is the Worker secret TURNSTILE_SECRET. The deploy does not create the widget: the operator makes it and gives the deploy the site key and the secret, and the secret is one that the deploy never generates. On git.pkgforge.dev neither is set yet, so people who aren't signed in can't send security reports or contact messages; a visitor without an account uses the public tracker.

#SMTP

Without an EMAIL binding, the core can send email through any SMTP server that speaks TLS. When the EMAIL binding is there, it is used and SMTP_URL is ignored.

1. Set SMTP_URL under vars in wrangler.jsonc.
   • smtps://<user>@<host>:465 uses TLS from the start. The port defaults to 465.
   • smtp://<user>@<host>:587 starts plain and upgrades with STARTTLS. If the server doesn't offer STARTTLS, the core sends nothing (E_SMTP_REJECTED), so the password never crosses the network in the clear.
   • Write an @ in the user as %40. Leave the user out for a relay that needs no sign-in.
   • Cloudflare Workers can't open connections to port 25, so use 465 or 587.
2. Store the password as the secret SMTP_PASSWORD. Never put it in SMTP_URL: the core refuses such a URL.
3. Make sure MAIL_FROM is an address the SMTP user may send from. It is both the From header and the envelope sender.

The core signs in with AUTH PLAIN, or AUTH LOGIN when the server offers only that. Each email is one connection, and each reply has 30 seconds to arrive. A 2xx answer is sent; a 4xx, a timeout or a dropped connection is E_SMTP_TRANSIENT and the queue tries again later, up to 6 times; a 5xx to RCPT TO that says the address doesn't exist is failed with E_SMTP_RECIPIENT_REJECTED and the address goes on the suppression list; any other 5xx is failed with E_SMTP_REJECTED. The core never logs the password or the content of an email.

Notification email depends on the email sending of the deployment: the core has the EMAIL binding, and delivery is not promised. No invitation is ever sent by email.

#DEV_AUTH

When DEV_AUTH is set, ACCESS_AUD is empty and both PUBLIC_URL and the request's own address are on the local machine (localhost, 127.x.x.x or [::1]), every request without credentials acts as the account with the email in DEV_AUTH, with full access.

Important: Never set DEV_AUTH on a deployed instance. As a safeguard it does nothing there: a request that reaches the Worker under any other host name, or a PUBLIC_URL that isn't on the local machine, turns it off.

#Worker secrets

Set with wrangler secret put through the Cloudflare door (the deploy sets the generated ones for you), never in wrangler.jsonc. A secret value is never printed or put in an argument.

None of these secrets is rotated automatically, and the deploy never replaces one that exists. Keep a copy of MASTER_KEY somewhere safe: replacing it without keeping the old one as MASTER_KEY_PREV makes every stored secret undecryptable. To rotate the OIDC key, delete OIDC_PRIVATE_KEY and deploy: a new key with a new kid is generated, and relying parties pick it up from /.well-known/jwks.

#Rotating MASTER_KEY

Rotate MASTER_KEY when it may have leaked, or on your own schedule. Githome accepts two keys while a rotation is under way: MASTER_KEY, which encrypts and signs everything new, and MASTER_KEY_PREV, the key it replaced, which is only used to decrypt and verify what was made before.

1. Make a new key and keep it with your copy of the current one: NEW_KEY="$(openssl rand -base64 32)".

2. Set the current key as MASTER_KEY_PREV and the new one as MASTER_KEY in one step, so no version of the Worker runs with the new key alone. OLD_KEY is the current value from your safe copy (Cloudflare doesn't show a secret's value):

   jq -n --arg old "$OLD_KEY" --arg new "$NEW_KEY" '{MASTER_KEY_PREV: $old, MASTER_KEY: $new}' | wrangler secret bulk -c wrangler.deploy.jsonc

   Run wrangler through the Cloudflare door. With wrangler secret put instead, put MASTER_KEY_PREV first and MASTER_KEY second.

3. Save the new key where you kept the old one. Nothing else needs to change: no deploy, migration or restart.

From then on, new and replaced secrets are encrypted with the new key, each stored value names the key it was encrypted with, and stored values move to the new key by themselves as they are used. Unsubscribe links, invitation links, codes, runtime tokens and cache and artifact URLs signed with the old key keep working; new ones are signed with the new key.

Remove MASTER_KEY_PREV only when nothing you still need depends on the old key: every secret you still need has been used or saved again since the rotation, and links already sent have expired or may stop working. If the old key leaked, treat the secrets as exposed: replace their values at the source and save the new values, then remove MASTER_KEY_PREV right away.

#Bindings

Defined in wrangler.jsonc. node scripts/deploy.ts apply creates the underlying resources that are missing.

The code also declares the container classes (RunnerContainer and its smaller sizes, SandboxContainer and ImportContainer) with their Durable Object bindings, because the Actions code stays in githome. The deployed config that render writes has "containers": [], so no Container is built or started on git.pkgforge.dev. The Durable Object classes are declared in eight migrations, tags v1 to v8, which wrangler deploy applies when the account doesn't have them yet.

#Other Worker settings

#The dev environment

wrangler.jsonc has an env.dev section that pnpm dev (wrangler dev -e dev) and the tests use. It is removed from the deployed config.

MASTER_KEY is not set in dev. Add it to apps/githome/.dev.vars (MASTER_KEY=<base64 of 32 random bytes>) to store secrets locally.

#GitHub imports

Imports from GitHub need no setup beyond a normal deploy: the IMPORT_WORKFLOW Workflow and the D1 tables of the imports are created by the deploy, and imports from GitLab, Forgejo, Gitea and Codeberg run without a container. An import from GitHub needs the import container (the IMPORTER binding), which the dormant CI keeps off, so on git.pkgforge.dev it stops at its Git step with "no import container is configured". What you can tune:

To offer linking through GitHub sign-in, create an OAuth app on github.com with the authorization callback URL https://git.pkgforge.dev/settings/linked/github/callback, put the client ID under vars and store the secret as GITHUB_OAUTH_CLIENT_SECRET. The OAuth flow asks GitHub for the read:user scope only and binds its state to the signed-in account. Without the two settings, people link accounts with the gist code, which needs no configuration.

Imports reach GitHub only on HTTPS hosts with public names; a GitHub API URL on a private address, localhost, .local or .internal is refused with 422 github_api_url must be a public host.

#Deploy script flags

The deploy is node scripts/deploy.ts render | plan | apply (see Deploy and update Githome). It reads no environment variable for the hostname, the zone or the administrators: the hosts are in deploy/resources.jsonc, and the account id and the token come from the Cloudflare door.

scripts/setup.sh takes --dry-run, --apply and --target NAME; with no flag it plans.

#Settings that are not configuration

Some values are fixed in code and can't be changed without editing it, for example the job timeout ceiling, matrix size, the 10 GB cache budget per repository and session lifetime. They are listed in Limits.