Branch Commit Buildkite Plugin

Warning

This plugin is deprecated. Commit verification is now supported natively by the Buildkite Agent via the checkout.commit_verification attribute on command steps, which supports the same strict and warn modes.

Please migrate to the native functionality instead of using this plugin. Native commit verification requires Buildkite agent v3.136.0 or later. See Commit verification and Migrating from checkout plugins.

Native equivalent:

steps:
  - label: ":pipeline:"
    command: buildkite-agent pipeline upload
    checkout:
      commit_verification: strict

A Buildkite plugin that verifies the build commit exists on the specified branch. Designed for UI-triggered builds where a user may select a commit that doesn't belong to the target branch.

The plugin only runs when BUILDKITE_SOURCE is ui. For all other build sources it exits immediately.

Options

Optional

mode (string)

Controls what happens when the commit is not found on the branch. Defaults to strict.

• warn — logs a warning and continues the build
• strict — fails the build with an error

Examples

In warn mode:

steps:
  - label: ":pipeline:"
    command: buildkite-agent pipeline upload
    plugins:
      - branch-commit#v1.0.0:
          mode: "warn"

In strict mode (the default — mode can be omitted):

steps:
  - label: ":pipeline:"
    command: buildkite-agent pipeline upload
    plugins:
      - branch-commit#v1.0.0:
          mode: "strict"

Shallow clones

When the repository is a shallow clone (e.g., when using the sparse-checkout plugin), the plugin runs git fetch --unshallow to retrieve enough commit history for ancestry validation. In partial clone environments (--filter=blob:none), this only downloads commit metadata and is inexpensive. In non-partial shallow clones, this downloads the full repository history, which may be slow on large repositories.

Developing

Run tests locally:

docker run -it --rm -v "$PWD:/plugin:ro" buildkite/plugin-tester

Run shellcheck:

docker run --rm -v "$PWD:/mnt" --workdir "/mnt" koalaman/shellcheck:stable hooks/* lib/*.bash

Validate plugin structure:

docker run -it --rm -v "$PWD:/plugin:ro" buildkite/plugin-linter --id branch-commit --path /plugin

Contributing

1. Fork the repository and create a feature branch
2. Add tests for any new functionality
3. Ensure all tests pass and shellcheck reports no warnings
4. Open a pull request

License

The package is available as open source under the terms of the MIT License.