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 branch
• false: 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 statistics
• false: 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_builds permission 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 branch
• false: Does not compare a build to the previous build
• passed_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 requests passed and failed builds.

Note

Only true, false, and passed_or_failed are accepted as of v2.0.0. Boolean-like aliases such as on, off, 1, or 0 aren'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_build now 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_BRANCH is required to be set when compare_previous_build is enabled.
• Breaking: compare_previous_build only accepts true, false, and passed_or_failed (the hook matches case-insensitively, but under normal pipeline validation plugin.yml only allows the exact lowercase string — case-insensitive matching only takes effect with --no-plugin-validation). Alias values such as on, off, 1, or 0 aren'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