1. Documentation
  2. Integrations
  3. Git Providers
  4. GitHub

GitHub Requires Production

GitHub is a Git repository management and hosting platform for companies, individuals, and Open-Source projects to collaborate, track bugs, and review code.

Integrating Blackfire with GitHub enables you to automate the performance testing of your code any time you modify it.

Triggering Scenarios on Deployed Environments

The expected workflow is as follows:

  1. A developer in your team creates a Pull Request;
  2. The Pull Request is automatically deployed;
  3. Your toolchain triggers Blackfire to run your scenarios;
  4. Blackfire sends a notification to GitHub that is displayed as a commit status on the corresponding Pull Request.

Caution

The following options require that Backfire can reach the HTTP server serving the pull request version of the code.

Tip

Some PaaS, like Platform.sh have built-in support for automatically deploying Pull Requests and triggerring Blackfire scenarios.

If your toolchain enables you to deploy your code automatically for each new Pull Request, create a webhook payload that you will use (for instance with Jenkins, Travis,…) to let Blackfire run the test scenarios.

Please read the builds webhook documentation to configure them.

To make sure that GitHub can receive a notification back from Blackfire, please configure the following parameters:

endpoint (Mandatory) The endpoint to profile
title (Optional) A title for the build (e.g .the Pull Request reference or title)
external_id (Mandatory) The Git commit hash of the tip of the pull request
external_parent_id (Optional) The Git commit hash of the parent build. This is typically the hash of the pull-request base branch

The external_id makes it possible for Blackfire to point the build report notification to the correct commit. The external_parent_id makes it possible for you to write comparison assertions.

Note

The Git commit hashes passed to external_id and external_parent_id must not be truncated.

Example:

  • Valid commit hash: 61c9b1b59340c44057635d24fb4d9c05842f4056
  • Invalid commit hash: 61c9b1b

Triggering Scenarios on Non-Deployed Code

Blackfire’s PHP SDK enables you to test the performance of your code without deploying it. You will need to configure it to:

Setting up the GitHub Notification Channel

Anytime a build report is available, the GitHub notification channel updates the commit status on the corresponding Pull Request.

Note

You must make sure to create the webhook payload like described above.

To configure a GitHub notification channel:

  • Go to your settings on GitHub to create a new personal access token, and grant it the repo:status scope;
  • Go to the Dashboard Build tab of the related Blackfire environment and look for the Notification Channel section;
  • Add a new GitHub notification channel. The configuration requires the repository name (like username/project-name) and the GitHub Token to be able to post build statuses on pull requests.