Git Diff Buildkite Plugin
A Buildkite plugin that shows git diff as a build annotation. You can compare against a target branch, a specific number of previous commits, include submodule changes, or compare a build against previous build.
Example
Add the following to your pipeline.yml:
steps:
- command: echo "Running with git diff..."
plugins:
- annotate-git-diff#v2.0.0:
context: "my-diff" # optional
format: "markdown" # optional (markdown|diff)
compare_branch: "main" # optional (defaults to comparing against previous commit)
compare_commits: 3 # optional (compare against 3 commits back, ignored if compare_branch is set)
include_merge_base: true # optional (defaults to true)
include_submodules: false # optional (defaults to false)
compare_previous_build: false # optional (true|false|passed_or_failed, defaults to false)
Configuration
context (optional)
The annotation context. Default: git-diff
format (optional)
The output format for the diff. Can be either markdown or diff. Default: markdown
compare_branch (optional)
The branch to compare against. If not set, will compare against previous commits based on compare_commits. Default: none
compare_commits (optional)
Number of commits to compare against when no branch is specified. Default: 1
include_merge_base (optional)
When comparing against a branch:
true: Compares against the common ancestor of the current commit and target branchfalse: Compares directly against the HEAD of the target branch Default:true
include_submodules (optional)
Whether to include submodule changes in the diff output.
true: Shows submodule changes in diff and includes them in statisticsfalse: Excludes submodule changes Default:false
max_body_bytes (optional)
Maximum size in bytes of the complete annotation body sent to buildkite-agent annotate. buildkite-agent enforces a hard limit of 1 MiB (1,048,576 bytes) per annotation body (source). When the diff would push the body over this cap the plugin truncates the output and appends a notice; in markdown format the notice lists the omitted files (truncated to ... and N more file(s) when even the list won’t fit), and in diff format the body is cut at a line boundary and marked with a trailing truncation line. Default: 1000000 (slightly under 1 MiB to leave headroom).
compare_previous_build (optional)
[!NOTE] Requires an API Access Token with
read_buildspermission to be available via the environment variable$BUILDKITE_API_TOKEN.
Whether to compare a build to the previous build. You’ll need to provide an API Access Token with read_builds permissions to run this check.
Only use this check as a standalone check, make sure to set other checks to false if you want to use the compare_previous_build check.
true: Shows changes between the last two successful builds on the current branchfalse: Does not compare a build to the previous buildpassed_or_failed: Shows changes between the last two builds on the current branch that either passed or failed. Blocked or canceled builds are excluded because the underlying API query only requestspassedandfailedbuilds.
[!NOTE] Only
true,false, andpassed_or_failedare accepted as ofv2.0.0. Boolean-like aliases such ason,off,1, or0aren’t supported — see Changelog. Any other value fails the step with an error annotation. (Case-insensitive matching only applies when run with--no-plugin-validation; normal pipeline validation requires the exact lowercase string.)
Default: false
Usage Examples
Compare against a branch:
steps:
- plugins:
- annotate-git-diff#v2.0.0:
compare_branch: "main"
Compare against multiple previous commits:
steps:
- plugins:
- annotate-git-diff#v2.0.0:
compare_commits: 3 # Shows changes in last 3 commits
Include submodule changes:
steps:
- plugins:
- annotate-git-diff#v2.0.0:
compare_branch: "main"
include_submodules: true
Compare a build to a previous build:
steps:
- plugins:
- annotate-git-diff#v2.0.0:
compare_previous_build: true
Compare a build to the previous passed or failed build:
steps:
- plugins:
- annotate-git-diff#v2.0.0:
compare_previous_build: passed_or_failed
Raw diff format:
steps:
- plugins:
- annotate-git-diff#v2.0.0:
format: "diff"
Changelog
v2.0.0
- Breaking:
compare_previous_buildnow scopes the lookup to the current branch (BUILDKITE_BRANCH) by default. Previously it compared against the most recent passed build on the pipeline regardless of branch; it now compares against the most recent matching build on the same branch.BUILDKITE_BRANCHis required to be set whencompare_previous_buildis enabled. - Breaking:
compare_previous_buildonly acceptstrue,false, andpassed_or_failed(the hook matches case-insensitively, but under normal pipeline validationplugin.ymlonly allows the exact lowercase string — case-insensitive matching only takes effect with--no-plugin-validation). Alias values such ason,off,1, or0aren’t supported — passing one of these fails the step with an error annotation rather than being treated as enabled/disabled.
Development
To run the tests:
docker-compose run --rm tests
License
MIT