shitrat-github

# ShitRat GitHub Use ShitRat when GitHub should show `shitratgit[bot]` as the actor instead of Joel. ## Default rule Prefer ShitRat for published agent-authored GitHub comments/reviews: ```bash shitrat status skillrecordings/migrate-egghead shitrat comment skillrecordings/migrate-egghead 26 --body-file comment.md shitrat review skillrecordings/egghead-next 1608 --event REQUEST_CHANGES --body-file review.md shitrat reply skillrecordings/egghead-next 1608 123456 --body-file reply.md shitrat edit-pr skillrecordings/egghead-next 1608 --title "fix: clearer title" --body-file pr.md --base main --state open shitrat tag example/project --name v0.1.0 --target aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --message "Release v0.1.0" --dry-run shitrat release example/project --tag v0.1.0 --title "First release" --notes-file notes.md --dry-run shitrat release example/project --tag v0.1.0 --generate-notes --draft --prerelease --dry-run shitrat ready-pr badass-courses/drovr 698 --dry-run shitrat enqueue-pr badass-courses/drovr 696 --dry-run shitrat convert-to-draft badass-courses/drovr 696 --dry-run shitrat label badass-courses/drovr 886 --add "NO MERGE" --dry-run shitrat set-status badass-courses/drovr <sha> --state failure --context gavel/hold --description "Held by review" --dry-run shitrat checks badass-courses/drovr <sha> shitrat pr-status badass-courses/drovr 867 shitrat run-log badass-courses/drovr <job-id> --tail 300 shitrat rerun badass-courses/drovr <run-id> --failed --dry-run shitrat merge joelhooks/shitrat-cli --base main --head feature-branch --message "merge: feature branch" shitrat push joelhooks/shitrat-cli --repo-dir /path/to/checkout shitrat commit-file joelhooks/shitrat-cli --branch main --message "docs: update notes" --file README.md shitrat commit-files joelhooks/shitrat-cli --branch main --message "docs: update docs" --file README.md --file docs/shitrat-commit-flow.md ``` If the pi extension is loaded, prefer the tools: - `shitrat_status` - `shitrat_comment` - `shitrat_review` - `shitrat_reply` - `shitrat_edit_pr` - `shitrat_merge` - `shitrat_commit_file` - `shitrat_commit_files` ## Safety rails - Do not paste or print the private key. - Do not use Joel's `gh pr review` when the desired actor is ShitRat. - Use `shitrat reply` / `shitrat_reply` for inline review threads; `comment` posts to the PR conversation, not an inline thread. - Use `shitrat edit-pr` / `shitrat_edit_pr` to update a PR's title, body, base, or open/closed state instead of `gh pr edit`. - Use `shitrat tag` and `shitrat release` instead of Joel-authenticated tag/release tools. Both default to dry-run, read preflight state, and require `--yes` for writes; do not combine it with `--dry-run`. Get approval for the exact preview before confirming. Smoke only with `--dry-run`, never a real tag or release. - `tag` requires a full existing commit SHA and creates only an annotated tag and a new ref. It refuses every existing tag, even the same target with different notes. Its preview's `<created-tag-object-sha>` is a reference to the annotation response, not the commit SHA. `release` requires an existing tag and refuses duplicate releases, including drafts. `--notes-file` and `--generate-notes` are mutually exclusive; `--draft` and `--prerelease` are independent. - Keep tag changes serialized with release creation: GitHub has no atomic require-existing-tag precondition, so a deletion after the final recheck can race the release API. Both commands read back writes and exit nonzero on refusal or mismatch. Failures never trigger rollback; inspect tags/releases before retrying. Do not add App permissions or fall back to Joel's credentials. - Use `shitrat ready-pr` instead of `gh pr ready` to take a pull request out of draft. - On a branch with a merge queue, `merge-pr` fails with `MERGE_QUEUE_REQUIRED`; use `shitrat enqueue-pr`, which queues the head it read (`expectedHeadOid`) and reports the queue position and state. The queue's ruleset decides the merge method. - To hold a pull request as ShitRat, use `shitrat label --add` (the repo's hold label, e.g. `NO MERGE`), `shitrat set-status --state failure` on its head sha, or `shitrat convert-to-draft`, which also drops it from the merge queue. `label --add` refuses a label the repo lacks, so a typo cannot mint a new label. - Watch CI with `shitrat checks`, `shitrat pr-status` and `shitrat run-log`, not unauthenticated curl: they spend the app's 5,000 requests an hour instead of the 60 an IP shares. They exit 1 on a failed read, so shell watches fail closed; branch on `error.code`. For a GitHub Actions check, the check run id is the job id `run-log` takes. `run-log` needs Actions: read on the app; never fall back to Joel's token when it says so. Use `shitrat rerun <repo> <run-id> [--failed]` instead of `gh run rerun`; `run-log` reports the `run_id`. A 409 `CONFLICT` means the run is still going. After the rerun is accepted, `attempt_confirmed: false` means GitHub has not shown the new `run_attempt` yet; re-read with `--dry-run` rather than assuming it. - After a real `push` or `create-pr`, ShitRat runs `fleet-compute attest --github <repo> --sha <full head sha>` when fleet-compute is on PATH. It is best-effort: exit 3 (including `FLEET_ATTEST=off`) adds nothing; any other outcome lands in the `attest` field, and the push or PR result stays `ok: true`. Every attempt, including exit 3 with its reason and `"fleet-compute": "missing"`, is appended to `~/.shitrat/log/attest.jsonl`; read that file back instead of the push JSON. - Use `shitrat status <owner/repo>` first when repo access is uncertain. - Use `--body-file` for non-trivial Markdown so shell quoting does not mangle review text. - Use `--dry-run` before writing unless Joel explicitly asked to commit/merge as ShitRat. - `merge` uses GitHub's merge endpoint to merge one branch into another as `shitratgit[bot]`, so do not fake a merge by replaying branch contents onto `main`. - When a checkout exists, commit locally as `shitratgit[bot]` so commit hooks run, then publish the unchanged commits with `shitrat push`. It rejects non-bot outgoing authors unless `--allow-any-author` is explicit, disables `pre-push` hooks so they cannot inherit the installation token, and never rewrites history or force-pushes. - `commit-file` is for small, intentional clone-less edits. `commit-files` is for small atomic clone-less batches. On existing branches they use GitHub blobs/trees with web-flow signing; on brand-new empty repos they create one root commit through a temporary ShitRat-authenticated git push. They cannot run local hooks. - Only post comments/reviews/commits when the user asked to publish or the workflow clearly requires it. ## Secrets The CLI reads env first, then `agent-secrets` leases: - `shitrat_github_app_id` - `shitrat_github_private_key` - `shitrat_github_installations_json` - `shitrat_github_installation_id_<owner_key>` as fallback Known owner keys: - `joelhooks` - `badass_courses` - `skillrecordings` - `wzrrd_sh` ## Install as pi package From the repo root: ```bash pi install /Users/joel/Code/joelhooks/shitrat-cli ``` Or once pushed: ```bash pi install git:github.com/joelhooks/shitrat-cli ```