Restore missing environment variable content, plus minor fixes/updates

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.
@@ -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: <ul> <li>`{{moment "YYYY-MM-DD"}}` generates a date, i.e. 2020-08-26</li> <li>`{{moment "2 days ago" "YYYY-MM-DD"}}` generates the date two days ago: 2020-08-24</li> <li>`{{moment "last week" "X"}}` generates a UNIX timestamp from last week: 1597924480</li> </ul> |
+
+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"}}
+```
+
+<Info>
+For a full overview of date formatting option, check the [moment.js docs](https://momentjs.com/docs/#/displaying/format/).
+</Info>
+
+In addition, you have access to these generic variables available to all checks:
+
+<GenericRuntimeVariablesTable/>
+
 ## Import a cURL request
 
 You can import the request method, url, headers and body from a [cURL](https://curl.haxx.se/) command.
@@ -160,5 +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`|
-
+|`video/webm`|

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
 
+<GenericRuntimeVariablesTable/>
 
 ## Included libraries
 

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.
+
+<CodeGroup dropdown>
+
+```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()
+})
+```
+
+</CodeGroup>
+
+### 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.
+
+<GenericRuntimeVariablesTable/>

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';
+
 <Tip>
 **Monitoring as Code**: Learn more about the [Multistep Check Construct](/constructs/multistep-check).
 </Tip>
@@ -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.
 
+<GenericRuntimeVariablesTable/>
 
-
+[Learn more about environment variables.](/platform/variables)

platform/variables.mdx

@@ -1,116 +1,94 @@
 ---
-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
 
-<Accordion title="Check-level variables">
-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
+<Note>
+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.
+</Note>
 
-Add variables on the **Variables** tab when editing a check.
+<Warning>
+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.
+</Warning>
 
-![check environment variables](/images/docs/images/browser-checks/check-environment-variables.png)
+<Tip>
+  This page provides a general overview of environment variables. For information specific to the CLI, refer to our [Checkly CLI documentation](/cli/environment-variables).
+</Tip> 
 
-**Example use cases:**
-- Test-specific credentials
-- Different API endpoints per check
-- Override default timeout values
-</Accordion>
+From here on, in this document, we refer to both variables and secrets as 'variables' for ease of reading, unless explicitly mentioned.
 
-<Accordion title="Group-level variables">
-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)
-</Accordion>
+<Accordion title="Check-level">
+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.
 
-<Accordion title="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)
 </Accordion>
 
-## Variable hierarchy
+<Accordion title="Group-level">
+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)
+</Accordion>
 
-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
+<Accordion title="Global">
+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.
+
+![set global environment variable](/images/docs/images/browser-checks/global-environment-variables.png)
 
-Environment variables are accessible in your code using the standard Node.js `process.env.VARIABLE_NAME` notation.
+<Note>
+Store variables at the global level whenever possible to follow the DRY (Don't Repeat Yourself) principle.
+</Note>
 
-<Accordion title="Example: GitHub login">
-<CodeGroup dropdown>
+</Accordion>
 
-```ts variables.spec.ts
-import { test } from '@playwright/test'
+By default, all variables are stored as string values. 
 
-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()
-})
-```
+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.
 
-```js variables.spec.js
-const { test } = require('@playwright/test')
+Secrets are never visible for any user and are always encrypted.
 
-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()
-})
-```
+## Variable hierarchy
 
-</CodeGroup>
-</Accordion>
+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.
 
-## Built-in variables
+Or, in other words: **check** variables override **group** variables override **global** variables.
 
-Checkly provides several built-in environment variables that are automatically available in your checks:
+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.
 
-<Accordion title="Runtime 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
-</Accordion>
+## 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}}`
 
 <Note>
-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}}}`.
 </Note>

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