| name | deploy-crabd-broker |
| description | Deploy the crab'd token broker so repos get the canonical crab'd[bot] identity via OIDC. Use when someone wants one shared bot identity across many repos/orgs instead of per-repo App keys. |
Deploy the crab'd broker
The broker (packages/broker, @crabd/broker) holds the canonical crab'd App's private key and vends
short-lived, repo-scoped installation tokens after verifying a run's GitHub OIDC token. Deploy it so
workflows can use the canonical crab'd[bot] with only permissions: id-token: write.
1. Prerequisites
- The canonical crab'd GitHub App created (from
app/manifest.json) and installed on the
target repos/org.
- Its App ID and private key (PEM).
2. Configure
The broker reads:
CRABD_APP_ID, CRABD_APP_PRIVATE_KEY — the App credentials (server secrets). The key may be a
raw PEM or a base64-encoded PEM (easier to store as a single-line env var:
base64 -w0 crabd-app.pem).CRABD_BROKER_AUDIENCE — OIDC audience (default crabd-broker); must match what the action sends.PORT — Node listen port (default 8787).
3. Deploy
Node (container or host):
pnpm --filter @crabd/broker build
CRABD_APP_ID=... CRABD_APP_PRIVATE_KEY="$(cat key.pem)" node packages/broker/dist/node.mjs
Cloudflare Workers: import createBroker from @crabd/broker and wire it to a Worker fetch
handler, providing the App credentials from Worker secrets (don't use the Node entry).
Put it behind HTTPS and note the public URL. Health check: GET /health → { ok: true }.
4. Point workflows at it
If not baking the URL into DEFAULT_BROKER_URL, set it per workflow:
- uses: louisescher/crabd@v0
with:
broker-url: https://your-broker.example.com
5. Verify
Trigger a run in a repo where the App is installed, with id-token: write. Confirm the comment posts
as crab'd[bot] and the broker logs a successful /token exchange. A 502 usually means the App isn't
installed on that repo; a 401 means an audience/issuer mismatch.
