From ec366ef2467bd21974f9e7280ff2b64956a15a6d Mon Sep 17 00:00:00 2001 From: Laura Guo Date: Fri, 10 Oct 2025 11:57:10 -0400 Subject: [PATCH 1/3] Restore missing env var content, plus minor fixes/updates --- .../api-checks/requests.mdx | 41 +++++- .../api-checks/set-up-and-tear-down.mdx | 10 +- .../browser-checks/mac-structure.mdx | 37 +++++ .../multistep-checks/overview.mdx | 5 +- platform/variables.mdx | 132 +++++++----------- snippets/generic-runtime-variables-table.mdx | 12 ++ 6 files changed, 153 insertions(+), 84 deletions(-) create mode 100644 snippets/generic-runtime-variables-table.mdx diff --git a/detect/synthetic-monitoring/api-checks/requests.mdx b/detect/synthetic-monitoring/api-checks/requests.mdx index dfcf514a..84e7a736 100644 --- a/detect/synthetic-monitoring/api-checks/requests.mdx +++ b/detect/synthetic-monitoring/api-checks/requests.mdx @@ -4,7 +4,7 @@ description: 'Requests' sidebarTitle: 'Requests' --- - +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; A full HTTP request is created by filling out the various parts of the HTTP request settings screen. Not all sections and fields are mandatory, only a name and URL are required to get going. @@ -162,3 +162,42 @@ This list shows all content types that we scrub from the response data. |`video/x-flv`| |`video/webm`| +## Accessing environment variables + +[Environment variables](/platform/variables) are exposed to your API checks using the common Handlebars/Moustache templating delimiters, i.e. `{{USER_API_KEY}}`. Note that Handlebars (double brackets) variables will be URI encoded. To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{USER_API_KEY}}}`. + +Variables can be used in the following API checks fields: + +- URL +- Body +- Header values +- Query parameters values +- Basic authentication username and password + +### Using helpers and built-in variables + +Next to your own variables, we've added some built-in ones. + +These variables are specific to API checks: + +| Helper | Description | +|----------------------|------------ | +| `{{GROUP_BASE_URL}}` | If your check belongs to a group, this resolves to the group's configured base URL. | +| `{{REQUEST_URL}}` | The request URL. | +| `{{$UUID}}` | Generates a random UUID/v4, i.e. 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d. | +| `{{$RANDOM_NUMBER}}` | Generates a random decimal number between 0 and 10000, i.e. 345. | +| `{{moment}}` | Generates a date or time using **moment.js** and allows for formatting: | + +A practical example of using the `{{moment}}` helper would be setting the pagination options on a typical API endpoint: + +``` + GET https://api.acme.com/events?from={{moment "last week" "X"}}&to={{moment "X"}} +``` + + +For a full overview of date formatting option, check the [moment.js docs](https://momentjs.com/docs/#/displaying/format/). + + +In addition, you have access to these generic variables available to all checks: + + \ No newline at end of file diff --git a/detect/synthetic-monitoring/api-checks/set-up-and-tear-down.mdx b/detect/synthetic-monitoring/api-checks/set-up-and-tear-down.mdx index dbc217a6..4439e499 100644 --- a/detect/synthetic-monitoring/api-checks/set-up-and-tear-down.mdx +++ b/detect/synthetic-monitoring/api-checks/set-up-and-tear-down.mdx @@ -5,6 +5,8 @@ description: 'Learn how to set up and tear down an API check with Checkly.' sidebarTitle: Set Up and Tear Down --- +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; + Setup and teardown scripts can be used to execute arbitrary JavaScript/TypeScript code before and/or after an API check. Both script types have access to all environment variables, runtime objects like `request` and `response` and popular npm packages like `moment`, `axios` and `lodash`. @@ -166,7 +168,7 @@ delete process.env.SOME_OTHER_KEY In setup scripts, the modified environment object is used for the subsequent HTTP request. In teardown script, the modified environment object is just there for informational purposes. -[More about using environment variables](/api-checks/variables/) +[More about using environment variables](/platform/variables) ### Request @@ -196,16 +198,18 @@ Response properties are exposed a standard Javascript object. These are only ava ### Built-in runtime variables [The setup and teardown runtime](/platform/runtimes/overview) also exposes a set of specific environment variables to the setup and teardown scripts, -next to the "generic" runtime variables like `process.env.CHECK_NAME` you find in all check runtimes +next to the "generic" runtime variables like `process.env.CHECK_NAME` you find in all check runtimes. #### Setup & teardown specific variables -| variable | description | +| Variable | Description | |------------------|------------------------------------------------------------| | `GROUP_BASE_URL` | The `{{GROUP_BASE_URL}}` value of the grouped `API` check. | | `REQUEST_URL` | The request URL of the `API` check executed. | +#### Generic runtime variables + ## Included libraries diff --git a/detect/synthetic-monitoring/browser-checks/mac-structure.mdx b/detect/synthetic-monitoring/browser-checks/mac-structure.mdx index 477c7868..f790789c 100644 --- a/detect/synthetic-monitoring/browser-checks/mac-structure.mdx +++ b/detect/synthetic-monitoring/browser-checks/mac-structure.mdx @@ -4,6 +4,7 @@ description: 'Learn how to structure your Browser Checks with Monitoring as Code sidebarTitle: MaC Structure --- +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; Monitoring as Code works by connecting Playwrighttest files with Checkly constructs to handle the end-to-endconfiguration of your Browser Check. @@ -42,3 +43,39 @@ test('Environment-aware test', async ({ page }) => { }) ``` +## Environment variables + +[Check, group and global variables](/platform/variables) are accessible in your code using the standard Node.js `process.env.MY_VAR` notation. For example, the code snippet below show how you can log into GitHub. + + + +```ts variables.spec.ts +import { test } from '@playwright/test' + +test('GitHub login', async ({ page }) => { + await page.goto('https://github.com/login') + await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) + await page.getByLabel('Password').type(process.env.GITHUB_PWD) + await page.getByRole('button', { name: 'Sign in' }).click() +}) +``` + +```js variables.spec.js +const { test } = require('@playwright/test') + +test('GitHub login', async ({ page }) => { + await page.goto('https://github.com/login') + await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) + await page.getByLabel('Password').type(process.env.GITHUB_PWD) + await page.getByRole('button', { name: 'Sign in' }).click() +}) +``` + + + +### Built-in runtime variables + +Our [check runtimes](/platform/runtimes/overview/) also expose a set of environment variables (e.g. `process.env.CHECK_NAME`) +to figure out what check, check type etc. you are running. + + \ No newline at end of file diff --git a/detect/synthetic-monitoring/multistep-checks/overview.mdx b/detect/synthetic-monitoring/multistep-checks/overview.mdx index 3d7f36ad..7abad674 100644 --- a/detect/synthetic-monitoring/multistep-checks/overview.mdx +++ b/detect/synthetic-monitoring/multistep-checks/overview.mdx @@ -4,6 +4,8 @@ description: 'Monitor complex API workflows with sequential requests using Playw sidebarTitle: 'Overview' --- +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; + **Monitoring as Code**: Learn more about the [Multistep Check Construct](/constructs/multistep-check). @@ -66,5 +68,6 @@ As with Browser checks, Checkly runs Multistep checks for a maximum of 240s. Scr The Multistep Check [runtime](/platform/runtimes/overview) exposes a set of environment variables (e.g. `process.env.CHECK_NAME`) that indicate what check, check type etc. you are running. + - +[Learn more about environment variables.](/platform/variables) diff --git a/platform/variables.mdx b/platform/variables.mdx index f8f5da40..6f2fadf4 100644 --- a/platform/variables.mdx +++ b/platform/variables.mdx @@ -1,116 +1,90 @@ --- -title: 'Environment variables' +title: 'Environment variables and secrets' sidebarTitle: 'Environment Variables' -description: 'Securely store and manage sensitive data like credentials and configuration values across your monitoring checks' +description: 'Store and manage common configuration values across your checks' --- -Environment variables allow you to store sensitive data like credentials and configuration values that can be reused across your monitoring setup. This keeps secrets out of your code and enables flexible configuration management. +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; -## Managing variables +Your checks might share the same configuration data, like an authentication token, a user name, or even a specific part of the URL. You can use variables and secrets to 'DRY' up your checks, store these variables in one place, and keep sensitive data secure. -You can create environment variables at three hierarchical levels, with check-level variables taking precedence over group and global variables. +## Overview - -Variables defined at the check level are only available to that specific check. Use these for check-specific configuration or to override group/global variables. +There are two ways to store configuration information in Checkly: Variables and secrets. Both variables and secrets are encrypted at rest and in flight. +* **Variables** are used to store non-sensitive information. Variables are shown in plaintext when being edited, on the check result page and in logs. Variables can be accessed via the CLI and API. +* **Secrets** allow you to store sensitive data for use in checks. Once saved, secrets are never shown in the UI or in logs and cannot be accessed via the CLI or API. -**Supported by:** API, Browser, Multistep & Playwright checks + +Secrets are fully supported starting with runtime version 2024.09 and later. For [Private Locations](/docs/private-locations/), secrets are available in agent version `3.3.4` and later, and for the [CLI](/docs/cli/), in version `4.9.0` and later. + -Add variables on the **Variables** tab when editing a check. + +To ensure the integrity of Playwright artifacts (traces, videos and screenshots), the following are not scrubbed, even when saved as secrets: The characters `/` and `*` and the full or partial match of `/artifact/`, `https://`, `http://`, `*********`, and `123`. +Values of the keys `sha1`, `_sha1`, `pageref`, `downloadsPath`, `tracesDir`, `pageId` and any string that ends with `sha1` will not be scrubbed from the Playwright trace, but will be scrubbed from the general check result. +Numbers are not scrubbed from the Playwright trace, but from the general check result. + -![check environment variables](/images/docs/images/browser-checks/check-environment-variables.png) +From here on, in this document, we refer to both variables and secrets as 'variables' for ease of reading, unless explicitly mentioned. -**Example use cases:** -- Test-specific credentials -- Different API endpoints per check -- Override default timeout values - - - -Variables defined at the group level are inherited by all checks within that group. This is ideal for sharing common configuration across related checks. +## Managing variables -**Benefits:** -- Reduces duplication across checks in the same group -- Consistent configuration for related monitoring scenarios -- Easy maintenance when credentials or endpoints change +You can create environment variables and secrets at three hierarchical levels: -**Example use cases:** -- Shared service credentials for all checks in a group -- Common API base URLs -- Environment-specific configuration (staging vs production) - + +Variables defined at the check level are only available to that specific check. Use these for check-specific configuration or to override group/global variables. - -Variables defined at the global level are available to all checks across your entire account. Use these for organization-wide configuration. +**Supported by:** API (only via the CLI), Browser, Multistep & Playwright checks -**Best practice:** Store variables at the global level whenever possible to follow the DRY (Don't Repeat Yourself) principle. +Check-level variables are shown in the **Variables** tab on the check edit page. -**Example use cases:** -- Organization-wide credentials -- Global configuration values -- Default timeout and retry settings +![check environment variables](/images/docs/images/browser-checks/check-environment-variables.png) -## Variable hierarchy + +Group variables are only accessible in the context of a group, which includes the checks within the group and their configuration. -When checks run, Checkly merges variables from all three levels into a single dataset. Variables at more specific levels override those at broader levels: +Group-level variables are shown the **Variables** tab in a check group. -**Check variables** > **Group variables** > **Global variables** +![set group environment variable](/images/docs/images/browser-checks/group-environment-variables.png) + -This hierarchy allows you to: -- Set default values at the global or group level -- Override specific values at the check level when needed -- Maintain flexible configuration with minimal duplication + +Variables defined at the global level are available throughout Checkly, including in checks, alert channels, and global configuration options. -## Accessing variables +Global variables are shown in the [Environment variables](https://app.checklyhq.com/environment-variables) section on the left-side menu. -Environment variables are accessible in your code using the standard Node.js `process.env.VARIABLE_NAME` notation. +![set global environment variable](/images/docs/images/browser-checks/global-environment-variables.png) - - + +Store variables at the global level whenever possible to follow the DRY (Don't Repeat Yourself) principle. + -```ts variables.spec.ts -import { test } from '@playwright/test' + -test('GitHub login', async ({ page }) => { - await page.goto('https://github.com/login') - await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) - await page.getByLabel('Password').type(process.env.GITHUB_PWD) - await page.getByRole('button', { name: 'Sign in' }).click() -}) -``` +By default, all variables are stored as string values. -```js variables.spec.js -const { test } = require('@playwright/test') +When using variables, you can click the lock icon to hide the value. Any data you “lock” is encrypted at rest and in flight on our back end and is only decrypted when needed. Locked environment variables can only be accessed by team members with [Read & Write access](/admin/team-management/overview/) or above. -test('GitHub login', async ({ page }) => { - await page.goto('https://github.com/login') - await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) - await page.getByLabel('Password').type(process.env.GITHUB_PWD) - await page.getByRole('button', { name: 'Sign in' }).click() -}) -``` +Secrets are never visible for any user and are always encrypted. - - +## Variable hierarchy -## Built-in variables +As checks are scheduled, Checkly merges the check, group, and global environment variables into one data set and exposes them +to the runtime environment. During merging, variables at more specific levels override those at broader levels. -Checkly provides several built-in environment variables that are automatically available in your checks: +Or, in other words: **check** variables override **group** variables override **global** variables. - -- `CHECK_NAME` - The name of the current check -- `CHECK_TYPE` - The type of check (API, BROWSER, etc.) -- `CHECK_ID` - The unique identifier of the check -- `REGION` - The current data center location (e.g., `us-east-1`) -- `RUN_ID` - Unique identifier for the current check run - +You can make use of this by providing a default value for a specific variable at the global or group level, but allow that variable to +be overridden at the check level. + +## Accessing variables -## Security +How variables are accessed depends on where you're accessing them from: -- **Encryption:** All variable data is encrypted at rest and in transit -- **Access control:** Locked variables can only be accessed by team members with Read & Write access or above -- **Best practices:** Avoid logging sensitive variables in your check results to prevent exposure to Read Only team members +* In [Browser](/detect/synthetic-monitoring/browser-checks/mac-structure#environment-variables), [Multistep](/detect/synthetic-monitoring/multistep-checks/overview#built-in-runtime-variables), and [API Check setup/teardown scripts](/detect/synthetic-monitoring/api-checks/set-up-and-tear-down#built-in-variables), use the standard Node.js `process.env.VARIABLE_NAME` notation. +* In [API Check requests](/detect/synthetic-monitoring/api-checks/requests#accessing-environment-variables), use Handlebars/Moustache templating delimiters, i.e. `{{VARIABLE_NAME}}` +* In [webhook alert channels](/integrations/alerts/webhooks#template-variables), also use the Handlebar/Moustache format, i.e. `{{VARIABLE_NAME}}` -For more login scenarios and examples, see our [login scenarios documentation](/browser-checks/login-scenarios/). + Handlebar (double brackets) variables will be URI encoded. To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{VARIABLE_NAME}}}`. diff --git a/snippets/generic-runtime-variables-table.mdx b/snippets/generic-runtime-variables-table.mdx new file mode 100644 index 00000000..854c04ab --- /dev/null +++ b/snippets/generic-runtime-variables-table.mdx @@ -0,0 +1,12 @@ +| Variable | Description | Availability | +|-------------------|---------------------------------------------|--------------------------------------| +| `ACCOUNT_ID` | The ID of the account the check belongs to. | | +| `CHECK_ID` | The UUID of the check being executed. | Only available after saving the check. | +| `CHECK_NAME` | The name of the check being executed. | | +| `CHECK_RESULT_ID` | The UUID where the result will be saved. | Only available on scheduled runs. | +| `CHECK_RUN_ID` | The UUID of the check run execution. | Only available on scheduled runs. | +| `CHECK_TYPE` | The type of the check, e.g. `BROWSER`. | | +| `PUBLIC_IP_V4` | The IPv4 of the check run execution. | | +| `PUBLIC_IP_V6` | The IPv6 of the check run execution. | | +| `REGION` | The current region, e.g. `us-west-1`. | | +| `RUNTIME_VERSION` | The version of the runtime, e.g, `2023.09`. | Only in Browser, Multistep, and API setup/teardown scripts. | \ No newline at end of file From 619f0fc74ba1463b73af34d050cb66ae7496d143 Mon Sep 17 00:00:00 2001 From: Laura Guo Date: Tue, 14 Oct 2025 11:43:08 -0400 Subject: [PATCH 2/3] Move "Accessing Environment Variables" section to below "Basic Authentication" in API docs --- .../api-checks/requests.mdx | 82 +++++++++---------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/detect/synthetic-monitoring/api-checks/requests.mdx b/detect/synthetic-monitoring/api-checks/requests.mdx index 84e7a736..575c7e81 100644 --- a/detect/synthetic-monitoring/api-checks/requests.mdx +++ b/detect/synthetic-monitoring/api-checks/requests.mdx @@ -98,6 +98,46 @@ request, use the username and password fields in the relevant section. ![api monitoring basic auth](/images/docs/images/api-checks/http-request-auth.png) +## Accessing environment variables + +[Environment variables](/platform/variables) are exposed to your API checks using the common Handlebars/Moustache templating delimiters, i.e. `{{USER_API_KEY}}`. Note that Handlebars (double brackets) variables will be URI encoded. To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{USER_API_KEY}}}`. + +Variables can be used in the following API checks fields: + +- URL +- Body +- Header values +- Query parameters values +- Basic authentication username and password + +### Using helpers and built-in variables + +Next to your own variables, we've added some built-in ones. + +These variables are specific to API checks: + +| Helper | Description | +|----------------------|------------ | +| `{{GROUP_BASE_URL}}` | If your check belongs to a group, this resolves to the group's configured base URL. | +| `{{REQUEST_URL}}` | The request URL. | +| `{{$UUID}}` | Generates a random UUID/v4, i.e. 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d. | +| `{{$RANDOM_NUMBER}}` | Generates a random decimal number between 0 and 10000, i.e. 345. | +| `{{moment}}` | Generates a date or time using **moment.js** and allows for formatting:
  • `{{moment "YYYY-MM-DD"}}` generates a date, i.e. 2020-08-26
  • `{{moment "2 days ago" "YYYY-MM-DD"}}` generates the date two days ago: 2020-08-24
  • `{{moment "last week" "X"}}` generates a UNIX timestamp from last week: 1597924480
| + +A practical example of using the `{{moment}}` helper would be setting the pagination options on a typical API endpoint: + +``` + GET https://api.acme.com/events?from={{moment "last week" "X"}}&to={{moment "X"}} +``` + + +For a full overview of date formatting option, check the [moment.js docs](https://momentjs.com/docs/#/displaying/format/). + + +In addition, you have access to these generic variables available to all checks: + + + ## Import a cURL request You can import the request method, url, headers and body from a [cURL](https://curl.haxx.se/) command. @@ -160,44 +200,4 @@ This list shows all content types that we scrub from the response data. |`video/x-ms-wmv`| |`video/x-msvideo`| |`video/x-flv`| -|`video/webm`| - -## Accessing environment variables - -[Environment variables](/platform/variables) are exposed to your API checks using the common Handlebars/Moustache templating delimiters, i.e. `{{USER_API_KEY}}`. Note that Handlebars (double brackets) variables will be URI encoded. To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{USER_API_KEY}}}`. - -Variables can be used in the following API checks fields: - -- URL -- Body -- Header values -- Query parameters values -- Basic authentication username and password - -### Using helpers and built-in variables - -Next to your own variables, we've added some built-in ones. - -These variables are specific to API checks: - -| Helper | Description | -|----------------------|------------ | -| `{{GROUP_BASE_URL}}` | If your check belongs to a group, this resolves to the group's configured base URL. | -| `{{REQUEST_URL}}` | The request URL. | -| `{{$UUID}}` | Generates a random UUID/v4, i.e. 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d. | -| `{{$RANDOM_NUMBER}}` | Generates a random decimal number between 0 and 10000, i.e. 345. | -| `{{moment}}` | Generates a date or time using **moment.js** and allows for formatting:
  • `{{moment "YYYY-MM-DD"}}` generates a date, i.e. 2020-08-26
  • `{{moment "2 days ago" "YYYY-MM-DD"}}` generates the date two days ago: 2020-08-24
  • `{{moment "last week" "X"}}` generates a UNIX timestamp from last week: 1597924480
| - -A practical example of using the `{{moment}}` helper would be setting the pagination options on a typical API endpoint: - -``` - GET https://api.acme.com/events?from={{moment "last week" "X"}}&to={{moment "X"}} -``` - - -For a full overview of date formatting option, check the [moment.js docs](https://momentjs.com/docs/#/displaying/format/). - - -In addition, you have access to these generic variables available to all checks: - - \ No newline at end of file +|`video/webm`| \ No newline at end of file From 35b0a08069e8288bec80671c8f83bf8dec30428c Mon Sep 17 00:00:00 2001 From: Laura Guo Date: Tue, 14 Oct 2025 11:44:12 -0400 Subject: [PATCH 3/3] Add link to /cli/environment-variables on /platform/variables page --- platform/variables.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/platform/variables.mdx b/platform/variables.mdx index 6f2fadf4..22836efb 100644 --- a/platform/variables.mdx +++ b/platform/variables.mdx @@ -6,7 +6,7 @@ description: 'Store and manage common configuration values across your checks' import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; -Your checks might share the same configuration data, like an authentication token, a user name, or even a specific part of the URL. You can use variables and secrets to 'DRY' up your checks, store these variables in one place, and keep sensitive data secure. +Your checks might share the same configuration data, like an authentication token, a user name, or even a specific part of the URL. You can use variables and secrets to 'DRY' up your checks, store these variables in one place, and keep sensitive data secure. ## Overview @@ -24,6 +24,10 @@ Values of the keys `sha1`, `_sha1`, `pageref`, `downloadsPath`, `tracesDir`, `pa Numbers are not scrubbed from the Playwright trace, but from the general check result. + + This page provides a general overview of environment variables. For information specific to the CLI, refer to our [Checkly CLI documentation](/cli/environment-variables). + + From here on, in this document, we refer to both variables and secrets as 'variables' for ease of reading, unless explicitly mentioned. ## Managing variables