Skip to content

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 --parse extracts it for cross-referencing in CI.

  • CI gating without config files. Custom trailers like Deploy-Env: staging or CI-Skip: true embed 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 -x appends a cherry 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, or Release-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: true

Each 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: true

This 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
fi

The --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:

ValueBehaviour
after (default)Appends after existing trailers of same key
beforePrepends before existing ones
endAppends at the very end of the trailer block
startPrepends at the start of the trailer block

Set per-trailer:

[trailer "Reviewed-by"]
        where = before

trailer.ifexists ​

Controls what happens when a trailer with the same key already exists:

ValueBehaviour
addIfDifferentAppend only if the value differs from every existing one
addIfDifferentNeighborAppend only if the value differs from the last one
add (default)Always append
replaceReplace the last instance
doNothingSkip silently

trailer.ifmissing ​

Controls what happens when no trailer with that key exists:

ValueBehaviour
add (default)Append the new trailer
doNothingSkip

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
done

2. 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; fi

3. 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-edit

4. 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 ;;
esac

5. 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.txt

6. 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"
fi

7. 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"
done

Now $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\n before the trailer block.

  • Case sensitivity is fuzzy. Trailer keys are normalized: ci-skip, CI-Skip, and CI_SKIP all match the same key. Standardise on the Gerrit convention (Title-Case with hyphen).

  • --in-place writes to the commit message file. It affects git log output but won't change the commit SHA until a git commit --amend or a rebase finalises the object. Use in prepared workflows, not mid-pipeline.

  • git interpret-trailers --parse strips the body. To get both body and trailers, use git 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 through git interpret-trailers --parse | grep.

See also ​

  • docs/devops-workflows/git-commit-signing.md — GPG/SSH commit signing, complementary to DCO trailers
  • docs/devops-workflows/git-notes-ci-annotations.md — alternative metadata storage on commits without remessage
  • docs/devops-workflows/git-hooks-devops.md — pre-receive hook enforcement patterns
  • docs/recipes/trailers-quick.md — one-page cheat sheet

Git Master — Git Reference for Every Skill Level