ahrav/run-runbook

Run Runbook

Launch runbooks from runbooks/ via Jetty using run-runbook.sh.

Workflow

1. Create or update runbook-params.json with any parameter overrides the user requested
2. Run ./run-runbook.sh <task-name>
3. Report the trajectory ID and workflow ID

Parameters File

If runbook-params.json is missing, create it locally at repo root before launching. The repo .gitignore excludes both runbook-params.json and run-runbook.sh, so these runbook helper files may exist only in your local checkout.

NEVER write secrets or tokens into runbook-params.json. The run-runbook.sh script injects GITHUB_TOKEN automatically via gh auth token at launch time. Do not add a GITHUB_TOKEN field to the JSON file — it is unnecessary and risks leaking credentials.

{
  "repository": "ahrav/gossip-rs",
  "pr_number": "312",
  "base_branch": "main",
  "CARGO_HOME": "/Users/<you>/.cargo",
  "timeout_sec": 3600
}

Common Overrides

| Parameter | Default | Override for | |-----------|---------|-------------| | timeout_sec | 3600 (1 hr) | Long audits: 7200 (2 hr), 10800 (3 hr) | | pr_number | varies | PR-specific runbooks (reviews, comment response) | | base_branch | main | Auditing a different branch |

Use the Edit tool to update runbook-params.json before running the script. Restore the original value immediately after launching if the override was one-time — the runbook runs remotely and does not re-read the local file.

Run the Script

./run-runbook.sh <task-name>

The <task-name> matches the filename in runbooks/ without the .md extension.

List Available Runbooks

if [ -d runbooks ] && ls runbooks/*.md >/dev/null 2>&1; then
  ls runbooks/*.md | sed 's|runbooks/||;s|\.md$||'
else
  echo "No local runbooks found. Ensure local runbook assets are provisioned."
fi

Output

The script prints trajectory and workflow IDs on success:

Run launched successfully:
  Task:          <task-name>
  Trajectory ID: <id>
  Workflow ID:   <id>

Report these to the user so they can track progress in Jetty.

Common Mistakes

| Mistake | Fix | |---------|-----| | Using RemoteTrigger API directly | Use run-runbook.sh — it handles param injection and Jetty API | | Forgetting to update timeout for long tasks | User-requested timeout goes in runbook-params.json timeout_sec | | Passing wrong task name | Name must match a file in runbooks/ without .md. The script lists available names on error. | | Not reporting trajectory ID | Always show the trajectory and workflow IDs in your response | | Not knowing which runbook to run | Use the guarded runbook-listing command above and ask the user to pick one | | Writing GITHUB_TOKEN into runbook-params.json | Never. run-runbook.sh injects the token via gh auth token automatically. Writing tokens into files risks credential leaks. |