GitHub integration

sbt-hood can also output comparison results to a GitHub pull request as comments, as well as setting mergeability states. This allows you to set up the plugin within your CI pipelines and avoid merging code that decreases your performance under the thresholds you’ve specified to the plugin.

In order to allow sbt-hood to communicate with GitHub you’ll need to set these additional settings:

  • token: GitHub access token. It can be generated by browsing to Developer settings > Personal access tokens within your user settings.
  • repositoryOwner: owner of the repository where the plugin will post updates.
  • repositoryName: name of the repository where the plugin will post updates.
  • pullRequestNumber: pull request number where the plugin will post updates.
  • targetUrl: optional URL to the CI job, allowing GitHub to show a link to your CI job besides the mergeability status (i.e.: TRAVIS_JOB_WEB_URL under TravisCI).
  • shouldBlockMerge: if set to true, sbt-hood will ask GitHub to block the current PR in case a benchmark has produced errors. Defaults to true.

Once these are set up, you can configure your CI scripts to call the following sbt-hood command:

compareBenchmarksCI

This command runs the previously described compareBenchmarks command (thus showing the comparison results in your CI job logs), and later sends a request to GitHub API to create a state for your pull request. Any comparison resulting in an error for any of your benchmarks will create an erroneous state in your pull request, thus disallowing mergeability until these are taken care of.

By fine tuning the different settings of the plugin within your CI pipelines you can make sure that your applications stay performant during every code iteration.

Uploading benchmark reports to GitHub

In addition to controlling the state of your pull requests, sbt-hood provides an additional task that allows uploading benchmark report files (generated by compareBenchmarks and compareBenchmarksCI, provided that outputToFile is set to true). To allow sbt-hood to upload your reports, the following settings are available (take into account that the previously described GitHub settings are also required for uploads to work):

  • benchmarkFiles: list of files to be uploaded. By default it contains an empty list (in this case, uploading to GitHub will fail).
  • uploadDirectory: target path in your repository to upload the benchmark report files. By default it’s set to benchmarks.
  • commitMessage: each time benchmark reports are uploaded, a new commit will be push to your repository.
  • branch: target branch in your repository to upload the benchmark report files. By default it’s set to master.

Once configured you can set up your CI to upload your report files by calling the following command:

uploadBenchmarks

By keeping these reports in your repository you can track the performance of key aspects of your code as it continues to evolve.