codician/diffinerypublic

---

#title: Configuration description: Every setting of a self-hosted Diffinery: Worker variables and secrets, bindings, the dev environment, and the secrets and variables the deploy workflows use.

A Diffinery instance is configured in four places: Worker variables in apps/diffinery/wrangler.jsonc, Worker secrets set with wrangler secret put, the Cloudflare bindings in the same wrangler.jsonc, and the secrets and variables of the repository whose workflows deploy it. This page lists every setting, its default and what it changes. To deploy for the first time, follow Deploy your own Diffinery.

#Where configuration lives

#Worker variables

Set under vars in wrangler.jsonc. All values are strings.

When either ACCESS_TEAM_DOMAIN or ACCESS_AUD is empty, email sign-in at /auth/access is off: the page answers "Account recovery by email is not set up on this instance. Ask an administrator for a sign-in link.", and the sign-in page doesn't offer Recover your account by email. Passkeys, invitations and admin sign-in links keep working, but the first administrator can't sign in, because email sign-in is how an account in BOOTSTRAP_ADMINS is created.

#PUBLIC_URL

PUBLIC_URL must be the exact origin people and tools use, with https:// and no path. You don't set it by hand for a deploy: scripts/render-config.mjs sets it from --public-url, which bootstrap fills in as https://<DIFFINERY_DOMAIN>, and refuses a URL that isn't https:// or has a path (--public-url must be an https origin, like https://git.example.com). The same flag points the Worker's route at that hostname, so the route and PUBLIC_URL always agree. Diffinery 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, check run details links, the sitemap and canonical tags.
• Workflows: github.server_url is PUBLIC_URL, github.api_url is PUBLIC_URL/api/v3, and the runner agent and sandboxes call back to it.
• 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 (by deploying with another DIFFINERY_DOMAIN) breaks every existing passkey (they are bound to the old hostname), changes the OIDC issuer that cloud providers trust, and changes every image name. Choose the hostname before your first sign-in.

#BOOTSTRAP_ADMINS

A comma-separated list of email addresses; spaces around entries are ignored and matching is case-insensitive. Logins in the list are ignored, because anyone could pick a free login, while an email address has to be proven (by email sign-in or by opening the link in an invitation email).

An account becomes a site administrator from this list only when it is created (through email sign-in at /auth/access, by joining from an invitation or through open sign-up, or through DEV_AUTH locally), or when an account that is still waiting for an invite signs in through /auth/access. Accounts that already exist are not promoted or demoted when you change the list later, and there is no page for granting or removing site administration. See Site administration.

#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 (see Open sign-up). Unset, or any other value, the instance is invite-only as before: /signup answers 404 and the sign-in page says so.

Open sign-up needs a Cloudflare Turnstile widget, so scripts can't use it to send email:

1. In the Cloudflare dashboard, open Turnstile, add a widget for your hostname (the one in PUBLIC_URL) and copy its site key and secret key.
2. Add "SIGNUP": "open" and "TURNSTILE_SITE_KEY": "<site key>" under vars in wrangler.jsonc; the deploy keeps them.
3. Store the secret: printf '%s' "$TURNSTILE_SECRET" | pnpm exec wrangler secret put TURNSTILE_SECRET -c wrangler.deploy.jsonc.

Each code request is checked with Turnstile's siteverify API, with the visitor's IP address. Without both keys, /signup answers 503 with "Sign-up needs Turnstile configured", except when PUBLIC_URL is on the local machine (localhost, 127.x.x.x or [::1]): local development and the end-to-end tests skip the check. Only the sign-up page's content security policy allows scripts and frames from https://challenges.cloudflare.com.

The limits on codes (5 a day per address, 20 a day per IP address, 10 minutes and 5 tries each) are in Limits. Sign-up emails always send: they need the EMAIL binding and the MAIL queue like every other email.

#EGRESS

Experimental: web hasn't been tried on a live instance yet. The setting covers the whole instance, so try it on a test instance first, or check it with an account no site administrator runs, as in Check it below. diffinery.com doesn't set it.

With EGRESS=web, hosted job and sandbox containers start without direct internet access. Cloudflare then lets only ports 80 and 443, and DNS to Cloudflare's resolvers, leave the container, and Diffinery forwards HTTP and HTTPS requests to any host through the Worker. Unset, or any other value, hosted compute reaches the whole internet as before. The setting is read when a container starts: jobs and sandboxes already running keep the access they started with.

Under web:

• Works: git clone https://..., curl, apt-get, npm, pnpm and pip installs, docker pull, and calls to the Diffinery and GitHub APIs.
• Refused: every other port. That includes SSH (git@... remotes, ssh, scp), SMTP (25, 465 and 587), IRC, databases and HTTP on other ports.
• HTTPS is intercepted. Requests leave through the instance's own Worker, which sees them decrypted, as the operator already can for the container itself. Cloudflare re-signs them with a CA it puts in the container at /etc/cloudflare/certs/cloudflare-containers-ca.crt. The runner agent adds that CA to the system store and sets NODE_EXTRA_CA_CERTS and REQUESTS_CA_BUNDLE, so tools that use the system store, Node.js and Python's requests trust it. Tools with their own fixed CA list or certificate pinning, client certificates (mutual TLS), and HTTPS from inside Docker containers a job starts (docker run, services:, RUN steps of a build) fail their certificate checks.

The account that owns the repository decides, as for quotas. Accounts run by a site administrator (their own account, and organizations with a site administrator as an owner) stay open even with EGRESS=web, so the instance's own Deploy and live test workflows keep their access. Self-hosted runners and GitHub imports are not affected. Under wrangler dev sandboxes run in a local process, not containers, so the setting changes nothing there.

To turn it on, add "EGRESS": "web" under vars in wrangler.jsonc; the deploy keeps it. To turn it off, remove it (or set any other value) and deploy again; containers started after that are open.

#How a blocked connection looks

Diffinery doesn't add a line to the job or terminal output when it limits a connection. The tool that made it reports an ordinary network error:

• A port other than 80 or 443 fails to connect, as behind a firewall: for example ssh: connect to host github.com port 22: Connection refused (or Connection timed out), or a mail or database client that can't reach its server.
• HTTPS from a tool that doesn't trust the Cloudflare CA fails its certificate check: for example SSL certificate problem: unable to get local issuer certificate (curl), x509: certificate signed by unknown authority (Go), PKIX path building failed (Java), or self-signed certificate in certificate chain (Node.js with its own CA list). Inside a Docker container a job starts, add the CA from /etc/cloudflare/certs/cloudflare-containers-ca.crt to the image, or run that step on the host.

If the CA never appears in the container, the runner agent writes web-only egress, but /etc/cloudflare/certs/cloudflare-containers-ca.crt did not appear: HTTPS will fail to the container's own log (not the job log), and every HTTPS request from the job fails its certificate check.

#Check it

With EGRESS=web deployed, run a workflow in a repository owned by an account that no site administrator runs (a site administrator's own repositories stay open):

on: workflow_dispatch
jobs:
  egress:
    runs-on: ubuntu-latest
    steps:
      - run: curl -fsSI https://example.com            # works
      - run: git ls-remote https://github.com/git/git HEAD   # works
      - run: npm view left-pad version                 # works
      - shell: bash
        run: "! timeout 10 bash -c '</dev/tcp/github.com/22'"  # SSH port: must not connect

All four steps pass. The last one fails if port 22 is reachable, which means the account is open (a site administrator runs it) or the setting isn't deployed.

#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 (no token, no session) acts as the account with the email in DEV_AUTH, with full access. That account is created on first use and is a site administrator if the email is also in BOOTSTRAP_ADMINS. While DEV_AUTH is set, the email log also keeps each whole message, and GET /api/v3/diffinery/emails returns it, so tests can read emails without delivering them.

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, such as workers.dev or your domain, or a PUBLIC_URL that isn't on the local machine, turns it off, and so does Cloudflare Access.

#Worker secrets

Set with wrangler secret put (the deploy does this for you with scripts/ensure-secrets.sh), never in wrangler.jsonc.

Neither secret is rotated automatically. Changing MASTER_KEY makes every stored secret undecryptable and invalidates unsubscribe links already sent, along with the runtime tokens of running jobs and cache and artifact links already handed out; keep a copy somewhere safe. To rotate the OIDC key, delete OIDC_PRIVATE_KEY and deploy: a new key with a new kid (diffinery-<date>) is generated, and relying parties pick it up from /.well-known/jwks.

To set a secret by hand (for example to restore a backup):

cd apps/diffinery
printf '%s' "$MASTER_KEY" | pnpm exec wrangler secret put MASTER_KEY -c wrangler.deploy.jsonc

#Bindings

Defined in wrangler.jsonc. The deploy creates the underlying resources if they don't exist.

The Durable Object classes are declared in four migrations (new_sqlite_classes): tag v1 for RepoDO, RunnerContainer and SandboxContainer, tag v2 for ImportContainer, tag v3 for ProjectDO and tag v4 for SchedulerDO. wrangler deploy applies a migration tag the account doesn't have yet.

#Other Worker settings

#The dev environment

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

To run an import locally, start it as usual, wait until its git.phase is waiting, claim the transfer, and run the runner agent's import mode against your instance (build it first with pnpm -r build):

TOKEN=$(curl -sS -X POST http://localhost:8787/api/v3/diffinery/imports/<id>/claim | jq -r .token)
DIFFINERY_API_URL=http://localhost:8787 DIFFINERY_IMPORT_ID=<id> DIFFINERY_IMPORT_TOKEN=$TOKEN \
  DIFFINERY_WORK_ROOT=/tmp/diffinery-import node containers/runner/dist/agent.mjs

Only the account that started the import can claim it. In local development (DEV_AUTH in effect, as described in DEV_AUTH), imports also accept plain http:// and loopback GitHub API URLs, for test doubles.

MASTER_KEY is not set in dev. Add it to apps/diffinery/.dev.vars (MASTER_KEY=<base64 of 32 random bytes>) or pass --var MASTER_KEY:<value> to wrangler dev to store Actions secrets locally. The end-to-end tests pass a random one with --var, together with PUBLIC_URL.

#GitHub imports

Imports from GitHub need no setup beyond a normal deploy: the IMPORTER container, the IMPORT_WORKFLOW Workflow and the D1 tables of migration 0010_imports.sql are created by the deploy. What you can tune:

To offer linking through GitHub sign-in, create an OAuth app on github.com (Settings → Developer settings → OAuth Apps) with the authorization callback URL https://git.example.com/settings/linked/github/callback (your PUBLIC_URL plus /settings/linked/github/callback). Then add the client ID under vars in wrangler.jsonc and store the secret:

cd apps/diffinery
printf '%s' "$CLIENT_SECRET" | pnpm exec wrangler secret put GITHUB_OAUTH_CLIENT_SECRET -c wrangler.deploy.jsonc

The OAuth flow asks GitHub for the read:user scope only, uses github.com (not an Enterprise host), 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 settings

Environment variables the scripts in scripts/ read:

scripts/render-config.mjs takes flags instead:

Bootstrap calls it with --public-url https://$DIFFINERY_DOMAIN, --zone $DIFFINERY_ZONE when that is set, and --mail-from notifications@${MAIL_DOMAIN:-$DIFFINERY_DOMAIN}. See Deploy your own Diffinery.

#Repository secrets and variables for the workflows

The workflows in .github/workflows/ read these from the repository (or its production environment):

Deploy reads DIFFINERY_DOMAIN, DIFFINERY_ZONE and MAIL_DOMAIN from the repository's variables and passes them to bootstrap, so you point it at your own hostname without editing the workflow (see Deploy your own Diffinery). Deploy runs on pushes to main on any Diffinery instance, and when started by hand on GitHub.

The Deploy job and the Sync job run in an environment named production. The Live test and Sync workflows target https://diffinery.com and its codician-team/diffinery repository; adapt or delete them for your own instance.

The Import campaign workflow is a manual test of the importer. Started on GitHub (Run workflow), it starts the same workflow on Diffinery and prints its report. On Diffinery it imports a list of public GitHub repositories (the repos input) as private repositories named <owner>/campaign-<github owner>-<github repo>, replacing copies from earlier campaigns. It can then run their push workflows (run_workflows, off by default, because that is third-party code) and writes a report of what came across and what ran.

• Queueing. Diffinery runs at most 3 repository imports per person at a time and answers 429 beyond that, so the campaign queues the rest and starts each one as an earlier one finishes.
• Time limit. Imports still waiting when minutes runs out are reported as not started.
• Failures. When a run fails before writing its report, the GitHub side prints the last 150 lines of the job's log instead.
• Following a run. Set follow_run to a Diffinery run id to print the report of a run that already started.

It needs DIFFINERY_LIVE_TOKEN and, optionally, IMPORT_GITHUB_TOKEN.

Sync to Diffinery copies the four variables above to the repository on Diffinery (only those that are set), together with the secrets CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID and DIFFINERY_LIVE_TOKEN, so the copy deploys to the same place. Each push copies only the branch or tag it pushed, and runs are queued per ref, so a push to another branch never replaces a waiting sync of main. A run started by hand copies every branch and tag; it queues together with main, and moves each ref only if it still points where it did when the run read it, so it never puts back an older commit that another run copied in the meantime. Branch deletions aren't copied. Only a sync of main checks that main on Diffinery matches and waits for its Actions runs.

scripts/diffinery-wait-runs.sh, which the sync workflow uses to wait for Actions runs on a commit, reads DIFFINERY (the instance origin) and TOKEN (a Diffinery token) from the environment:

DIFFINERY=https://diffinery.com TOKEN=dfy_... scripts/diffinery-wait-runs.sh acme/website <sha> 60

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