[vaind]

A sandbox holds one git grant at a time, and a grant names one operation and its repositories. A pod that fetches and pushes can't get both, and a push grant can update any ref, including the default branch, tags and deletions, since GitServer relays pushes unread.

GrantV2 holds a list of rules, each a repository, an operation and the branches it may touch.

• Fetch rules set branches or any_object, one required, so leaving out branches never reads as full access. Fetch rules listing branches stay refused until GitServer can keep a fetch to them.
• Push rules set branches or full-match branch_patterns, and create_only allows only new branches. An update passes if any rule allows it, so a create_only pattern can sit next to the branch the pod already made.
• Unknown fields and versions are refused, so later fields only need verifiers to ship first.

GitServer reads a push's ref updates before the pack and refuses the whole push unless a rule allows every one of them. Anything it doesn't recognise refuses the push too: no body, push options, a signature, or a capability git doesn't send. authorize_request refuses a GrantV2 push outright, since only GitServer reads its ref updates. git reads the answer only after sending the whole push, so the server reads the pack to the end and answers with a status report, which git shows as ! [remote rejected] main -> main (reason), where a 403 shows only "RPC failed".

Grant is now GrantV1, with Grant kept as an alias. It still signs and verifies, with pushes relayed unread, so signers can switch later, and it's marked deprecated for type checkers.

For reviewers:

• GitServer doesn't know the default branch, so keeping it out of push rules, by name or pattern, is the signer's job.
• Patterns run against branch names the client chooses, so signers must avoid patterns that backtrack catastrophically.
• verify_grant now returns GrantV1 | GrantV2, so code that reads operation or repositories from its result needs to narrow first. Neither Seer nor Sentry does.

Open question:

1. Major release instead - the feature flag that guards Sentry's git endpoint hasn't been enabled in production, so no version 1 grant is in use yet. This could ship as a major release in which the server no longer accepts version 1 grants and GrantV1 goes away, rather than a minor release that keeps it working while deprecated. Reviewers, please weigh in.

Example: a pod's grant once it has pushed its first branch

The pod may fetch main and its own branch, start new branches under seer/, and keep pushing to seer/fix-login, which it already created. The fetch rule shows the intended shape, which GitServer refuses until it can keep a fetch to listed branches. Until then, Seer's checkout uses a fetch rule with "any_object": true before any agent runs.

{
  "organization_id": 1,
  "referrer": "seer.coding_job",
  "rules": [
    {"operation": "fetch", "repository": 42, "branches": ["main", "seer/fix-login"]},
    {"operation": "push", "repository": 42, "branch_patterns": ["seer/.+"], "create_only": true},
    {"operation": "push", "repository": 42, "branches": ["seer/fix-login"]}
  ],
  "version": 2,
  "exp": 1794243666,
  "iat": 1794242766,
  "aud": "scm-git-grant"
}

Under this grant, git shows each refused push like this:

$ git push origin HEAD:main
 ! [remote rejected] HEAD -> main (the git grant does not cover this branch)
$ git push origin HEAD:seer/other    # seer/other already exists
 ! [remote rejected] HEAD -> seer/other (the git grant allows only creating this branch)
$ git push origin :seer/fix-login
 ! [remote rejected] seer/fix-login (the git grant does not allow deleting a branch)

Changelog Entry

• Add GrantV2, a git grant made of repository, operation and branch rules, and keep pushes under it to their rules' branches. Rename Grant to GrantV1, keeping Grant as an alias, and deprecate it.

🤖 Generated with Claude Code

[linear-code]

CW-3072