Appearance
Git Commit Trailers for CI/CD Automation
git interpret-trailers is Git's structured metadata engine for commit messages. It embeds key-value pairs (trailers) in the message footer — Signed-off-by:, Change-Id:, Reviewed-by: — and provides plumbing to parse, add, replace, or query them programmatically. For a DevOps engineer, this turns commit messages into a machine-readable database that pipelines can gate on.
Why a DevOps Engineer Needs This
DCO enforcement.
Signed-off-by:trailers prove the contributor accepted the Developer Certificate of Origin. A pre-receive hook can reject commits missing this trailer without needing a separate legal database.Gerrit integration. Gerrit's
Change-Id:trailer links related patch sets.git interpret-trailers --parseextracts it for cross-referencing in CI.CI gating without config files. Custom trailers like
Deploy-Env: stagingorCI-Skip: trueembed deployment intent in the commit itself. Pipelines read them with a one-liner instead of parsing commit message bodies by convention.Cherry-pick tracking.
git cherry-pick -xappends acherry picked from commit <SHA>trailer automatically. Combined with backport pipeline scripts that parse this trailer, you can trace every upstream fix into release branches.Automated release notes. Trailers like
Fixes: #123,Closes: PROJ-456,Reviewed-by: alice, orRelease-Notes: <text>give pipelines structured data for changelog generation without regex scraping.
How Trailers Work
A trailer sits at the end of a commit message, separated from the body by a blank line:
Subject line
Body paragraph. Free-form.
Signed-off-by: Jane Doe <jane@example.com>
Reviewed-by: John Smith <john@example.com>
CI-Skip: trueEach trailer is a token: value pair. The token is case-insensitive by default. Multiple trailers with the same key are allowed (e.g. multiple Reviewed-by: lines).
Parsing trailers: git interpret-trailers --parse
$ git log -1 --format="%B" | git interpret-trailers --parse
Signed-off-by: Jane Doe <jane@example.com>
Reviewed-by: John Smith <john@example.com>
CI-Skip: trueThis is the programmatic extraction command. Pipe to grep, awk, or jq in CI:
bash
# Check whether a commit has a specific trailer
trailer=$(git log -1 --format="%B" | git interpret-trailers --parse | grep -i '^CI-Skip:' | sed 's/CI-Skip: *//I')
if [ "$trailer" = "true" ]; then
echo "Skipping CI per commit trailer"
exit 0
fiThe --format placeholder %(trailers) does the same inline:
bash
git log -1 --format="%(trailers:key=Reviewed-by,separator=%n)"Adding trailers at commit time
bash
# Single trailer
git commit -m "Fix rate limiter race" --trailer "Signed-off-by: Jane Doe <jane@example.com>"
# Multiple trailers
git commit -m "Add retry to s3 upload" \
--trailer "Signed-off-by: Jane Doe <jane@example.com>" \
--trailer "Reviewed-by: John Smith <john@example.com>"Adding trailers to existing commits
Use git interpret-trailers with --in-place:
bash
# Append a trailer to HEAD's message
git interpret-trailers --in-place --trailer "Release-Phase: staging" HEAD
# Append via commit --amend
git commit --amend --trailer "Reviewed-by: alice" --no-edit--in-place operates on the raw file (.git/COMMIT_EDITMSG for HEAD). Safe for automated backport pipelines that want to stamp the source commit SHA.
Configuration
Trailer behaviour is controlled via trailer.* config keys in .gitconfig or repo-local config.
trailer.separators
Default separators are : (Signed-off-by: Jane). You can add alternatives:
[trailer "Ticket"]
key = Ticket-Ref
command = echo "PROJ-$(date +%s)"But the default : is what nearly every pipeline expects. Don't change it without updating your consumers.
trailer.where
Controls where a new trailer is inserted:
| Value | Behaviour |
|---|---|
after (default) | Appends after existing trailers of same key |
before | Prepends before existing ones |
end | Appends at the very end of the trailer block |
start | Prepends at the start of the trailer block |
Set per-trailer:
[trailer "Reviewed-by"]
where = beforetrailer.ifexists
Controls what happens when a trailer with the same key already exists:
| Value | Behaviour |
|---|---|
addIfDifferent | Append only if the value differs from every existing one |
addIfDifferentNeighbor | Append only if the value differs from the last one |
add (default) | Always append |
replace | Replace the last instance |
doNothing | Skip silently |
trailer.ifmissing
Controls what happens when no trailer with that key exists:
| Value | Behaviour |
|---|---|
add (default) | Append the new trailer |
doNothing | Skip |
trailer.<key>.command
Define a shell command that generates the trailer value dynamically:
[trailer "ChangeId"]
key = Change-Id
command = echo "I$(uuidgen | tr -d -)"Now git commit --trailer "Change-Id:" runs the command and inserts Change-Id: If3c85062b95262e2a9f129380....
DevOps Patterns
1. DCO pre-receive hook
In a server-side pre-receive hook, validate that every new commit carries Signed-off-by: from an author matching the commit author:
bash
#!/bin/sh
# .git/hooks/pre-receive
while read oldrev newrev ref; do
for sha in $(git rev-list "$oldrev..$newrev"); do
author=$(git log -1 --format="%aN <%aE>" "$sha")
sob=$(git log -1 --format="%(trailers:key=Signed-off-by,valueonly)" "$sha" | head -1)
if [ "$author" != "$sob" ]; then
echo "pre-receive: commit $sha missing Signed-off-by from $author"
exit 1
fi
done
done2. CI skip gate
Read CI-Skip from the HEAD commit of a PR branch and skip the pipeline:
bash
# .forgejo/workflows/ci.yaml or similar
skip_trailer=$(git log -1 --format="%(trailers:key=CI-Skip,valueonly)" 2>/dev/null)
if echo "$skip_trailer" | grep -qi "^true$"; then exit 0; fi3. Backport stamp in CI
When a pipeline cherry-picks a fix into a release branch, stamp the source:
bash
# CI backport script
sha=$(git rev-parse HEAD)
git cherry-pick -x "$sha" # appends (cherry picked from commit <SHA>) trailer
# Or with a custom trailer
git cherry-pick "$sha"
git commit --amend --trailer "Backport-Source: $sha" --trailer "Backport-Branch: $CI_BRANCH" --no-edit4. Release phase gating
Gate a deployment pipeline on Deploy-Env::
bash
env=$(git log -1 --format="%(trailers:key=Deploy-Env,valueonly)")
case "$env" in
staging) deploy_staging ;;
canary) deploy_canary ;;
production) deploy_prod ;;
*) echo "Unknown Deploy-Env: $env"; exit 1 ;;
esac5. Automated changelog from trailers
Extract Release-Notes: trailers between two tags:
bash
git log v1.0..v2.0 --format="%(trailers:key=Release-Notes,valueonly)" \
| grep -v '^$' > changelog-entries.txt6. Prepare-commit-msg hook
Inject a Change-Id: automatically on every new commit, matching Gerrit's expectation:
bash
#!/bin/sh
# .git/hooks/prepare-commit-msg
# Generate Change-Id only if none exists
if ! grep -q "^Change-Id:" "$1"; then
change_id="I$(date +%s)-$(git diff | sha1sum | cut -d' ' -f1 | head -c 20)"
git interpret-trailers --in-place --trailer "Change-Id: $change_id" "$1"
fi7. Multi-trailer extraction in CI
Parse multiple trailers from a single commit and export them as environment variables:
bash
# Extract all known trailers from HEAD
for trailer in $(git log -1 --format="%(trailers:only)" | sed 's/: /=/g'); do
export "GIT_$trailer"
doneNow $GIT_Signed-off-by, $GIT_Reviewed-by, etc. are available to the pipeline.
Common Pitfalls
Trailers require a blank line separator. If the commit body runs into the trailers without a blank line, Git won't parse them as trailers. Always keep
\n\nbefore the trailer block.Case sensitivity is fuzzy. Trailer keys are normalized:
ci-skip,CI-Skip, andCI_SKIPall match the same key. Standardise on the Gerrit convention (Title-Case with hyphen).--in-placewrites to the commit message file. It affectsgit logoutput but won't change the commit SHA until agit commit --amendor a rebase finalises the object. Use in prepared workflows, not mid-pipeline.git interpret-trailers --parsestrips the body. To get both body and trailers, usegit log -1 --format="%B" | git interpret-trailers(no--parse), which prints the full message with the trailers block appended or corrected.%(trailers:key=...,valueonly)in format strings is available from Git 2.44+. Older Git versions require piping throughgit interpret-trailers --parse | grep.
See also
docs/devops-workflows/git-commit-signing.md— GPG/SSH commit signing, complementary to DCO trailersdocs/devops-workflows/git-notes-ci-annotations.md— alternative metadata storage on commits without remessagedocs/devops-workflows/git-hooks-devops.md— pre-receive hook enforcement patternsdocs/recipes/trailers-quick.md— one-page cheat sheet