Deploy and update Githome

Githome runs on Cloudflare, with copies kept off Cloudflare, and the operator deploys it from its private repository. Nobody else deploys a copy: this page describes how the instance at git.pkgforge.dev is deployed, so that you can reason about what a deploy creates, changes and never touches. The commands run from a checkout of the repository; the repository is private and has no public clone URL.

There are two entry points, and both run the same script:

For what each Cloudflare product does in Githome, see Architecture. For every setting, see Configuration.

#What you need

Nobody who uses the instance needs a Cloudflare account. Only the deployment uses one.

#The resources

One file of the repository, deploy/resources.jsonc, lists the Cloudflare resources of each Worker, and wrangler.jsonc of each Worker holds the bindings; a test keeps the two in agreement. Each resource name starts with githome-, except the core Worker and its D1 database, which are named githome.

The deploy keeps a fixed list of secrets for each Worker. It generates MASTER_KEY and OIDC_PRIVATE_KEY the first time and never rotates them. The others come from the operator and are never generated: the mail, mirror and backup credentials, the Turnstile secret and, for the dash, the token that registers the first passkey. See Worker secrets.

#The Cloudflare door

The deploy reaches Cloudflare through one door, scripts/cf-token.ts with scripts/lib/cf-auth.ts. The operator keeps a minter credential in a file outside git. For each run the door mints a child token that holds only the permission groups of the run's purpose (the read-only wrangler-read for plan), hands it to wrangler from node_modules as CLOUDFLARE_API_TOKEN in that process only, and revokes it when the process ends, also on Ctrl-C. A token value is never printed, logged, put in an argument or written to a file, and the door refuses a command that deletes a resource. The account id comes from the door, never from the tree.

node scripts/cf-token.ts verify checks that the minter is active, and node scripts/cf-token.ts check mints a child token, makes two reads with it and revokes it.

#How a deployment works

1. render is local and makes no network call. For each Worker of the manifest it writes wrangler.deploy.jsonc in the Worker's folder (a generated file that git ignores; don't edit it) from wrangler.jsonc: no env section, a Custom Domain for each host, the D1 names of the manifest, no container, and the variable GITHOME_CI=off, so the forge CI stays dormant. Each Durable Object binding and migration stays.
2. plan is read only. It lists each resource of the manifest as present, missing or different: the Worker, each D1 database, R2 bucket, queue and Workflow, each Custom Domain, the crons and each secret that apply generates. It exits 3 on a missing or a different resource.
3. apply creates each missing D1 database, R2 bucket and queue, renders the config with the real D1 ids, applies the D1 migrations, deploys with wrangler, sets each missing generated secret from a value made in the process (never printed), and plans again. It stops on a resource that it cannot read or that differs, and it sets no secret when a read after the deploy fails, so a live key is never replaced. It never deletes or replaces a resource. MASTER_KEY is read from the operator's own copy when that copy exists; otherwise it is generated and written there before it is set, so a copy exists for a rebuild.

--worker NAME limits a command to one Worker. --target NAME makes a deployment of its own beside the live one, for a rebuild or a drill: each resource takes a name under githome-NAME-, the Worker has no Custom Domain and serves its workers.dev host, and it runs only the jobs of a rebuild.

Exit codes: 0 done, 1 a Cloudflare call or a step failed, 2 it could not run (bad arguments, no manifest, the door refused), 3 a resource is missing or differs.

#Deploy from your own machine

scripts/setup.sh runs from a checkout of the repository, for the first deploy and for each update. It checks node, pnpm and git, refuses a Node other than the one in .node-version or a pnpm other than the one in packageManager, runs pnpm install --frozen-lockfile, and starts the deploy script. It takes the Cloudflare token from the door, never from an argument or a prompt.

scripts/setup.sh                # plan: what the account lacks (read only)
scripts/setup.sh --dry-run      # build and dry-run each Worker: no Cloudflare call
scripts/setup.sh --apply        # deploy
scripts/setup.sh --target NAME  # with the plan or --apply: a deployment of its own

pnpm setup:cloudflare runs the same script. Every step creates only what is missing, so run it again with --apply to update; with no flag it plans and changes nothing.

#The first sign-in

Githome has no passwords, no Cloudflare Access sign-in and no open sign-up. The dash registers its first passkey with a bootstrap token that the operator sets as the Worker secret DASH_BOOTSTRAP_TOKEN (at least 32 characters). The dash records the one use of the token and refuses it afterwards. From then on the superadmin signs in on https://dash.git.pkgforge.dev with that passkey, invites each account and sends the one-time invitation link by hand. Githome sends no email for an invitation. A person who lost their passkeys asks the superadmin for a sign-in link.

#DNS

Each host is a Custom Domain of its Worker, which Cloudflare creates with the DNS record and the certificate. A new host can take a while to get its certificate. When wrangler is run without a terminal, it replaces an existing DNS record of a host that becomes a Custom Domain.

#Updating

Update by running scripts/setup.sh --apply (or node scripts/deploy.ts apply) again from the updated checkout. Each run:

• Creates nothing that already exists and keeps the D1 data, the R2 data and the secrets.
• Applies new D1 migrations before the new Worker goes live. Versions only move forward: D1 migrations can't be undone, so don't deploy an older version over a newer one.

Keep MASTER_KEY safe and don't simply replace it: it decrypts every stored secret, and links already sent are signed with it. To change it, keep the old key as MASTER_KEY_PREV as described in Rotating MASTER_KEY. If OIDC_PRIVATE_KEY is deleted, the next deploy generates a new key with a new key ID; systems that trust the OIDC tokens fetch the new public key from /.well-known/jwks.

#Mirrors and backups

Push mirrors copy each repository, with its forge state in refs/githome/meta, to GitHub, Cloudflare Artifacts, GitLab, Forgejo or Codeberg. Backups start once their bucket and credentials are set (they are not set yet, so no backup runs); then they run each day, are sealed with their own key (BACKUP_KEY, used for nothing else) and go to an S3-compatible bucket off Cloudflare. A deployment made with --target is the place where a rebuild or a drill runs, beside the live one.

#Local development

You can run the core on your machine with wrangler dev, which simulates D1, R2, Queues, Durable Objects and Workflows locally.

pnpm install
pnpm -r build
pnpm --filter @githome/app db:migrate:local
pnpm dev

pnpm dev runs wrangler dev -e dev in apps/githome and serves http://localhost:8787. The dev environment differs from the deployment:

To store secrets locally, put a key in apps/githome/.dev.vars (ignored by git): MASTER_KEY=<base64 of 32 random bytes>. The dash has its own dev environment (wrangler dev -e dev --port 8788).

#Troubleshooting