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

To connect the integration, you must be the GitHub personal account owner or an active organization owner. Repository access or ordinary organization membership is not enough.
The Checkly GitHub integration connected 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.

Connect the installation from Account settings > Integrations in Checkly and grant the App 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, click Integrate with GitHub, then Continue with GitHub.
Authorize GitHub, choose a Checkly App installation you own, and click Connect. You can connect the same installation to multiple Checkly accounts.
If you need a new installation or different repository access, use Install on another GitHub account or Manage repository access. Return to Checkly, click Refresh, then Connect.
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.

GitHub account or organization missing

Only installations you own appear in the chooser. Click Use a different GitHub account to sign in as the personal account owner or an organization owner. If organization ownership cannot be verified, ask an organization owner to approve the Checkly App’s Members: read permission and authorize organization SSO, then authorize GitHub again.

Manage deployment hooks with the API

Use the Checkly Public API to create GitHub deployment hooks programmatically. A deployment trigger represents the link between one GitHub repository and either a check or a check group.

Create a deployment trigger for a check or check group. Repeating the request for the same target returns the existing trigger without changing its settings.
List deployment triggers for your account.

The API supports GitHub deployment triggers. To configure the Checkly Vercel integration, use the Vercel integration settings.

If you omit both deployment filters, every successful deployment reported for the repository can trigger a run, including production deployments. Set environmentRegexFilter or environmentUrlRegexFilter when you only want to run checks against specific environments.

You can use deployment environment URLs with API, URL, browser, and multi-step checks. API and URL checks replace the host in the configured request URL. Browser and multi-step checks receive the deployment URL through the ENVIRONMENT_URL environment variable. To change or remove a trigger created through the API, open the check or check group in Checkly and use its CI/CD settings.

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

GitHub account or organization missing

Manage deployment hooks with the API

Use deployment environment URLs

API checks & environment URLs

Browser checks & environment URLs

Limitations

​Set up GitHub deployment hooks

​GitHub account or organization missing

​Manage deployment hooks with the API

​Use deployment environment URLs

​API checks & environment URLs

​Browser checks & environment URLs

​Limitations

Set up GitHub deployment hooks

GitHub account or organization missing

Manage deployment hooks with the API

Use deployment environment URLs

API checks & environment URLs

Browser checks & environment URLs

Limitations