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:

  1. 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.

  2. Add its sparrow.json at 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.

  3. 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
    
  4. 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 (law agents-never-git-push-to-main). If the repository deploys from an integration branch, such as dev, and you promote it to main yourself, 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 in sparrow.json's targetBranch.

  5. 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.py as a hook in .claude/settings.json, and another repository can copy the script and register it the same way.

  6. 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 reviewRequiresValidation is 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 (law no-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).