Reference
GitHub, branches and check runs
Babbit works through a GitHub app installed on your organization. It writes only branches under change/ and newdev/, pull requests, merges you approved and check runs, and never your default branch directly.
Permissions
| Babbit reads | Babbit writes |
|---|---|
| Repository contents. | Branches under change/ and newdev/ only. |
| Pushes, including forced pushes. | Pull requests, and merges of pull requests whose change was approved and verified. |
| Pull request and repository events. | Check runs on pull request heads. |
The app never writes your default branch directly; code reaches it only by merging a pull request. The app doesn't request the workflows permission, so GitHub itself refuses any change that would add a file under .github/workflows/.
Branches
| Branch | What it holds |
|---|---|
main (your default branch) | Your code. Babbit reads it and merges approved pull requests into it. |
newdev/spec | Your spec, on the first repository you connected. Changes only through approved changes. |
change/<id> | The code for one change, one branch per repository it touches. |
newdev/comments/<id> | Comments, merged on their own so a comment never alters an approved change. |
Agents never hold a Git credential. Code leaves a workspace as a diff, and the GitHub app commits it to the change's branch.
Files in your repository
| File | What it is |
|---|---|
newdev/map.json | For each scenario, the test that proves it and the boxes it uses. Kept current by the Code Writing agent in the same pull request as the code. |
newdev/release.json | What a release needs to check for this repository. |
agents/agents.md (spec branch) | Your agents' rules, rendered from their settings and merged by the app. |
Commit trailers
Every commit Babbit makes ends with a line that names its change:
NewDev-Change: ch-1715351fc1The trailer is a label, not proof. Babbit knows a change by its pull requests and the commits they hold. A commit that names a change but isn't in one of its pull requests is drift.
Check runs
Babbit posts three check runs on each pull request head from its own runner. Agents can't edit them. The land step reads all three before it merges.
| Check | Passes when |
|---|---|
newdev/shape | The pull request keeps the shape rules, including a map whose every scenario names a test the repository defines. |
newdev/evidence | Every scenario tested in this repository, and every scenario the change adds or edits, passed at this head. The summary reads like 4/5 verified at 3b9d04e. |
newdev/set | Every pull request in the change is green, so the set can land. When the set is held, its summary says why. |
A check run belongs to its head. A new commit on the pull request has no checks until Babbit runs them again.
What GitHub doesn't stop
Nothing on GitHub stops a person with write access from pushing to the default branch or merging around Babbit's checks. Babbit doesn't hide this. Such a push is read back as drift, with the person who pushed it named. See Keeping spec and code in sync.
Renames and transfers
Babbit knows a repository by its GitHub id and a short key, so renaming or transferring a repository changes its name in Babbit and nothing else.
Related
- Create a project: installing the app.
- Evidence and verification: what the checks prove.