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#v1.2.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 (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 pipeline
• false: Does not compare a build to the previous build Default: false

Usage Examples

Compare against a branch:

steps:
  - plugins:
      - annotate-git-diff#v1.2.0:
          compare_branch: "main"

Compare against multiple previous commits:

steps:
  - plugins:
      - annotate-git-diff#v1.2.0:
          compare_commits: 3  # Shows changes in last 3 commits

Include submodule changes:

steps:
  - plugins:
      - annotate-git-diff#v1.2.0:
          compare_branch: "main"
          include_submodules: true

Compare a build to a previous build:

steps:
  - plugins:
      - annotate-git-diff#v1.2.0:
          compare_previous_build: true

Raw diff format:

steps:
  - plugins:
      - annotate-git-diff#v1.2.0:
          format: "diff"

Development

To run the tests:

docker-compose run --rm tests

License

MIT