Connecting a repository
How a project's owner connects the project's git repository to Sparrow.
A project's work usually lives in one git repository. Its owner connects it once:
-
Name it on the project. Open the project, edit it, and fill in Git repository (
https://github.com/<owner>/<repo>). The board shows it under the project's name. -
Add its
sparrow.jsonat the repository's root (see Which project a file belongs to). A repository that holds one project's work maps everything to it, and may name the branch its pull requests target:{"schemaVersion": "2.2.0", "targetBranch": "main", "projects": {"CHURCH": {"paths": ["**"]}}}Commit it like any other change, from a task.
-
Let GitHub's merge button only rebase. Pull requests land with "Rebase and merge" (law
feature-branch-per-ticket), and a new GitHub repository also offers merge commits and squash merging. In Settings → General → Pull Requests, untick Allow merge commits and Allow squash merging, or run:gh api -X PATCH repos/<owner>/<repo> \ -F allow_merge_commit=false -F allow_squash_merge=false -F allow_rebase_merge=true -
Choose the default branch. Agents cut their branches from it and open their pull requests against it, reading it from GitHub rather than assuming
main(lawagents-never-git-push-to-main). If the repository deploys from an integration branch, such asdev, and you promote it tomainyourself, make the branch that pull requests should land on the default (Settings → General → Default branch). Alternatively, leave GitHub's default branch alone and name the target insparrow.json'stargetBranch. -
Protect the default branch and restrict tags, where your plan allows. A ruleset requires a pull request for every change to the default branch and limits who creates tags (law
agents-never-git-push-to-main). GitHub offers rulesets and branch protection on public repositories, but on private ones only with GitHub Pro, Team or Enterprise; otherwise its API answers 403. Without them nothing on GitHub stops a push to the default branch, and the push guard is the only check: passerines registers.github/scripts/git_push_guard.pyas a hook in.claude/settings.json, and another repository can copy the script and register it the same way. -
Landing automation is optional. In a repository with it, the automation moves every merged task to Completed once every post-merge run succeeded, or to Blocked when one didn't, whether you or the automation merged the pull request, and lands the pull request of a task whose
reviewRequiresValidationis off. passerines has it:universal-land-pr.yml(root ADR-0009 and ADR-0010), a GitHub App allowed to read and write contents and pull requests, and a machine credential stored as a secret for every project whose tasks land in the repository, whether their review is on or off (see Machine credentials). Without a project's credential, the automation can't move that project's tasks. A repository without the automation leaves every landing, and moving every merged task, to you (lawno-automated-commits-to-main).
Everyone who works on the repository through an agent also sets up the MCP server and the effort-to-model mapping (see Agents and the MCP server).