|
1 | 1 | --- |
2 | | -title: 'Environment variables' |
| 2 | +title: 'Environment variables and secrets' |
3 | 3 | sidebarTitle: 'Environment Variables' |
4 | | -description: 'Securely store and manage sensitive data like credentials and configuration values across your monitoring checks' |
| 4 | +description: 'Store and manage common configuration values across your checks' |
5 | 5 | --- |
6 | 6 |
|
7 | | -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. |
| 7 | +import GenericRuntimeVariablesTable from '/snippets/generic-runtime-variables-table.mdx'; |
8 | 8 |
|
9 | | -## Managing variables |
| 9 | +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. |
10 | 10 |
|
11 | | -You can create environment variables at three hierarchical levels, with check-level variables taking precedence over group and global variables. |
| 11 | +## Overview |
12 | 12 |
|
13 | | -<Accordion title="Check-level variables"> |
14 | | -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. |
| 13 | +There are two ways to store configuration information in Checkly: Variables and secrets. Both variables and secrets are encrypted at rest and in flight. |
| 14 | +* **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. |
| 15 | +* **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. |
15 | 16 |
|
16 | | -**Supported by:** API, Browser, Multistep & Playwright checks |
| 17 | +<Note> |
| 18 | +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. |
| 19 | +</Note> |
17 | 20 |
|
18 | | -Add variables on the **Variables** tab when editing a check. |
| 21 | +<Warning> |
| 22 | +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`. |
| 23 | +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. |
| 24 | +Numbers are not scrubbed from the Playwright trace, but from the general check result. |
| 25 | +</Warning> |
19 | 26 |
|
20 | | - |
| 27 | +From here on, in this document, we refer to both variables and secrets as 'variables' for ease of reading, unless explicitly mentioned. |
21 | 28 |
|
22 | | -**Example use cases:** |
23 | | -- Test-specific credentials |
24 | | -- Different API endpoints per check |
25 | | -- Override default timeout values |
26 | | -</Accordion> |
27 | | - |
28 | | -<Accordion title="Group-level variables"> |
29 | | -Variables defined at the group level are inherited by all checks within that group. This is ideal for sharing common configuration across related checks. |
| 29 | +## Managing variables |
30 | 30 |
|
31 | | -**Benefits:** |
32 | | -- Reduces duplication across checks in the same group |
33 | | -- Consistent configuration for related monitoring scenarios |
34 | | -- Easy maintenance when credentials or endpoints change |
| 31 | +You can create environment variables and secrets at three hierarchical levels: |
35 | 32 |
|
36 | | -**Example use cases:** |
37 | | -- Shared service credentials for all checks in a group |
38 | | -- Common API base URLs |
39 | | -- Environment-specific configuration (staging vs production) |
40 | | -</Accordion> |
| 33 | +<Accordion title="Check-level"> |
| 34 | +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. |
41 | 35 |
|
42 | | -<Accordion title="Global variables"> |
43 | | -Variables defined at the global level are available to all checks across your entire account. Use these for organization-wide configuration. |
| 36 | +**Supported by:** API (only via the CLI), Browser, Multistep & Playwright checks |
44 | 37 |
|
45 | | -**Best practice:** Store variables at the global level whenever possible to follow the DRY (Don't Repeat Yourself) principle. |
| 38 | +Check-level variables are shown in the **Variables** tab on the check edit page. |
46 | 39 |
|
47 | | -**Example use cases:** |
48 | | -- Organization-wide credentials |
49 | | -- Global configuration values |
50 | | -- Default timeout and retry settings |
| 40 | + |
51 | 41 | </Accordion> |
52 | 42 |
|
53 | | -## Variable hierarchy |
| 43 | +<Accordion title="Group-level"> |
| 44 | +Group variables are only accessible in the context of a group, which includes the checks within the group and their configuration. |
54 | 45 |
|
55 | | -When checks run, Checkly merges variables from all three levels into a single dataset. Variables at more specific levels override those at broader levels: |
| 46 | +Group-level variables are shown the **Variables** tab in a check group. |
56 | 47 |
|
57 | | -**Check variables** > **Group variables** > **Global variables** |
| 48 | + |
| 49 | +</Accordion> |
58 | 50 |
|
59 | | -This hierarchy allows you to: |
60 | | -- Set default values at the global or group level |
61 | | -- Override specific values at the check level when needed |
62 | | -- Maintain flexible configuration with minimal duplication |
| 51 | +<Accordion title="Global"> |
| 52 | +Variables defined at the global level are available throughout Checkly, including in checks, alert channels, and global configuration options. |
63 | 53 |
|
64 | | -## Accessing variables |
| 54 | +Global variables are shown in the [Environment variables](https://app.checklyhq.com/environment-variables) section on the left-side menu. |
65 | 55 |
|
66 | | -Environment variables are accessible in your code using the standard Node.js `process.env.VARIABLE_NAME` notation. |
| 56 | + |
67 | 57 |
|
68 | | -<Accordion title="Example: GitHub login"> |
69 | | -<CodeGroup dropdown> |
| 58 | +<Note> |
| 59 | +Store variables at the global level whenever possible to follow the DRY (Don't Repeat Yourself) principle. |
| 60 | +</Note> |
70 | 61 |
|
71 | | -```ts variables.spec.ts |
72 | | -import { test } from '@playwright/test' |
| 62 | +</Accordion> |
73 | 63 |
|
74 | | -test('GitHub login', async ({ page }) => { |
75 | | - await page.goto('https://github.com/login') |
76 | | - await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) |
77 | | - await page.getByLabel('Password').type(process.env.GITHUB_PWD) |
78 | | - await page.getByRole('button', { name: 'Sign in' }).click() |
79 | | -}) |
80 | | -``` |
| 64 | +By default, all variables are stored as string values. |
81 | 65 |
|
82 | | -```js variables.spec.js |
83 | | -const { test } = require('@playwright/test') |
| 66 | +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. |
84 | 67 |
|
85 | | -test('GitHub login', async ({ page }) => { |
86 | | - await page.goto('https://github.com/login') |
87 | | - await page.getByLabel('Username or email address').type(process.env.GITHUB_USER) |
88 | | - await page.getByLabel('Password').type(process.env.GITHUB_PWD) |
89 | | - await page.getByRole('button', { name: 'Sign in' }).click() |
90 | | -}) |
91 | | -``` |
| 68 | +Secrets are never visible for any user and are always encrypted. |
92 | 69 |
|
93 | | -</CodeGroup> |
94 | | -</Accordion> |
| 70 | +## Variable hierarchy |
95 | 71 |
|
96 | | -## Built-in variables |
| 72 | +As checks are scheduled, Checkly merges the check, group, and global environment variables into one data set and exposes them |
| 73 | +to the runtime environment. During merging, variables at more specific levels override those at broader levels. |
97 | 74 |
|
98 | | -Checkly provides several built-in environment variables that are automatically available in your checks: |
| 75 | +Or, in other words: **check** variables override **group** variables override **global** variables. |
99 | 76 |
|
100 | | -<Accordion title="Runtime variables"> |
101 | | -- `CHECK_NAME` - The name of the current check |
102 | | -- `CHECK_TYPE` - The type of check (API, BROWSER, etc.) |
103 | | -- `CHECK_ID` - The unique identifier of the check |
104 | | -- `REGION` - The current data center location (e.g., `us-east-1`) |
105 | | -- `RUN_ID` - Unique identifier for the current check run |
106 | | -</Accordion> |
| 77 | +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 |
| 78 | +be overridden at the check level. |
| 79 | + |
| 80 | +## Accessing variables |
107 | 81 |
|
108 | | -## Security |
| 82 | +How variables are accessed depends on where you're accessing them from: |
109 | 83 |
|
110 | | -- **Encryption:** All variable data is encrypted at rest and in transit |
111 | | -- **Access control:** Locked variables can only be accessed by team members with Read & Write access or above |
112 | | -- **Best practices:** Avoid logging sensitive variables in your check results to prevent exposure to Read Only team members |
| 84 | +* 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. |
| 85 | +* In [API Check requests](/detect/synthetic-monitoring/api-checks/requests#accessing-environment-variables), use Handlebars/Moustache templating delimiters, i.e. `{{VARIABLE_NAME}}` |
| 86 | +* In [webhook alert channels](/integrations/alerts/webhooks#template-variables), also use the Handlebar/Moustache format, i.e. `{{VARIABLE_NAME}}` |
113 | 87 |
|
114 | 88 | <Note> |
115 | | -For more login scenarios and examples, see our [login scenarios documentation](/browser-checks/login-scenarios/). |
| 89 | + Handlebar (double brackets) variables will be URI encoded. To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{VARIABLE_NAME}}}`. |
116 | 90 | </Note> |
0 commit comments