Run Checkly from GitHub Actions

Use the Checkly GitHub Action to run Monitoring as Code constructs from a repository or trigger checks already deployed to Checkly. The Action uses the Checkly CLI and can report the resulting test session through the GitHub Actions job or a separate GitHub Check.

Prerequisites

A GitHub repository with GitHub Actions enabled.
A Checkly project that uses Checkly CLI 8.15.0 or newer.
CHECKLY_API_KEY stored as a GitHub Actions secret.
CHECKLY_ACCOUNT_ID stored as a GitHub Actions variable. Account IDs do not need to be secrets.
For detached GitHub Check reporting, the Checkly GitHub App connected to the same Checkly account and granted access to the repository.

Install the GitHub App from the Checkly account that will run the test session. Go to Account settings > Integrations, click Integrate with GitHub, and grant the installation access to the repository. Installing the app directly from its GitHub listing does not connect the installation to your Checkly account.

Run checks on pull requests

Use this workflow when your Checkly constructs are defined in the repository:

.github/workflows/checkly.yml

name: Checkly

on:
  pull_request:

jobs:
  checkly:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: checkly/checkly-action@v1
        with:
          command: test
          cli-version: latest
          install-command: npm ci
          reporting: auto
        env:
          CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
          CHECKLY_ACCOUNT_ID: ${{ vars.CHECKLY_ACCOUNT_ID }}

The checkout step makes the pull request’s constructs and project dependencies available to the Action. With reporting: auto, the Action uses a detached GitHub Check when it is available. Otherwise, the workflow waits for the test session and reports the result through the GitHub Actions job.

Choose what to run

The command input selects the source of the checks:

Command	What it runs
`test`	Constructs from the checked-out repository. Use this to validate pull request changes before deploying them to Checkly.
`trigger`	Checks that are already deployed to the Checkly account. It does not load or test pull request-local constructs.

For test, use tags, grep, or files to select repository constructs:

with:
  command: test
  tags: |
    production,webapp
    production,api
  grep: checkout
  files: |
    __checks__/**/*.check.ts

Each tags line creates a separate --tags filter. Comma-separated tags on one line must all match. For trigger, select deployed checks with tags or check IDs:

.github/workflows/checkly-trigger.yml

name: Checkly trigger

on:
  workflow_dispatch:

jobs:
  checkly:
    runs-on: ubuntu-latest
    steps:
      - uses: checkly/checkly-action@v1
        with:
          command: trigger
          cli-version: latest
          reporting: auto
          tags: production
        env:
          CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
          CHECKLY_ACCOUNT_ID: ${{ vars.CHECKLY_ACCOUNT_ID }}

Choose a reporting mode

The reporting input controls whether the workflow waits for the Checkly test session:

Value	Behavior
`auto`	Use a detached Checkly run and external GitHub Check when available. Otherwise, wait and report through the GitHub Actions job. This is the default.
`github-check`	Require detached GitHub Check reporting. The Action fails preflight before running checks when the Checkly GitHub App cannot report to the repository.
`github-actions`	Always wait for the test session. The workflow job carries the result and the Action writes the Checkly report to the job summary.

Detached reporting produces two separate GitHub Check Runs: the GitHub Actions job and the external Checkly GitHub Check. The workflow job can finish successfully after starting the detached test session while the external Checkly GitHub Check is still running. Use github-check-name to set the external GitHub Check Run name. It defaults to Checkly; it is not the name of a Checkly check.

with:
  command: test
  reporting: github-check
  github-check-name: Checkly PR validation

A GitHub Actions job Check Run, an external Checkly GitHub Check Run, and a Checkly check are different objects. The Action does not publish a legacy commit status. The Checkly test session contains the execution results behind either reporting mode.

Resolve the CLI and dependencies

The Action requires Checkly CLI 8.15.0 or newer. Use cli-version: latest unless you need to test against a specific stable release. The Action resolves the CLI after running install-command inside working-directory:

If the project installs the checkly package, the Action uses that local CLI so the CLI and imported constructs share the same module installation.
Otherwise, the Action runs npx checkly@<cli-version>.

Keep the project’s checkly dependency at 8.15.0 or newer. If you use an exact stable cli-version, it must match the locally installed Checkly version. In a monorepo, working-directory selects where the Action resolves the config, dependencies, and CLI. When dependencies install from the repository root, install them before invoking the Action:

.github/workflows/checkly-monorepo.yml

name: Checkly webapp

on:
  pull_request:

jobs:
  checkly:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - run: npm ci

      - uses: checkly/checkly-action@v1
        with:
          command: test
          cli-version: latest
          working-directory: apps/webapp
          reporting: auto
        env:
          CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
          CHECKLY_ACCOUNT_ID: ${{ vars.CHECKLY_ACCOUNT_ID }}

If the target directory has its own package manifest and lockfile, use install-command instead. The command runs inside working-directory before the Action resolves the local CLI.

Report to the correct commit

GitHub Check Runs attach to commits. By default, the Action uses:

Event	Default commit
`pull_request` or `pull_request_target`	The pull request head SHA.
Any other event	`GITHUB_SHA`.

Set github-sha when the commit you check out and test differs from that default. This commonly applies to repository_dispatch and deployment workflows. Use the same SHA for checkout and Check reporting:

.github/workflows/checkly-preview-dispatch.yml

name: Validate preview

on:
  repository_dispatch:
    types: [preview-ready]

jobs:
  checkly:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.client_payload.sha }}

      - uses: checkly/checkly-action@v1
        with:
          command: test
          cli-version: latest
          install-command: npm ci
          reporting: auto
          github-sha: ${{ github.event.client_payload.sha }}
          github-check-name: Checkly preview validation
        env:
          CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
          CHECKLY_ACCOUNT_ID: ${{ vars.CHECKLY_ACCOUNT_ID }}
          ENVIRONMENT_URL: ${{ github.event.client_payload.environment_url }}

The commit must belong to the current repository. github-sha only selects the commit that receives the external Check; it does not grant repository access. Checkly still verifies that the GitHub App installation for the Checkly account can access the repository.

Test preview deployments

Pull request and custom-dispatch workflows usually need to pass their preview URL explicitly as ENVIRONMENT_URL, as shown in the repository_dispatch example above. For deployment_status events, the Action automatically exposes github.event.deployment_status.environment_url as ENVIRONMENT_URL when the workflow has not already set it. GitHub sets GITHUB_SHA to the commit being deployed, so the Action can normally use its default commit metadata:

.github/workflows/checkly-deployment.yml

name: Validate deployment

on:
  deployment_status:

jobs:
  checkly:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: checkly/checkly-action@v1
        with:
          command: test
          cli-version: latest
          install-command: npm ci
          reporting: auto
        env:
          CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
          CHECKLY_ACCOUNT_ID: ${{ vars.CHECKLY_ACCOUNT_ID }}

If a custom deployment workflow checks out a commit from an event payload instead of GITHUB_SHA, pass that same commit through github-sha. If you want Checkly itself to listen for GitHub deployment events and trigger checks linked to a repository, use GitHub deployment hooks instead of this workflow.

Protect merges with detached checks

When you use detached reporting, require the external Checkly GitHub Check in your branch rules. Requiring only the GitHub Actions job does not wait for the external Checkly test session to finish.

Configure the exact github-check-name as a required check. If the workflow uses path filters, make sure it still creates the required Checkly Check for every pull request commit. Prefer Action inputs such as files, grep, or tags when you need to select a smaller test set.

Next steps

Learn more about checkly test.
Learn more about checkly trigger.
Use GitHub deployment hooks when you want Checkly to react directly to GitHub deployment events.

Getting Started

Detect

Communicate

Resolve

AI

Integrations

Run Checkly from GitHub Actions

Run checks on pull requests

Choose what to run

Choose a reporting mode

Resolve the CLI and dependencies

Report to the correct commit

Test preview deployments

Protect merges with detached checks

Next steps

​Run checks on pull requests

​Choose what to run

​Choose a reporting mode

​Resolve the CLI and dependencies

​Report to the correct commit

​Test preview deployments

​Protect merges with detached checks

​Next steps

Run checks on pull requests

Choose what to run

Choose a reporting mode

Resolve the CLI and dependencies

Report to the correct commit

Test preview deployments

Protect merges with detached checks

Next steps