Notes Append Endpoint

Git notes have a new endpoint for appends: POST /notes/append. It adds text to the note on a Git object. If the object has no note, it creates one. It takes the same body as POST /notes without action, and it returns the same response.

curl "$PIERRE_API_BASE_URL/repos/my-repo/notes/append" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "object_ref": "main",
    "note": "Build passed."
  }'

{
  "sha": "e4462d5ba17164b5bbf0cf87d26599980e40115d",
  "notes_ref": "refs/notes/commits",
  "target_ref": "refs/notes/commits",
  "new_ref_sha": "931f0171230808a0c4be8afac463da8de1fd485d",
  "result": {
    "success": true,
    "status": "ok"
  }
}

POST /notes creates a note. It returns 409 when the object already has a note on the notes ref. Its action field is now deprecated. A request with "action": "append" still appends, but new code should call POST /notes/append. We will announce the removal of action in a later post.

A retry of an append is not safe by default. When a request succeeds but you do not get the response, a retry adds the text again. To prevent this, send expected_notes_ref_sha with the notes ref SHA that you saw last: new_ref_sha from a write, or ref_sha from a read.

curl "$PIERRE_API_BASE_URL/repos/my-repo/notes/append" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "object_ref": "main",
    "note": "Deployed to production.",
    "expected_notes_ref_sha": "931f0171230808a0c4be8afac463da8de1fd485d"
  }'

The first request appends the text. The notes ref then has a new SHA, so a retry of the same request returns 409 and adds nothing:

{
  "sha": "e4462d5ba17164b5bbf0cf87d26599980e40115d",
  "notes_ref": "refs/notes/commits",
  "target_ref": "refs/notes/commits",
  "new_ref_sha": "",
  "result": {
    "success": false,
    "status": "conflict",
    "message": "notes ref mismatch: got a2a45c06280aeeadf9a50a16f90515fd0a048e86, expected 931f0171230808a0c4be8afac463da8de1fd485d"
  }
}

After a 409, read the note. If your text is not there, send the append again with the new ref_sha.

See the API reference for repos.notes.append and repos.notes.create.