Calibre’s GitHub application automatically sets up Pull Request Reviews. It allows checking the performance impact of development work before it gets released to your customers by posting a customisable speed report directly in a Pull Request. This article covers how to connect Calibre to your GitHub organisation and configure the integration.
Calibre will detect repository deployments using GitHub deployment statuses. Vercel, Netlify, Heroku and other hosting platforms create GitHub deployment statuses automatically.
Each deployment must have a unique hostname (e.g.: my-preview-url-123.example.com in order to use Pull Request reviews.
To enable the GitHub integration, go to Site → Settings → Integrations tab and click Add to a repository in the GitHub section. You will be redirected to GitHub to enable the integration for your organisation.
Calibre requires access to commit statuses, deployments, checks, comments and pull requests. We strongly recommend granting access to any selected repositories you’re interested in tracking.
After confirming the link between GitHub and Calibre, you will have to select a primary branch that will be the base for performance comparisons. This branch should be either deploying to production or a staging environment. In most cases, this might be main branch.
For the most accurate results, make sure you compare two very similar environments. Some of the common differentiators producing unreliable results can be using a CDN on production, but not on Pull Request deployments, or the presence of ads or other third parties.
Calibre will create Pull Request Review tests from any GitHub deployment status. If your repository is deploying to several environments in Pull Requests (e.g. in monorepo scenarios or when both Site and a Storybook preview is created), choose one of the following options:
If your repository generates several deployment environments, specify one to be used as a comparison source for Pull Request Reviews to avoid errors in reporting. If you are using Vercel, specify both the preview and production deployment environment.
You can also select or ignore specific branches from your testing.
If you are using Performance Budgets, you can opt in to fail Pull Request checks when a Budget is exceeded. The Calibre budget check will fail if an existing Budget for a Site is currently met on production, but newly failing in the tested Pull Request.
Calibre will compare each Pull Request to the median of site metrics since the last deploy. Each report highlights changes in Web Vitals and assets transferred:
You can also check if any Budgets changed status:
Pull Request Reviews provide a helpful performance overview directly in GitHub, with the ability to drill down into metrics further in the Calibre interface.
Calibre does not automatically test draft Pull Requests. Test Draft Pull Requests by marking them as Ready for Review or using a Pull Request command. You can also re-run a Pull Request Review by closing and re-opening your Pull Request.
When your Pull Request is merged and selected branch is successfully deployed, Calibre creates a deployment marker on your charts and takes a new snapshot of your Site. That way, you always know how releases affect your performance metrics.
If you’re using Netlify, make sure to enable the Netlify integration first, so the deployment markers show on your charts.
You can control Calibre actions by commenting on a PR, too:
Your repository has to be using GitHub deployment statuses, so Calibre knows what to compare Pull Requests to. Providers such as Vercel, Netlify and Heroku provide these automatically.
If you have a custom CI pipeline, you can mark deployments and create deployment statuses using the GitHub API. Calibre creates a Pull Request Review Site when it receives a deployment status with a state of success. Make sure to set the canonical URL of your review Site in the environment_url field.
You can include or exclude branches that Calibre runs Pull Request Reviews on by setting the deployment branches using positive and negative patterns.
The order branch patterns are defined matters. The last matching pattern will determine if the branch is included or excluded.
Set the Deployment Branches field to: dependabot/**:
Set the Deployment Branches field to: !*. You can trigger Calibre actions by using the Pull Request Command @calibreapp run.
Set the Deployment Branches field to: releases/**, releases/**-alpha.
For detailed configuration options including authentication, headers, cookies, and branch-specific settings, see the Pull Request Review Configuration page and create a .calibre/config.yml file in your repository.
Calibre will automatically source the configuration file for each Pull Request Review.
To use Pull Request Reviews, the following API access to your GitHub respository is required:
In addition to these API items, Calibre will also read the following events for authorised repositories:
Your team authorises access during installation and will be prompted to confirm any changes in access requirements.
If you have any questions or concerns, let us know at security@calibreapp.com.
On this page