From 36e80423704db17984264485ab4d4c20e8e1cb40 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Wed, 23 Sep 2026 16:49:15 +0900 Subject: [PATCH] docs(cli): the deploy write-back covers every resource type [RED-997] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Describe what the interactive deploy's "update my code" choice writes for alert channels, private locations, dashboards, maintenance windows and status pages with their services, components and automation rules, what it refuses (credentials, a channel's type and fixed webhook settings, Telegram's packed template, a dashboard's stylesheet, a v2 page's cards, component and rule references), that dates are written as new Date('…') and the repeat settings together, and that a construct declared in a shared module is looked for in the first file that imported it. Co-Authored-By: Claude Fable 5.1 --- cli/checkly-deploy.mdx | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/cli/checkly-deploy.mdx b/cli/checkly-deploy.mdx index 37d92877..7f66b2db 100644 --- a/cli/checkly-deploy.mdx +++ b/cli/checkly-deploy.mdx @@ -67,7 +67,7 @@ Resources that did not change are not written at all. Deploying the same code tw ### Updating your code with changes made in Checkly -When the plan shows a check or check group that was edited in the Checkly web app or through the API, and the edit is on a property the CLI can write into your code, the prompt gets a third choice next to applying and cancelling: +When the plan shows a resource that was edited in the Checkly web app or through the API, and the edit is on a property the CLI can write into your code, the prompt gets a third choice next to applying and cancelling: ```text Terminal ? Apply these changes? › @@ -76,14 +76,20 @@ When the plan shows a check or check group that was edited in the Checkly web ap ❯ Cancel ``` -Choosing it writes your account's current values into the construct files of checks and check groups and ends the run without deploying, so you can review the result with `git diff` and deploy again; any other resource type the code still declares is listed as not updated. Only what can be written without guessing is written, so a reason found once the file is read (listed below) can still leave nothing to write: +Choosing it writes your account's current values into the construct files and ends the run without deploying, so you can review the result with `git diff` and deploy again. Only what can be written without guessing is written, so a reason found once the file is read (listed below) can still leave nothing to write: - On every check: `name`, `description`, `activated`, `muted`, `shouldFail`, `tags`, `locations`, `frequency` and `alertEscalationPolicy`; `retryStrategy` on every check except agentic and Playwright checks, which do not take one. Also `degradedResponseTime` and `maxResponseTime` on API checks and URL, TCP, DNS, gRPC, SSL and traceroute monitors; the packet-loss thresholds on ICMP monitors; `period` and `grace` on heartbeat monitors, each written together with its unit; `environmentVariables` and `runtimeId` on API, browser, multistep and Playwright checks (a check that relied on the project-wide runtime gets the value pinned, like any other defaulted property); `sslCheckDomain` and `aiAutoRepairEnabled` on browser checks and `aiAutoRepairEnabled` on multistep checks; `prompt` on agentic checks (a multi-line prompt written as a template literal stays one); the `request` of an API check (`url`, `method`, `headers`, `queryParameters`, `body`, `bodyType`, `basicAuth`, `followRedirects`, `skipSSL`, `ipFamily`), URL monitor (`url`, `followRedirects`, `skipSSL`, `ipFamily`), TCP monitor (`hostname`, `port`, `data`, `ipFamily`), DNS monitor (`query`, `recordType`, `protocol`, and `nameServer` and `port`, written together), ICMP monitor (`hostname`, `pingCount`, `ipFamily`), gRPC monitor (`url`, `port`, `skipSSL`, `timeout`, `ipFamily` and the `grpcConfig` keys, except `metadata`, whose values Checkly never returns), SSL monitor (`hostname`, `port`, `ipFamily` and the `sslConfig` keys) or traceroute monitor (every key); and the `request.assertions` of an API check and of every URL, TCP, DNS, gRPC, SSL, ICMP and traceroute monitor. Agentic checks take no `shouldFail`. - On a check group: `name`, `activated`, `muted`, `tags`, `locations`, `concurrency`, `environmentVariables`, `runtimeId`, `retryStrategy`, `alertEscalationPolicy`, and `apiCheckDefaults` (`url`, `headers`, `queryParameters`, `basicAuth`, `assertions`). -- The construct has to be declared as `new ApiCheck('logical-id', { … })` in a JavaScript or TypeScript file, with the class imported by name from `checkly/constructs` or destructured from a top-level `require` of it (a namespace import or a re-export from your own module is not recognised) and its options written out as an object literal. An existing value is replaced only when it is itself a literal (a string, number or boolean, or an array or object of those) or, for the properties below, an expression on the same helper whose arguments are literals; a property the code does not set is added after the last one of the object that holds it (`request` itself has to exist for `request.body` to be added), in the file's own quoting and indentation. Nothing else in the file is touched. +- On every alert channel: `sendRecovery`, `sendFailure`, `sendDegraded`, `sslExpiry` and `sslExpiryThreshold`, plus the channel's own properties: `address` on an email channel; `channel` on a Slack channel; `slackChannels` on a Slack app channel; `name`, `webhookType`, `template` and `method` on a webhook channel; `name`, `region` and `priority` on an Opsgenie channel; `account` and `serviceName` on a PagerDuty channel; `phoneNumber` and `name` on an SMS or phone call channel; `name` and `payload` on an MS Teams or incident.io channel; `name` on a Telegram channel. A credential (a webhook or Slack URL, an API key, a service key, a webhook secret, the values of `headers` and `queryParameters`) is never written, since Checkly does not return it; a channel's type, and the webhook type and method the MS Teams, Telegram and incident.io constructs fix, cannot change in the code; Telegram's `chatId`, `messageThreadId`, `payload` and `apiKey` are packed into the message template and URL, which the CLI does not unpack. +- On a private location: `name`, `slugName` and `icon` (`proxyUrl` is never written). +- On a dashboard: every property except `customCSS`, which is a stylesheet rather than a value; `tags` is written whole. +- On a maintenance window: `name`, `tags`, `startsAt` and `endsAt` (written as `new Date('…')` from the timestamp Checkly reports, over an existing `new Date(…)` or a string), and `repeatInterval`, `repeatUnit` and `repeatEndsAt`, which are written together or not at all. +- On a status page: `name`, `url`, `customDomain`, `logo`, `redirectTo`, `favicon` and `defaultTheme`, and on a `StatusPageV3` also `logoDark`, `description`, `privacyPolicyLink`, `termsOfServiceLink`, `supportLink`, `footerText`, `googleAnalyticsTag`, `allowIndexing` and each colour of `themeColors` (a colour under `light` or `dark` is added only when your code already has that object). The `cards` of a `StatusPage` hold services and are not written. +- On a status page service: `name`. On a `StatusPageV3Component`: `type`, `name`, `description`, `hidden`, `displayOrder`, `showHistoricalData` and `expandedByDefault` (its page and parent are references). On a `StatusPageV3AutomationRule`: `name`, `enabled`, `firstUpdate`, `lastUpdate`, `notifySubscribers`, `tags` and `coolDownMinutes` (its page and components are references). +- The construct has to be declared as `new ApiCheck('logical-id', { … })` in a JavaScript or TypeScript file, with the class imported by name from `checkly/constructs` or destructured from a top-level `require` of it (a namespace import or a re-export from your own module is not recognised) and its options written out as an object literal. An existing value is replaced only when it is itself a literal (a string, number or boolean, or an array or object of those) or, for the properties below, an expression on the same helper whose arguments are literals; a property the code does not set is added after the last one of the object that holds it (`request` itself has to exist for `request.body` to be added), in the file's own quoting and indentation. Nothing else in the file is touched. The file searched is the one the CLI was loading when the construct was created, so a construct declared in a module that several files import (a common layout for alert channels and status pages) is looked for in the first file that imported it, where the lookup fails and the construct is listed as not updated. - `frequency`, `retryStrategy`, `alertEscalationPolicy` and `assertions` are written the way `checkly import` spells them: `Frequency.EVERY_30S` (a whole-minute schedule stays a number where your code uses one), `RetryStrategyBuilder.fixedStrategy({ maxRetries: 3 })`, `AlertEscalationBuilder.runBasedEscalation(3, …)`, `AssertionBuilder.statusCode().equals(200)` and the corresponding builder of each monitor type. A helper the file does not import yet is added to its `import { … } from 'checkly/constructs'` (or to its `const { … } = require('checkly/constructs')`), which the output reports as well. A check group of the `CheckGroupV2` class moved to the global alert policy gets `alertEscalationPolicy: 'global'`. -A change that was also made in your code since the last deploy is written over it, and the output marks it `(replacing a local edit)`; a list such as `tags` or `assertions` that your code changed too is left alone instead, since the CLI cannot merge the two. Every change that cannot be written is listed under `Not updated (edit these by hand)` with its reason; the usual ones are a reference to another resource (alert channels, private locations, a group), an incident trigger (Checkly does not report its settings), a secret or a locked variable that Checkly does not return, a script or code bundle, `doubleCheck` (replaced by `retryStrategy`, whether or not a retry strategy sits beside it) and `runParallel`, the offset of a whole-minute schedule (Checkly assigns it), a property your code also changed, a helper call holding a variable, a check or a `CheckGroup` on the global alert policy or a group without a policy of its own (remove `alertEscalationPolicy` by hand; nothing is ever removed from your code), a retry strategy, alert policy or assertion this CLI version cannot spell, a helper name your file already uses for something else, a file with no `checkly/constructs` import to add a helper to, options built from a variable or a spread, or a construct the CLI cannot locate in the file (its id is computed, or two constructs share it). TypeScript and JSX files need `typescript` installed in the project, as TypeScript check files already do. +A change that was also made in your code since the last deploy is written over it, and the output marks it `(replacing a local edit)`; a list such as `tags` or `assertions` that your code changed too is left alone instead, since the CLI cannot merge the two. Every change that cannot be written is listed under `Not updated (edit these by hand)` with its reason; the usual ones are a reference to another resource (alert channels, private locations, a group, a status page's services, components or parent), an incident trigger (Checkly does not report its settings), a secret or a locked variable that Checkly does not return, a script or code bundle, `doubleCheck` (replaced by `retryStrategy`, whether or not a retry strategy sits beside it) and `runParallel`, the offset of a whole-minute schedule (Checkly assigns it), a property your code also changed, a helper call holding a variable, a check or a `CheckGroup` on the global alert policy or a group without a policy of its own (remove `alertEscalationPolicy` by hand; nothing is ever removed from your code), a retry strategy, alert policy or assertion this CLI version cannot spell, a helper name your file already uses for something else, a file with no `checkly/constructs` import to add a helper to, options built from a variable or a spread, or a construct the CLI cannot locate in the file (its id is computed, two constructs share it, or it is declared in a module several files import). TypeScript and JSX files need `typescript` installed in the project, as TypeScript check files already do. The CLI prints each property it updated with its old and new value, and each helper it imported. There is no flag for the choice, and the `confirmation_required` envelope does not change.