Pull Request Reviews allow you to see the performance impact of development work before it gets released to your customers. It’s a powerful GitHub integration that works with most popular deployment platforms.
To enable Pull Request Reviews, 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:
You can also select or ignore specific branches from your testing.
Calibre will compare each Pull Request to the median of your site metrics since the last deploy. Each report highlights critical measurements (Largest Contentful Paint, Cumulative Layout Shift and Total Blocking Time) overall and across Test Profiles to highlight top-level changes.
You can also analyse each page to see browser previews for specific Test Profiles and most significant changes, including any Budgets that have changed.
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.
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.
You can customise metrics and authentication settings by including a configuration YAML file in your linked repository at /.calibre/config.yml.
There are two top-level properties you must specify:
There are two versions of the Calibre configuration file.
You can set the version by specifying the version number as the value of the version key:
1version: 22pullRequestReviews:
1version: 12pullRequestReviews:
By default, Calibre will compare the following metrics:
Metric type | Metric name |
---|---|
Paint | Largest Contentful Paint |
Paint | Cumulative Layout Shift |
Runtime | Total Blocking Time |
Lighthouse Score | Lighthouse Performance Score |
Paint | First Contentful Paint |
Paint | First Meaningful Paint |
Paint | Speed Index |
Runtime | Time to Interactive |
Runtime | JS Parse & Compile |
Request | Total page transferred |
Request | Total HTML transferred |
Request | Total Image transferred |
Request | Total Video transferred |
Request | Total Font transferred |
Request | Total JSON transferred |
Request | Total CSS transferred |
Request | Total JavaScript transferred |
Request | Number of requests (Asset Count) |
Under pullRequestReviews in your configuration file you can explicitly define which metrics to use, or you can provide a list of metrics to ignore from all available metrics in Calibre.
When you define metrics, the first three will be shown in the summary table.
The following configuration will only compare the metrics listed under measurements:
1version: 22pullRequestReviews:3 - measurements:4 - firstRender5 - assetCount6 - pageSizeInBytes7 - lighthousePerformanceScore
1version: 12pullRequestReviews:3 measurements:4 - lighthousePerformanceScore5 - lighthouseAccessibilityScore6 - lighthouseSEOScore
The following configuration will include all metrics except the ones listed under ignore:
1version: 22pullRequestReviews:3 - ignore:4 - lighthousePwaScore5 - pageHTMLDownload6 - timeToFirstByte7 - lighthouseSeoScore8 - pageWaitTiming
1version: 12pullRequestReviews:3 ignore:4 - lighthousePwaScore5 - pageHTMLDownload6 - timeToFirstByte7 - lighthouseSeoScore8 - pageWaitTiming
Calibre will copy authentication settings to each Pull Request Review test. The authentication URL will be updated to use the same host as the pull request deployment.
If you require specific authentication details for Pull Request Reviews, you can set them using config.yml.
The following configuration will be used for authentication:
1version: 22pullRequestReviews:3 - authentication:4 url: https://different-domain.com/login5 username: user@email.com6 password: mysecretpassword7 formSelector: form8 usernameSelector: input[name=email]9 passwordSelector: input[type=password]
1version: 12pullRequestReviews:3 authentication:4 url: https://different-domain.com/login5 username: user@email.com6 password: mysecretpassword7 formSelector: form8 usernameSelector: input[name=email]9 passwordSelector: input[type=password]
Providers like Netlify and Vercel have the option to password protect preview deployments. By omitting the authentication URL and only setting the password fields, the Calibre Agent will login to the deployment URL with a password before each Snapshot:
1version: 22pullRequestReviews:3 - authentication:4 password: mysecretpassword5 passwordSelector: input[type=password]
1version: 12pullRequestReviews:3 authentication:4 password: mysecretpassword5 passwordSelector: input[type=password]
You can specify headers and cookies for each Pull Request Review test.
.calibre/config.yml
, then Test Agent cookies and headers.1version: 22pullRequestReviews:3 # Headers4 - headers:5 - name: X-Calibre-Test6 value: Pull Request7 - name: User-Agent8 value: Calibre910 # Cookies11 - cookies:12 - name: seen-cookie-notice13 value: true14 - name: uid15 value: 116 domain: calibreapp.com17 path: /18 secure: true19 httpOnly: true2021 # Specify headers and cookies for branches prefixed with `stage-`22 - headers:23 - name: X-Environment24 value: staging25 cookies:26 - name: staging-cookie27 value: true28 branches:29 - stage-*
You can specify configuration blocks for different 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.
The following configuration will apply authentication settings for all preview- branches except for preview-public as the last matching pattern for this branch does not require authentication.
1version: 22pullRequestReviews:3 - branches:4 - preview-*5 authentication:6 password: mysecretpassword7 formSelector: form8 passwordSelector: input[type=password]9 required: true10 - branches:11 - preview-public12 authentication:13 required: false
The following configuration will report on a different set of metrics for devops and ui branches:
1version: 22pullRequestReviews:3 - branches:4 - devops-*5 measurements:6 - timeToFirstByte7 - pageWaitTiming8 - pageHTMLDNS9 - branches:10 - ui-*11 measurements:12 - largestContentfulPaint13 - totalBlockingTime14 - lighthousePerformanceScore
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.