> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-herve-eng-22-telegram-group-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub deployment hooks

> Trigger linked Checkly checks from GitHub deployment events and use deployment environment URLs as test targets.

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](/integrations/ci-cd/github/actions), which starts test sessions from a GitHub Actions workflow.

<Accordion title="Prerequisites">
  * The Checkly GitHub integration installed from the [Account settings > Integrations](https://app.checklyhq.com/settings/account/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.
</Accordion>

<Warning>
  Start the installation from [Account settings > Integrations](https://app.checklyhq.com/settings/account/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.
</Warning>

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](https://vercel.com/docs/v2/git-integrations/vercel-for-github)
* [Heroku Pipelines](https://devcenter.heroku.com/articles/pipelines)
* Other deployment services that use the [GitHub deployments API](https://docs.github.com/en/rest/deployments/deployments) and report successful deployment statuses.

<Warning>
  This integration has some [known limitations](/integrations/ci-cd/github/deployments#limitations). Use the [Checkly GitHub Action](/integrations/ci-cd/github/actions) when you want GitHub Actions to start a recorded test session and report the result on a pull request.
</Warning>

## Set up GitHub deployment hooks

1. Go to [Account settings > Integrations](https://app.checklyhq.com/settings/account/integrations) and click **Integrate with GitHub**.
2. 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.
3. Open the check or check group you want to trigger and go to its **CI/CD** settings.
4. 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.

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

## 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.:

<CodeGroup dropdown={true}>
  ```typescript test.spec.ts theme={null}
  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)
  })
  ```

  ```javascript test.spec.js theme={null}
  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)
  })
  ```
</CodeGroup>

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](/integrations/ci-cd/github/actions) or the [Checkly CLI](/cli/overview) in your CI/CD pipeline when you need these features.