# Install FlareDispatch — agent runbook

> You are an AI coding agent installing FlareDispatch's GitHub App for an
> operator. FlareDispatch is BYOC: it runs entirely in the operator's own
> Cloudflare account — there is no shared/hosted App, so you create one they
> own. Follow these steps in order. One step needs a human; the rest are yours
> to run.

> Why create an App rather than OAuth sign-in + install? There is no shared App
> to "just install". OAuth only proves who a user is; it can't hand this Worker
> the App ID + private key it needs to mint installation tokens and post Check
> Runs as a bot. So the flow CREATES a GitHub App the operator owns (via the
> App-manifest flow), then installs it. The personal-vs-org choice is the
> "select an account" step — it happens at creation because App ownership is
> fixed when the App is made and can't be moved afterward.

- Dispatcher origin: https://flare-dispatch.fractalbox.dev
- Full docs: https://flare-dispatch.fractalbox.dev
- Source + quickstart: https://github.com/fractalbox/flare-dispatch#quickstart

## Prerequisites (verify before starting)

1. The operator has a local checkout of `flare-dispatch` and `wrangler` is
   authenticated (`wrangler whoami` succeeds).
2. The Dispatcher is already deployed and reachable at the origin above
   (`curl -fsS https://flare-dispatch.fractalbox.dev/health` returns 200). If not, deploy it first with
   `wrangler deploy` from the checkout, then re-check.

## Step 1 — Human creates the App (interactive, hand this off)

The GitHub App manifest flow requires a logged-in github.com session and a
click — you cannot complete it headlessly. Surface this URL to the operator
and ask them to open it and finish the flow:

    https://flare-dispatch.fractalbox.dev/v1/github/install/new

Tell them: pick personal vs. org owner, click through to GitHub, create the
App. GitHub redirects back to a one-time "App created" page that prints five
secret values. Ask them to paste that page's secret block back to you (or to
run the `wrangler secret put` commands themselves if they prefer not to share
credentials with an agent).

## Step 2 — Store the five secrets (you run these)

From the operator's `flare-dispatch` checkout, set each secret with the value
from the success page:

    wrangler secret put GITHUB_APP_ID
    wrangler secret put GITHUB_WEBHOOK_SECRET
    wrangler secret put GITHUB_APP_CLIENT_ID
    wrangler secret put GITHUB_APP_CLIENT_SECRET
    wrangler secret put GITHUB_APP_PRIVATE_KEY   # multi-line PEM, paste whole block

`GITHUB_APP_PRIVATE_KEY` is a multi-line PEM — paste the entire block
including the BEGIN/END lines. Never commit any of these values; they belong
only in Worker Secrets.

## Step 3 — Redeploy so the Worker picks up the secrets

    wrangler deploy

## Step 4 — Install the App on the repos

The success page links to `<app_html_url>/installations/new`. Have the
operator open it and select the repos/org to install on. (This is the operator's
choice of scope — surface the link, don't guess.)

## Step 5 — Verify

Open a pull request (or dispatch a run) on an installed repo. Within a few
seconds a FlareDispatch Check Run should appear on the commit. If it does, the
install is complete. If not, see the BYOC setup spec:
https://flare-dispatch.fractalbox.dev/docs/05-byoc

## Notes

- Idempotent: re-running `wrangler secret put` overwrites; re-running
  `wrangler deploy` is safe.
- Pure-webhook mode means no `.github/workflows` file is required — installing
  the App is the trigger. Details: https://flare-dispatch.fractalbox.dev/docs/05-byoc