Skip to content
Beef Docs

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 and release that touch apps/flank/**. There is no GitHub-driven deploy step — Railway deploys automatically from the configured branch. The exact per-environment branch mapping (which Railway environment tracks main vs release) is configured in the Railway dashboard and is not checked into this repo. TODO(@law): document the current mapping here.

Procedure (normal deploy)

  1. Open PR. CI runs flank-lint, flank-typecheck, flank-test in parallel. All must pass.
  2. Merge to main. Railway picks up the commit on the staging service and rebuilds.
  3. Watch logs in Railway for server.started. Confirm the app comes up on its port and the /sign-in healthcheck passes.
  4. Promote to production by merging main → release. The CI workflow runs the same lint/typecheck/test gates on release; Railway then redeploys the production service from the release branch. TODO(@law): confirm whether any additional release step (changelog, tag, manual promote) is expected beyond the merge.

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.

If the bad commit is already in release, revert via PR. Do not push to release 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, being retired. 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 are superseded by brain. TODO(@law): remove the seed-sync and gRPC secret wiring once nothing depends on it.

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.