Flank Runbook

This runbook covers day-2 operations for flank. Flank is the visual workflow editor — it owns no workflow data and runs no executions. Workflows, executions, adapters, and secrets live in brain; flank reaches them over HTTP. For incidents that are really about workflow execution or storage, use the brain runbook. Pair this with flank-oncall for paging policy.

Deploy

Flank is deployed to Railway as beef-flank, root apps/flank, config apps/flank/railway.json. The GitHub workflow at .github/workflows/flank.yml runs CI gating only (lint, typecheck, vitest) on PRs and pushes to main that touch apps/flank/**, the shared ESLint configs, or the workflow. There is no GitHub-driven deploy step. main is the only long-lived branch, and Railway deploys it to production automatically.

Procedure (normal deploy)

1. Open PR. The required flank CI job runs lint, typecheck, and tests when apps/flank/**, the shared ESLint configs, or the workflow changes. Each check runs even if an earlier one fails. All must pass.
2. Merge to main. Railway builds the commit and deploys it to production.
3. Watch logs in Railway for server.started. Confirm the app comes up on its port and the /sign-in healthcheck passes.

Rollback

Railway keeps prior deployments addressable. To roll back:

1. Open the beef-flank service in Railway → Deployments.
2. Find the previous green deploy and choose Redeploy.
3. Confirm server.started and the /sign-in healthcheck.

Then revert the bad commit on main via PR, so the next deploy does not ship it again. Do not push to main directly.

Editor can’t reach brain

Symptoms: the editor loads but workflow lists are empty, saves fail, or executions don’t appear; server-function calls error with brain fetch failures.

Root causes:

• BRAIN_API_URL is unset or wrong on beef-flank.
• Brain is down or unreachable on the configured host.
• The minted Clerk JWT is rejected by brain (expired Clerk session, missing ADMIN role, or Clerk keys rotated without redeploy).

Procedure

1. Confirm brain health first. If brain is down, flank cannot list, load, save, or execute anything — defer flank investigation. See the brain runbook.
2. Check BRAIN_API_URL on the beef-flank Railway service resolves to the right brain host.
3. Check auth. A 401/403 from brain means the Clerk session is invalid or the user lacks ADMIN. Verify CLERK_SECRET_KEY / CLERK_PUBLISHABLE_KEY on beef-flank and that the operator’s account has the ADMIN role in brain.
4. Stuck or failed executions are a brain concern. Brain re-enqueues executions left RUNNING by a crash on boot. Flank only reads execution traces — it cannot recover them. Escalate to brain on-call.

Secrets and adapters

Provider adapters and any secrets they need are owned by brain, not flank. Rotating a provider key or changing an adapter is a brain operation — see the brain docs. Flank’s role is limited to authoring the workflow graphs that reference brain’s adapters.

Legacy, retired (removed). Flank previously synced git-driven seeds/ to sirloin storage at boot (runSeedSync) and resolved adapter secrets from a sirloin-backed store (FlankResolveSecrets, encrypted with FLANK_ENCRYPTION_KEY, 5-minute per-process cache). Those paths have been deleted along with the flank engine and the sirloin flank storage surface.

Healthchecks and signals to watch

• Logger event server.started with port and stage — boot succeeded.
• Railway /sign-in healthcheck — the editor is serving.
• Brain fetch errors in flank logs (brain GET/POST … failed) — flank can’t reach brain; check BRAIN_API_URL, brain health, and auth.
• 401/Unauthorized on UI server functions — Clerk session/keys issue.

For escalation paths, see flank-oncall.