GitHub deployment hooks

Use GitHub deployment hooks when you want Checkly to listen for GitHub deployment_status events and trigger checks linked to a repository. This is separate from the Checkly GitHub Action, which starts test sessions from a GitHub Actions workflow.

Prerequisites

The Checkly GitHub integration installed from the Account settings > Integrations page of the Checkly account that owns the checks.
A deployment provider that sends successful GitHub deployment_status events, such as Vercel for GitHub or Heroku Pipelines.
One or more Checkly checks linked to the GitHub repository from the check’s CI/CD settings.

Start the installation from Account settings > Integrations in Checkly and click Integrate with GitHub. Grant the installation access to the repository you want to link. Installing the app directly from GitHub does not connect it to the Checkly account, so deployment hooks and GitHub Check reporting will not work correctly.

GitHub deployment_status webhook events are triggered whenever a deployment service reports a successful deployment. This works with services that report successful deployment statuses through the GitHub Deployments API, including:

Vercel for GitHub
Heroku Pipelines
Other deployment services that use the GitHub deployments API and report successful deployment statuses.

This integration has some known limitations. Use the Checkly GitHub Action when you want GitHub Actions to start a recorded test session and report the result on a pull request.

Set up GitHub deployment hooks

Go to Account settings > Integrations and click Integrate with GitHub.
In GitHub, choose the account where you want to install the Checkly GitHub App and grant it access to the repositories you want to connect. After installation, GitHub redirects you to Checkly.
Open the check or check group you want to trigger and go to its CI/CD settings.
Click Link GitHub repo and select the repository that reports your deployment events.

After you link the repository, Checkly listens for successful deployment events and runs the linked check or check group. You can also choose a run location, filter deployments by environment or environment URL, and include screenshots in the pull request comment.

You can link multiple checks to the same repository. Checkly runs the linked checks as a test suite when GitHub reports a successful deployment.

Use deployment environment URLs

GitHub reports an environment URL on each deployment event. Depending on what deployment service you use, this environment URL can be used to run your check on different target environments than configured in your check. The primary use case for this is validating temporary review/branch deployments, such as those provided by Vercel and Heroku Pipelines, before going to production. So, when you enable the “Use environment URL from deployment trigger” checkbox there are two scenarios:

API checks & environment URLs

With API checks, Checkly replaces the hostname part of your request URL with the host in the environment URL. For example:

Your configured URL: https://api.acme.com/v1/customers?page=1
Environment URL: https://now.customer-api.qis6va2z7.now.sh
Replaced URL: https://now.customer-api.qis6va2z7.now.sh/v1/customers?page=1

Notice we only replace the host part, not the URL path or any query parameters.

Browser checks & environment URLs

For browser checks, the environment URL is exposed as the ENVIRONMENT_URL environment variable. This means you can use that variable in your code to replace any hardcoded URL you might have, i.e.:

test.spec.ts

import { expect, test } from '@playwright/test'

test('assert response status of page', async ({ page }) => {
  const targetUrl = process.env.ENVIRONMENT_URL || 'https://www.checklyhq.com'
  const response = await page.goto(targetUrl)

  expect(response.status()).toBeLessThan(400)
})

const { expect, test } = require('@playwright/test')

test('assert response status of page', async ({ page }) => {
  const targetUrl = process.env.ENVIRONMENT_URL || 'https://www.checklyhq.com'
  const response = await page.goto(targetUrl)

  expect(response.status()).toBeLessThan(400)
})

This sets the targetUrl variable to either the ENVIRONMENT_URL or your main production URL. When a Preview deployment happens on GitHub, this check runs the script against the preview environment. This check also runs on a set interval and checks your production environment. With one check, you can validate preview deployments from GitHub events and keep running the same check on your production schedule.

Limitations

GitHub deployment hooks lack support for several features:

Client certificates are not applied.
OpenTelemetry integration headers are not applied.
Private locations are not available.

Use the Checkly GitHub Action or the Checkly CLI in your CI/CD pipeline when you need these features.

Getting Started

Detect

Communicate

Resolve

AI

Integrations

GitHub deployment hooks

Set up GitHub deployment hooks

Use deployment environment URLs

API checks & environment URLs

Browser checks & environment URLs

Limitations

​Set up GitHub deployment hooks

​Use deployment environment URLs

​API checks & environment URLs

​Browser checks & environment URLs

​Limitations

Set up GitHub deployment hooks

Use deployment environment URLs

API checks & environment URLs

Browser checks & environment URLs

Limitations