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

# Run Checkly from GitHub Actions

> Run Checkly test sessions from GitHub Actions and report results through workflow jobs or external GitHub Checks.

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.

<Accordion title="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.
</Accordion>

<Warning>
  Install the GitHub App from the Checkly account that will run the test session. Go to [Account settings > Integrations](https://app.checklyhq.com/settings/account/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.
</Warning>

## Run checks on pull requests

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

```yaml .github/workflows/checkly.yml theme={null}
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:

```yaml theme={null}
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:

```yaml .github/workflows/checkly-trigger.yml theme={null}
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.

```yaml theme={null}
with:
  command: test
  reporting: github-check
  github-check-name: Checkly PR validation
```

<Note>
  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.
</Note>

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

1. If the project installs the `checkly` package, the Action uses that local CLI so the CLI and imported constructs share the same module installation.
2. 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:

```yaml .github/workflows/checkly-monorepo.yml theme={null}
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:

```yaml .github/workflows/checkly-preview-dispatch.yml theme={null}
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:

```yaml .github/workflows/checkly-deployment.yml theme={null}
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](/integrations/ci-cd/github/deployments) instead of this workflow.

## Protect merges with detached checks

<Warning>
  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.
</Warning>

Configure the exact `github-check-name` as a [required check](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks).

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`](/cli/checkly-test).
* Learn more about [`checkly trigger`](/cli/checkly-trigger).
* Use [GitHub deployment hooks](/integrations/ci-cd/github/deployments) when you want Checkly to react directly to GitHub deployment events.