Pull Request Review Configuration

Advanced configuration for Pull Request Reviews can be set using a .calibre/config.yml file. This configuration file allows you to customize authentication, headers, cookies, and branch-specific settings.

Configuration file structure#

There are two top-level properties you must specify:

  • version: The current version is 2
  • pullRequestReviews: Options for Pull Request Reviews

Version#

There are two versions of the Calibre configuration file.

  • Version 1: Single configuration block (Deprecated)
  • Version 2: Supports multiples blocks of configuration which can be used for branch specific configuration.

You can set the version by specifying the version number as the value of the version key:

Version 2
version: 2
pullRequestReviews:

Authentication configuration#

Calibre will automatically copy authentication settings from each Site 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. This is helpful when your Pull Request environment has different authentication than the main Site.

Define authentication settings#

The following configuration will be used for authentication:

version: 2
pullRequestReviews:
  - authentication:
      url: https://different-domain.com/login
      username: user@email.com
      password: mysecretpassword
      formSelector: form
      usernameSelector: input[name=email]
      passwordSelector: input[type=password]

Password only settings#

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:

version: 2
pullRequestReviews:
  - authentication:
      password: mysecretpassword
      passwordSelector: input[type=password]

Headers and cookies#

You can specify headers and cookies for each Pull Request Review test.

Caution

Test Profiles can override cookies and headers set in Pull Request Review configuration. Calibre applies cookies and headers in the following order: Test Profile cookies and headers, Cookies and headers set in .calibre/config.yml, then Test Agent cookies and headers.

Version 2
version: 2
pullRequestReviews:
  # Headers
  - headers:
      - name: X-Calibre-Test
        value: Pull Request
      - name: User-Agent
        value: Calibre

  # Cookies
  - cookies:
      - name: seen-cookie-notice
        value: true
      - name: uid
        value: 1
        domain: calibreapp.com
        path: /
        secure: true
        httpOnly: true

  # Specify headers and cookies for branches prefixed with `stage-`
  - headers:
      - name: X-Environment
        value: staging
    cookies:
      - name: staging-cookie
        value: true
    branches:
      - stage-*

Branch specific configuration#

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.

Disable authentication for a preview branch#

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.

Version 2
version: 2
pullRequestReviews:
  - branches:
      - preview-*
    authentication:
      password: mysecretpassword
      formSelector: form
      passwordSelector: input[type=password]
      required: true
  - branches:
      - preview-public
    authentication:
      required: false

Complete configuration example#

Here's a comprehensive example showing all available configuration options:

Complete example
version: 2
pullRequestReviews:
  # Default configuration for all branches
  - authentication:
      url: https://auth.example.com/login
      username: test@example.com
      password: secretpassword
      formSelector: form.login
      usernameSelector: input[name=email]
      passwordSelector: input[type=password]
      required: true
    headers:
      - name: X-Environment
        value: preview
      - name: Authorization
        value: Bearer token123
    cookies:
      - name: session-id
        value: abc123
        domain: example.com
        path: /
        secure: true
        httpOnly: true

  # Configuration for staging branches
  - branches:
      - staging/*
      - stage-*
    authentication:
      password: stagingpassword
      passwordSelector: input[type=password]
    headers:
      - name: X-Environment
        value: staging
    cookies:
      - name: staging-mode
        value: true

  # Configuration for public preview branches (no auth required)
  - branches:
      - public-*
    authentication:
      required: false
    headers:
      - name: X-Environment
        value: public-preview

On this page