PR Commenter Plugin

A Buildkite plugin written in Go that enables commenting on pull requests that builds are triggered from.

The plugin uses the /issues endpoint as that doesn’t require a commit SHA or file name in order to post the comment; this comment will post to the conversation tab and won’t be associated with any file changes.

The plugin is built and tested with Go 1.26.10, which includes the eMudhra certificate verification fix. Use Go 1.26.10 or later in the 1.26 series, or 1.27.3 or later, on your agents when building the plugin.

The plugin binary will get built in the step and output as a pre-exit hook. This ensures that it runs as the last command on the step and is able to get the exit code of the step that it runs on (necessary for the default message).

The GitHub API token can be retrieved from a Buildkite Secret or read from an environment variable populated by an earlier hook or plugin. By default, the plugin retrieves the Buildkite Secret named GITHUB_TOKEN.

👩‍💻 Usage

The plugin expects at least one of BUILDKITE_STEP_KEY or BUILDKITE_LABEL to be set for proper usage.

Add the following to your pipeline.yml:

steps:
  - key: approval-comment
    command: 'echo "~~~ :github: Add approval comment Pull Request"'
    plugins:
      - pr-commenter#v0.5.0:
          message: "LGTM!"
          secret-name: GITHUB_TOKEN

Enabling “Sticky” comments

Set allow-repeats: false in order to post and update a single comment. This configuration relies on BUILDKITE_STEP_KEY or BUILDKITE_LABEL being set and unique to the step.

steps:
  - key: approval-comment
    command: 'echo "~~~ :github: Add approval comment Pull Request"'
    plugins:
      - pr-commenter#v0.5.0:
          message: "LGTM!"
          secret-name: GITHUB_TOKEN
          allow-repeats: false

📒 Options

secret-name (optional, string)

The Buildkite Secret containing the GitHub API token. It can be set to any Buildkite Secret name. If neither secret-name nor token-env is provided, it defaults to GITHUB_TOKEN. If no secret with that name exists, the plugin will error.

Default: GITHUB_TOKEN

token-env (optional, string)

The name of an environment variable containing the GitHub API token. This is useful when an earlier hook or plugin retrieves the token from an external secrets manager. The referenced variable must exist and contain a non-empty value when this plugin’s pre-exit hook runs.

token-env and secret-name are mutually exclusive within one plugin configuration. If neither is configured, the plugin retrieves the Buildkite Secret named GITHUB_TOKEN.

Do not put the token value itself in this option or in pipeline YAML; provide only the environment variable name. If the selected Buildkite Secret or environment variable cannot provide a token, the plugin’s pre-exit hook fails and the job will fail.

Using AWS SSM Parameter Store

The aws-ssm plugin exports parameters during its pre-command hook. The PR Commenter can read the resulting environment variable during pre-exit:

steps:
  - key: approval-comment
    command: 'echo "~~~ :github: Add approval comment Pull Request"'
    plugins:
      - aws-ssm#v1.1.0:
          parameters:
            PR_COMMENTER_GITHUB_TOKEN: /buildkite/github/pr-commenter-token
      - pr-commenter#v0.5.0:
          message: "LGTM!"
          token-env: PR_COMMENTER_GITHUB_TOKEN

The token is available to the job command and later hooks once it has been exported. Use a GitHub token with the minimum permissions required to comment on pull requests, and take particular care with builds originating from untrusted forks.

message (optional, string)

The message which should be posted to the PR. This can be a dynamic value, such as $BUILDKITE_COMMAND

Default: [${BUILDKITE_BUILD_URL}#${BUILDKITE_JOB_ID}](https://github.com/buildkite-plugins/pr-commenter-buildkite-plugin/blob/HEAD/${BUILDKITE_BUILD_URL}#${BUILDKITE_JOB_ID}) exited with code ${BUILDKITE_COMMAND_EXIT_STATUS}

allow-repeats (optional, boolean)

Whether to Allow identical comments to be posted every time the plugin is run. Disabling this (allow-repeats: false) will cause the plugin to post a single “sticky” comment, which will be updated on subsequent runs if the message changes.

Default: true

message-id (optional, string)

An additional unique identifier for the comment generated by the plugin instance; useful if using “sticky” comments (allow-repeats: false) and using the plugin multiple times in a single step.

Default: null

Compatibility

Elastic Stack	Agent Stack K8s	Hosted (Mac)	Hosted (Linux)	Notes
✅	⚠️	✅	✅	K8s: The go binary will need to be available on the agents

• ✅ Fully supported (all combinations of attributes have been tested to pass)
• ⚠️ Partially supported (some combinations cause errors/issues)

🛠️ Development

Running the tests

The tests are written using Go’s built-in testing package.

Tests can be run using:

go test -v ./...

💪 Contributing

We welcome all contributions to improve this plugin! To contribute, please follow these guidelines:

• Fork the repository
• Make your changes and ensure that the tests pass.
• Write clear and concise commit messages.
• Submit a pull request.

By contributing, you agree to license your contributions under the LICENSE file of this repository.

License

MIT (see LICENSE)