Custom Git Notes Refs

Git notes in Code Storage are no longer limited to refs/notes/commits. Pass a notes ref to write, read, and delete notes on an independent stream. CI status, review summaries, and agent verdicts can each attach a note to the same commit without overwriting each other.

await repo.createNote({
  sha: commitSha,
  note: 'Reviewed. Ready for production.',
  ref: 'reviews',
});

const note = await repo.getNote({ sha: commitSha, ref: 'reviews' });

await repo.create_note(
    sha=commit_sha,
    note="Reviewed. Ready for production.",
    ref="reviews",
)

note = await repo.get_note(sha=commit_sha, ref="reviews")

_, err := repo.CreateNote(ctx, storage.CreateNoteOptions{
	SHA:  commitSHA,
	Note: "Reviewed. Ready for production.",
	Ref:  "reviews",
})

Notes refs resolve the way git notes --ref does: reviews, notes/reviews, and refs/notes/reviews all target refs/notes/reviews. An omitted ref uses refs/notes/commits. Refs outside refs/notes/ and unsafe ref paths return 400. expectedRefSha and refPolicies apply to the notes ref you select.

A new endpoint lists the notes refs in a repository, so you can discover note streams before you read them. Filter by prefix and page with next_cursor. limit defaults to 20 and is capped at 100.

curl "$CODE_STORAGE_BASE_URL/repos/my-repo/notes/refs?prefix=agents/&limit=20" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

{
  "refs": [
    {
      "cursor": "opaque-cursor",
      "ref": "refs/notes/agents/verdicts",
      "sha": "a1b2c3d4e5f6..."
    }
  ],
  "next_cursor": "opaque-cursor",
  "has_more": true,
  "prefix": "refs/notes/agents/"
}

The notes write API now accepts object_ref. Pass a full object SHA, or a branch, tag, or other revision that resolves to a commit. Code Storage resolves the name before it writes the note, and the response reports the resolved commit.

curl "$CODE_STORAGE_BASE_URL/repos/my-repo/notes" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "object_ref": "main",
    "notes_ref": "ci",
    "action": "add",
    "note": "Build passed."
  }'

The REST fields object_ref and notes_ref replace sha and ref. The old names still work but are deprecated.

See the docs →