GitHub Action and pull requests

The action is the file action.yml at the root of the Roook repo. On each run it:

1. Chooses the Bob mode. It is replay unless you ask for live, and live turns into replay when no key is present.
2. Installs uv, then Roook itself from the action's own checkout, with Python 3.12.
3. In live mode, sets up Node 24 and installs Bob Shell from the package you named. In replay mode, copies your recordings into place.
4. Runs rook run --ci --auto on your checkout, with your request and budgets. Roook starts your app in Docker on the runner.
5. Adds rook-report.md to the job summary, and posts it as one comment on the pull request.
6. Fails the job when an approved rule is broken or the run did not finish.

The action reports; it does not open fix pull requests. It runs on a local checkout, so even with auto on, a fix stays on a branch inside the runner's workspace, which is thrown away with the runner.

name: rook
on:
  pull_request:
permissions:
  contents: read
  pull-requests: write
jobs:
  rook:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false
      - uses: tony19053000/rook@<full-commit-sha>
        with:
          bob-mode: live
          bob-api-key: ${{ secrets.BOB_API_KEY }}
          bob-package: <url-or-path-of-the-bob-shell-package>

• Replace <full-commit-sha> with the full SHA of the Roook commit you want, so the action cannot change under you. Roook has no release tags yet, so there is no version tag to use instead.
• Replace the bob-package value with a Bob Shell package you are entitled to use, as a URL or a path npm can install. Roook does not host one. Without it, live mode stops with an error.
• Store your IBM Bob key as the repository secret BOB_API_KEY.

repo-path

The folder to check. Roook copies it and never changes it. Default: the repo root.

request

What to look for. Default: find bugs in my app.

bob-mode

replay (the default): recorded Bob answers from the recordings input. live: real Bob calls, which need bob-api-key and bob-package. Live falls back to replay when the key is empty, as on a pull request from a fork.

bob-api-key

Your IBM Bob key. Pass the repository secret, never the key itself.

bob-package

Live mode: the Bob Shell package for npm to install, as a URL or a path.

recordings

Replay mode: a folder of Bob recordings, copied to ~/.rook/recordings on the runner.

auto

true (the default) adds --auto, so Roook answers its own questions. false runs rook run --ci alone.

budget

The Bob coin budget for the run. Default: 1.5.

seconds

The search budget in seconds. Default: 120.

setup

Names of environment variables your app needs, separated by spaces. Each is passed to Roook as a setup value.

report-dir

Where rook-report.json and rook-report.md are written. Default: rook-report.

comment

true (the default) posts or updates one Roook comment on the pull request.

github-token

The token used for the comment. Default: the workflow's own token, which needs pull-requests: write.

Outputs:

exit-code

Roook's exit code: 0, 1 or 2, as below.

report

The path of rook-report.md.

bob-mode

The Bob mode actually used: live or replay.

0

Every approved rule held. The job passes.

1

An approved rule is broken: the engine found a counterexample. The job fails.

2

The run did not finish: it failed or was stopped before it could say. The job fails. This is not a verdict on your code.

rook run --ci uses the same codes when you run it yourself.

Roook keeps one comment on the pull request and updates it on every run, instead of adding a new one each time. It holds rook-report.md: each approved rule and its result, and for a broken rule the minimal steps, the replay count, the observed values and the expected check.

• The workflow needs the pull-requests: write permission for the comment. Set comment to false to skip it; the report is still in the job summary.
• Text that comes from your app or from Bob is put in code spans in the report, so it cannot mention people or inject formatting.
• Only a comment written by a bot is updated, so nobody can redirect the update by copying Roook's marker into their own comment.

• The action has not yet been run on a GitHub-hosted runner from start to finish. Its parts are covered by automated tests and a dry run of the comment step. Treat it as untested until you have seen it pass in your repo.
• Live mode needs a Bob Shell package you provide. Roook does not host or redistribute Bob Shell.
• Replay mode only fits code that has not changed. A recording is matched by the exact prompt, and the prompts include a digest of your files. A pull request that changes the code misses its recordings, and the run does not finish (exit code 2). For real pull requests, use live mode.
• The runner must have Docker. GitHub's ubuntu-latest runners do.
• rook init writes a different, simpler starter workflow that installs Roook with uv and runs rook run . --ci --auto. It does not install Bob Shell and does not use this action, so on a GitHub-hosted runner it needs a Bob Shell install step added before it can make live runs.

Fix pull requests come from the CLI on your machine, for a repo on GitHub:

1. In the Roook web app, sign in and connect GitHub. This installs the Roook GitHub App on the repos you choose. It asks for Contents (read and write), Pull requests (read and write) and Metadata (read).
2. On your machine, sign in with rook login.
3. Run rook run owner/name. The CLI asks the Roook server for a short-lived token for that one repo, clones the repo into a workspace, and does everything else locally: your Docker, your IBM Bob key.
4. When a fix is verified and you say yes, Roook pushes a rook/fix-* branch and opens a pull request.

The pull request's commit holds the fix, the regression test, rook/rook.yaml and the counterexample file. Its description names the rule, the size of the counterexample and its replay count, the regression test and the verification result, and gives the command to replay it. Roook never pushes to your default branch and never force-pushes.

A local folder

No GitHub involved. The verified fix is committed to a rook/fix-* branch in the run's workspace, ~/.rook/workspaces/<run-id>/, and nothing is pushed. Read it there with git, and apply it to your repo yourself.

The hosted site

Hosted runs of your own repos are turned off. Signed-in users can connect GitHub and see their repos, and the site shows the CLI command to run a repo on their own machine.

• GitHub App permissions and tokens