1. Resources
  2. /
  3. Plugins
  4. /
  5. annotate-git-diff-buildkite-plugin

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

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

The plugins listed on this webpage are provided for informational purposes only. They have not undergone any formal security review or assessment. While we strive to provide useful resources, we cannot guarantee the safety, reliability, or integrity of these plugins. Users are strongly advised to conduct their own security evaluations before downloading, installing, or using any plugin. By using these plugins, you acknowledge and accept any risks associated with their use. We disclaim any liability for any harm or damages arising from the use of the plugins listed.

Start turning complexity into an advantage

Create an account to get started with a 30-day free trial. No credit card required.

Buildkite Pipelines

Platform

  1. Pipelines
  2. Public pipelines
  3. Test Engine
  4. Package Registries
  5. Mobile Delivery Cloud
  6. Pricing

Hosting options

  1. Self-hosted agents
  2. Mac hosted agents
  3. Linux hosted agents

Resources

  1. Docs
  2. Blog
  3. Changelog
  4. Example pipelines
  5. Plugins
  6. Webinars
  7. Case studies
  8. Events
  9. Migration Services
  10. Comparisons

Company

  1. About
  2. Careers
  3. Press
  4. Brand assets
  5. Contact

Solutions

  1. Replace Jenkins
  2. Workflows for AI/ML
  3. Testing at scale
  4. Monorepo mojo
  5. Bazel orchestration

Legal

  1. Terms of Service
  2. Acceptable Use Policy
  3. Privacy Policy
  4. Subprocessors
  5. Service Level Agreement

Support

  1. System status
  2. Forum
© Buildkite Pty Ltd 2025