You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: "Trigger Checkly checks from GitHub deployment events fired by services like Vercel and Heroku, running against both preview and production deployments."
4
-
sidebarTitle: GitHub Deployments
2
+
title: GitHub deployment hooks
3
+
description: "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.
8
9
9
-
GitHub deployments are webhook events triggered by GitHub whenever a deployment service reports a successful deployment
10
-
event. This works out-of-the-box with the following services.
11
-
12
-
-[Vercel for GitHub](https://vercel.com/docs/v2/git-integrations/vercel-for-github)
Any (SaaS) service that interacts with the [GitHub deployments API](https://developer.github.com/v3/repos/deployments/) and
16
-
reports the correct "success" message will work, both with production and preview deployments.
10
+
<Accordiontitle="Prerequisites">
11
+
- 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.
12
+
- A deployment provider that sends successful GitHub `deployment_status` events, such as Vercel for GitHub or Heroku Pipelines.
13
+
- One or more Checkly checks linked to the GitHub repository from the check's **CI/CD** settings.
14
+
</Accordion>
17
15
18
16
<Warning>
19
-
This integration has some [known limitations](/integrations/ci-cd/github/deployments#limitations). We recommend using the [Checkly CLI](/cli/overview) in your CI/CD pipeline instead.
17
+
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.
20
18
</Warning>
21
19
22
-
## Setting up your GitHub integration
20
+
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:
23
21
24
-
1. Go to the **integrations tab** in your account settings and click the "Integrate with GitHub" button.
25
-
22
+
-[Vercel for GitHub](https://vercel.com/docs/v2/git-integrations/vercel-for-github)
- Other deployment services that use the [GitHub deployments API](https://docs.github.com/en/rest/deployments/deployments) and report successful deployment statuses.
26
25
27
-
2. You will be redirected to GitHub and prompted to select an account and install the Checkly GitHub App.
28
-
26
+
<Warning>
27
+
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.
28
+
</Warning>
29
29
30
-
3. When accepting the installation, you are redirected back to Checkly and the integration is installed.
31
-
Now, go to the **CI/CD tab** of the check you want to link to a GitHub repository. In Browser checks, this will be under "Change settings".
32
-
30
+
## Set up GitHub deployment hooks
33
31
34
-
4. Click the **"Link GitHub repo"** button and select the repository you want to link.
35
-
32
+
1. Go to [Account settings > Integrations](https://app.checklyhq.com/settings/account/integrations) and click **Integrate with GitHub**.
33
+
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.
34
+
3. Open the check or check group you want to trigger and go to its **CI/CD** settings.
35
+
4. Click **Link GitHub repo** and select the repository that reports your deployment events.
36
36
37
-
5. On each deployment event, we will run your check and report the results directly in **your GitHub timeline and PR overview**.
38
-
37
+
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.
39
38
40
-
6. You will also get an overview of the check result in the *details* section
41
-
42
-
43
-
> You can hook up multiple checks to the same repo. We will just run all of them as a test suite.
39
+
<Note>
40
+
You can link multiple checks to the same repository. Checkly runs the linked checks as a test suite when GitHub reports a successful deployment.
41
+
</Note>
44
42
45
-
## Using environment URLs
43
+
## Use deployment environment URLs
46
44
47
45
GitHub reports an **environment URL** on each deployment event. Depending on what deployment service you use,
48
46
this environment URL can be used to run your check on different target environments than configured in your check.
@@ -54,7 +52,7 @@ So, when you enable the **"Use environment URL from deployment trigger"** checkb
54
52
55
53
### API checks & environment URLs
56
54
57
-
With API checks, we replace the hostname part of your request url with the host in the environment URL.
55
+
With API checks, Checkly replaces the hostname part of your request URL with the host in the environment URL.
58
56
For example:
59
57
60
58
- Your configured URL: `https://api.acme.com/v1/customers?page=1`
@@ -68,7 +66,7 @@ Notice we only replace the **host** part, not the URL path or any query paramete
68
66
For browser checks, the environment URL is exposed as the `ENVIRONMENT_URL` environment variable. This means you can use that
69
67
variable in your code to replace any hardcoded URL you might have, i.e.:
70
68
71
-
<CodeGroupdropdown>
69
+
<CodeGroupdropdown={true}>
72
70
```typescript test.spec.ts
73
71
import { expect, test } from'@playwright/test'
74
72
@@ -92,18 +90,18 @@ test('assert response status of page', async ({ page }) => {
92
90
```
93
91
</CodeGroup>
94
92
95
-
This way we are setting the `targetUrl` variable to either the `ENVIRONMENT_URL` or just our main production URL.
93
+
This sets the `targetUrl` variable to either the `ENVIRONMENT_URL` or your main production URL.
96
94
97
-
Whenever a **Preview**deploy happens on GitHub, this check gets called and runs the script against the preview environment. This check also runs on a set interval, and checks our production environment.
95
+
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.
98
96
99
-
This way, we kill two birds with one stone and don't need separate checks for separate environments.
97
+
With one check, you can validate preview deployments from GitHub events and keep running the same check on your production schedule.
100
98
101
99
## Limitations
102
100
103
-
GitHub deployments lacks support for several features:
101
+
GitHub deployment hooks lack support for several features:
104
102
105
103
* Client certificates are not applied.
106
104
* OpenTelemetry integration headers are not applied.
107
105
* Private locations are not available.
108
106
109
-
As an alternative, we recommend using the [Checkly CLI](/cli/overview) in your CI/CD pipeline. The CLI is much more powerful and fully supported.
107
+
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.
0 commit comments