Organizing checks with groups
Groups help you organize your checks (e.g. by team or feature) and apply shared configuration such as API defaults, scheduling & location overrides, and other properties.
Creating a check group
By default, newly created check groups behave like folders, with no group-level configuration applied. To get started:
-
Define a name: Pick a meaningful name for your group. It helps you and your team identify the group in Checkly and in alerts triggered by failures.
-
Add tags (optional): Tags help you relate groups to one another and also determine which checks appear on your dashboards.
You can populate a group by moving existing checks into it or by creating new checks directly within the group.
Group level configuration
Groups let you apply shared configuration to standardize how checks behave. Below is a breakdown of each setting and how it affects checks in the group:
API checks defaults
You can define API check defaults such as a common base URL, request information, assertions, and setup & teardown scripts to manage API checks in your group at scale.
Variables
For configuration information commonly used by checks in your group, create group environment variables and secrets. These are merged with variables at the global and check levels when a check runs.
Scheduling & locations overrides
-
Locations: Select public or private locations. This will override the location setting for all checks in your group. For example, if you create a check that runs in
eu-west-1
but add it to a group running inus-east-1
, the check will run fromus-east-1
only. -
Scheduling strategy: Selecting a scheduling strategy will override this setting for all checks in your group. For example, if you create a check that runs in
parallel
but add it to a group running inround-robin
, the check will run inround-robin
only. -
Frequency: Each check in your group runs at its own scheduling interval. However, you can specify a default at the group level with the
frequency
property via the CLI.
Retries & alerting overrides
-
Retries: Select your preferred retry strategy for failed checks. This will override retry settings for all checks in your group. For example, if you create a check that runs with
fixed
retries but add it to a group running withlinear
retries, the check will run withlinear
retries only. -
Alert settings: You can configure alert channels for checks in your group. If we don’t provide your preferred alert method, use webhooks to configure your alert flow. Like with retries, this will override alert settings for checks in your group.
Make sure to select an alert channel, otherwise checks in this group will not alert.
Testing
You can run checks in this group as E2E tests locally or from your CI/CD pipeline to validate your freshly deployed application. Use the Checkly CLI, or configure integrations with Vercel and GitHub.
Runtimes
Checkly manages the runtime environment for your JavaScript code in browser checks and setup & teardown scripts. If the checks in this group need a runtime different from your account default, you can set that here.
Adding or removing checks from groups
-
Moving a check into a group: If the group has group-level configuration defined, adding a check may change how it runs. Settings like API defaults, locations & scheduling, or retries & alerting can override or append to the check’s configuration.
-
Removing check from group: Any group-level configuration will no longer apply, and the check will use its own configuration going forward.
To prevent issues (e.g. broken references to group variables), the check will be automatically deactivated after being added to or removed from a group. Make sure to review its settings before reactivating.
How we run grouped checks
It helps to understand how we run the checks in a group, specifically if you’re doing more sophisticated checks with shared variables, script and alerting channels. Here are the rules:
- Checks are scheduled as individual checks, not “as a group”.
- Calling a “group run” using a trigger (either command line or via our GitHub integration) runs all the checks in a group.
- The group itself does not have an explicit runtime state.
- There are no results or metrics collected at the group level.
- Checks in a group still have their individual scheduling settings.
As you can see, groups in their current incarnation are mostly handy configuration buckets for common properties. In the future we will expand the group features to make them smarter.
Last updated on June 17, 2025. You can contribute to this documentation by editing this page on Github