Attaching Build Metadata with `git notes`

"Which commit is actually live in staging right now?" is a question every deploy pipeline eventually needs to answer, and the usual answers are all a little uncomfortable. Append it to the commit message after the fact, and you've rewritten history and changed the commit's hash — which breaks anyone who already pulled it. Keep it in a separate deploy log, and now there are two systems to keep in sync, and no obvious command that ties a specific commit back to its own deploy history.

git notes attaches arbitrary text to a commit — deploy status, build IDs, whatever a pipeline wants to record — without altering the commit at all. Same hash, before and after.

Attach a note

A commit that just shipped a health check endpoint:

git log --oneline
# a270dd7 add health check endpoint

A deploy pipeline attaches a note the moment it finishes:

git notes add -m "deployed: 2026-08-06T09:14:02Z
environment: staging
status: success
duration: 47s" a270dd7

git log shows the note right alongside the commit it's attached to:

git log -1 --show-notes

commit a270dd74a5f9cc855a67ed8a1934ca225c803b90
Author: Test <[email protected]>
Date:   Thu Aug 6 14:48:55 2026 +0530
 
    add health check endpoint
 
Notes:
    deployed: 2026-08-06T09:14:02Z
    environment: staging
    status: success
    duration: 47s

The commit hash — a270dd7 — is exactly what it was before. Notes live outside the commit object itself, so attaching one never rewrites anything downstream.

Multiple deploys, one commit

The same commit gets promoted to production later. git notes append adds to the existing note instead of replacing it:

git notes append -m "---
deployed: 2026-08-06T11:02:10Z
environment: production
status: success
duration: 52s" a270dd7

git notes show a270dd7

deployed: 2026-08-06T09:14:02Z
environment: staging
status: success
duration: 47s
 
---
deployed: 2026-08-06T11:02:10Z
environment: production
status: success
duration: 52s

One commit, a running log of every environment it's been deployed to and when. git log --oneline for that commit still reads exactly the same as it always did — the extra detail is opt-in, visible with --show-notes or git notes show, invisible otherwise.

Where the notes actually live

Notes aren't part of the commit object; they're their own ref, separate from your branches:

git show-ref

a270dd74... refs/heads/main
ec44c5f7... refs/notes/commits

That refs/notes/commits ref is why a note can be added, removed, or rewritten freely without disturbing a single commit hash on any branch. It's also why notes don't show up automatically for someone who clones the repo — by default, git clone and git fetch don't transfer refs/notes/*. To share them, push and fetch the ref explicitly:

git push origin refs/notes/commits
git fetch origin refs/notes/*:refs/notes/*

Most teams either configure that fetch refspec once in .git/config so it happens automatically, or — just as often — treat notes as a local, per-machine annotation and never push them at all. Both are legitimate; it depends whether the note is meant for your own pipeline's bookkeeping or for the whole team to see.

Editing and removing notes

Notes aren't append-only unless you choose to treat them that way. git notes edit a270dd7 opens the existing note in your editor for a full rewrite, and git notes remove a270dd7 deletes it outright — useful for correcting a deploy record that logged the wrong environment, without needing to touch the commit itself. Because notes live on their own ref, none of this ever changes the commit hash, so it's safe to edit a note on a commit that's already been pushed and pulled by other people; only the note ref needs re-syncing, not the branch.

What it's actually good for

• Deploy tracking, as above — which commit shipped where, and when, without a separate database.
• CI status that outlives the build. Attach a note with the CI run URL and result, so git log on an old commit can still answer "did this pass CI, and where's the log."
• Code review metadata a team wants to keep without editing commit messages after the fact — an approver's name, a ticket link discovered post-merge.

Notes are a light tool, not a replacement for a real deploy dashboard — there's no query language, and finding "every commit deployed to production this week" means scripting over git log --show-notes yourself. But for stamping a fact onto the exact commit it's true of, without touching history, git notes does the one job cleanly.