diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index a76fc6d4a..53f4b9b57 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -30374,13 +30374,14 @@ }, "change_status": { "type": "string", - "description": "Lifecycle status of the change event, reported by the change source as execution progresses.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |", + "description": "Lifecycle status of the change event, reported by the change source as execution progresses.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "link": { @@ -30468,13 +30469,14 @@ }, "change_status": { "type": "string", - "description": "Current lifecycle status of the change.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |", + "description": "Current lifecycle status of the change.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "start_time": { diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index 3d49ef29d..6ffe7dad0 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -30374,13 +30374,14 @@ }, "change_status": { "type": "string", - "description": "变更事件的生命周期状态。由变更事件源按执行进度上报。\n| 值 | 含义 |\n|---|---|\n| `Planned` | 已计划，尚未开始。 |\n| `Ready` | 已就绪，待执行。 |\n| `Processing` | 正在执行。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "description": "变更事件的生命周期状态。由变更事件源按执行进度上报。\n| 值 | 含义 |\n|---|---|\n| `Planned` | 已计划，尚未开始。 |\n| `Ready` | 已就绪，待执行。 |\n| `Processing` | 正在执行。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "link": { @@ -30468,13 +30469,14 @@ }, "change_status": { "type": "string", - "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "start_time": { diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 36e2edaf6..5c2bdd216 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -1320,6 +1320,10 @@ "description": "Alert description.", "type": "string" }, + "detail_url": { + "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.", + "type": "string" + }, "end_time": { "description": "Unix timestamp (seconds) when the alert recovered. 0 if still active.", "format": "int64", @@ -1541,6 +1545,10 @@ "description": "Alert description.", "type": "string" }, + "detail_url": { + "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.", + "type": "string" + }, "end_time": { "description": "Resolution time, Unix epoch seconds. 0 if still active.", "format": "int64", @@ -4494,13 +4502,14 @@ "type": "string" }, "change_status": { - "description": "Lifecycle status of the change event, reported by the change source as execution progresses.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |", + "description": "Lifecycle status of the change event, reported by the change source as execution progresses.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "type": "string" }, @@ -4576,13 +4585,14 @@ "type": "string" }, "change_status": { - "description": "Current lifecycle status of the change.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |", + "description": "Current lifecycle status of the change.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "type": "string" }, diff --git a/api-reference/openapi.legacy.zh.json b/api-reference/openapi.legacy.zh.json index 8a655bf64..174469636 100644 --- a/api-reference/openapi.legacy.zh.json +++ b/api-reference/openapi.legacy.zh.json @@ -28938,7 +28938,8 @@ "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ] }, "start_time": { @@ -29007,7 +29008,8 @@ "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "description": "变更状态" }, diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 25cbdfae4..afedef7f7 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -1320,6 +1320,10 @@ "description": "告警描述。", "type": "string" }, + "detail_url": { + "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。", + "type": "string" + }, "end_time": { "description": "告警恢复的 Unix 时间戳（秒），仍活跃时为 0。", "format": "int64", @@ -1541,6 +1545,10 @@ "description": "告警描述。", "type": "string" }, + "detail_url": { + "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。", + "type": "string" + }, "end_time": { "description": "恢复时间，Unix 时间戳（秒）。活跃时为 0。", "format": "int64", @@ -4494,13 +4502,14 @@ "type": "string" }, "change_status": { - "description": "变更事件的生命周期状态。由变更事件源按执行进度上报。\n| 值 | 含义 |\n|---|---|\n| `Planned` | 已计划，尚未开始。 |\n| `Ready` | 已就绪，待执行。 |\n| `Processing` | 正在执行。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "description": "变更事件的生命周期状态。由变更事件源按执行进度上报。\n| 值 | 含义 |\n|---|---|\n| `Planned` | 已计划，尚未开始。 |\n| `Ready` | 已就绪，待执行。 |\n| `Processing` | 正在执行。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "type": "string" }, @@ -4576,13 +4585,14 @@ "type": "string" }, "change_status": { - "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |", "enum": [ "Planned", "Ready", "Processing", "Canceled", - "Done" + "Done", + "Failed" ], "type": "string" }, diff --git a/docs.json b/docs.json index 127a205a1..9410da20f 100644 --- a/docs.json +++ b/docs.json @@ -1853,7 +1853,26 @@ { "group": "变更集成", "pages": [ - "zh/on-call/integration/change-integration/custom-event" + "zh/on-call/integration/change-integration/custom-event", + "zh/on-call/integration/change-integration/github", + "zh/on-call/integration/change-integration/gitlab", + "zh/on-call/integration/change-integration/hcp-terraform", + "zh/on-call/integration/change-integration/argocd", + "zh/on-call/integration/change-integration/netlify", + "zh/on-call/integration/change-integration/vercel", + "zh/on-call/integration/change-integration/jfrog-artifactory", + "zh/on-call/integration/change-integration/buildkite", + "zh/on-call/integration/change-integration/launchdarkly", + "zh/on-call/integration/change-integration/jenkins", + "zh/on-call/integration/change-integration/circleci", + "zh/on-call/integration/change-integration/bitbucket", + "zh/on-call/integration/change-integration/unleash", + "zh/on-call/integration/change-integration/gitea", + "zh/on-call/integration/change-integration/rundeck", + "zh/on-call/integration/change-integration/flagsmith", + "zh/on-call/integration/change-integration/azure-devops", + "zh/on-call/integration/change-integration/argo-rollouts", + "zh/on-call/integration/change-integration/octopus-deploy" ] }, { @@ -3330,7 +3349,26 @@ { "group": "Change Integration", "pages": [ - "en/on-call/integration/change-integration/custom-event" + "en/on-call/integration/change-integration/custom-event", + "en/on-call/integration/change-integration/github", + "en/on-call/integration/change-integration/gitlab", + "en/on-call/integration/change-integration/hcp-terraform", + "en/on-call/integration/change-integration/argocd", + "en/on-call/integration/change-integration/netlify", + "en/on-call/integration/change-integration/vercel", + "en/on-call/integration/change-integration/jfrog-artifactory", + "en/on-call/integration/change-integration/buildkite", + "en/on-call/integration/change-integration/launchdarkly", + "en/on-call/integration/change-integration/jenkins", + "en/on-call/integration/change-integration/circleci", + "en/on-call/integration/change-integration/bitbucket", + "en/on-call/integration/change-integration/unleash", + "en/on-call/integration/change-integration/gitea", + "en/on-call/integration/change-integration/rundeck", + "en/on-call/integration/change-integration/flagsmith", + "en/on-call/integration/change-integration/azure-devops", + "en/on-call/integration/change-integration/argo-rollouts", + "en/on-call/integration/change-integration/octopus-deploy" ] }, { diff --git a/en/ai-sre/environments.mdx b/en/ai-sre/environments.mdx index 402ae75e4..4903e7e97 100644 --- a/en/ai-sre/environments.mdx +++ b/en/ai-sre/environments.mdx @@ -26,7 +26,9 @@ AI SRE provides two types of Environments: -The default selection logic is: **AI SRE uses an online BYOC Runner that the current member can use first; otherwise it uses the cloud Sandbox.** Usable Runners include Shared-scope (account-level) Runners and team-scoped Runners that belong to one of the current member's teams. You can also pin a session to the cloud Sandbox, or to a specific Runner, from the environment selector in the chat input. +When you don't specify an environment manually, the system picks one for each new session in this order: it first uses an online BYOC Runner under the team bound to the session; if no such Runner is available online, it falls back to an online Shared-scope (account-level) Runner; if neither is available, it uses the cloud Sandbox. + +You can also pin the session manually from the environment selector in the chat input: force the cloud Sandbox, or pin a specific Runner. The console record is called an **Environment**. The process running on your machine is called a **Runner**. One BYOC Environment maps to one Runner process; cloud Sandbox instances are managed by the system per session. @@ -403,7 +405,7 @@ The environment selector at the bottom of the chat input decides where a new ses | Option | Meaning | |---|---| -| **Auto** | The default for new sessions. Uses an online Runner the current member can use; otherwise falls back to the cloud Sandbox. | +| **Auto** | The default for new sessions. Tries an online BYOC Runner under the session's bound team, then an online Shared-scope (account-level) Runner, and falls back to the cloud Sandbox when neither is available. | | **Cloud Sandbox · Default** | Forces the system-managed cloud Sandbox and ignores self-hosted Runners. | | **Self-hosted Environment** | Lists Runners the current member can use. Offline, never-connected, or team-mismatched Runners cannot be selected; Runners in **Degraded** status **remain selectable**, and selecting one shows a "Degraded — you can continue, but responses may be slower" notice. | diff --git a/en/ai-sre/sandbox.mdx b/en/ai-sre/sandbox.mdx index f4326519e..00868f030 100644 --- a/en/ai-sre/sandbox.mdx +++ b/en/ai-sre/sandbox.mdx @@ -50,7 +50,7 @@ The **environment selector** at the bottom of the chat box decides where the ses | Option | Behavior | |---|---| -| **Auto** | The default for new sessions. Prefers an online Runner the current member can use; otherwise **falls back to the cloud sandbox**. | +| **Auto** | The default for new sessions. Tries an online BYOC Runner under the session's bound team, then an online Shared-scope (account-level) Runner, and falls back to the **cloud sandbox** when neither is available. | | **Cloud sandbox · Default** | Forces the cloud sandbox, ignoring all self-hosted Runners. | diff --git a/en/developer/cli.mdx b/en/developer/cli.mdx index bc1353663..c59d6c161 100644 --- a/en/developer/cli.mdx +++ b/en/developer/cli.mdx @@ -842,8 +842,8 @@ The following commands support `--fields` with `json` or `toon` output. Supply c | Command | Structured output when `--fields` is omitted | Limit | | --- | --- | --- | -| `flashduty incident list` | `incident_id`, `title`, `incident_severity`, `progress`, `start_time`, `channel_id` | 16 KiB | -| `flashduty incident similar ` | `incident_id`, `title`, `incident_severity`, `progress`, `start_time`, `close_time`, `ack_time`, `alert_cnt`, `root_cause`, `score` | 16 KiB | +| `flashduty incident list` | `incident_id`, `num`, `title`, `incident_severity`, `progress`, `start_time`, `channel_id`, `detail_url` | 16 KiB | +| `flashduty incident similar ` | `incident_id`, `num`, `title`, `incident_severity`, `progress`, `start_time`, `close_time`, `ack_time`, `alert_cnt`, `root_cause`, `score`, `detail_url` | 16 KiB | | `flashduty incident detail ` | Returns full detail when `--fields` is omitted; otherwise returns only the selected fields | 8 KiB for projections only | | `flashduty alert-event list` | `event_id`, `alert_id`, `event_severity`, `event_status`, `event_time`, `title` | 16 KiB | | `flashduty channel escalate-rule-list ` | `rule_id`, `rule_name`, `status`, `priority`, `filters` | 16 KiB | diff --git a/en/on-call/incident/search-view-incident.mdx b/en/on-call/incident/search-view-incident.mdx index 177078103..8d4be9e38 100644 --- a/en/on-call/incident/search-view-incident.mdx +++ b/en/on-call/incident/search-view-incident.mdx @@ -277,7 +277,7 @@ The change event list displays the following information: | Column | Description | | :--- | :--- | -| **Status** | Current status of the change event, including Planned, Ready, Processing, Canceled, Done | +| **Status** | Current status of the change event, including Planned, Ready, Processing, Canceled, Done, Failed | | **Change Key** | Unique identifier of the change event | | **Title** | Brief description of the change event | | **Description** | Detailed information about the change event | diff --git a/en/on-call/integration/alert-integration/alert-sources/argocd.mdx b/en/on-call/integration/alert-integration/alert-sources/argocd.mdx index 9ba29d4e5..8412f2268 100644 --- a/en/on-call/integration/alert-integration/alert-sources/argocd.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/argocd.mdx @@ -148,7 +148,7 @@ kubectl exec -n argocd deploy/argocd-notifications-controller -- \ /usr/local/bin/argocd admin notifications template notify flashduty-health --recipient flashduty ``` -No error output means Flashduty accepted the request. When the application is `Healthy`, this is a recovery message and creates no alert; in an intermediate state such as `Progressing`, Flashduty ignores it. +The command prints debug logs of the request and response, including the full push URL with its `integration_key`, so do not paste the output anywhere public. A `200 OK` status on the `Received response:` line means Flashduty accepted the request. When the application is `Healthy`, this is a recovery message and creates no alert; in an intermediate state such as `Progressing`, Flashduty ignores it. diff --git a/en/on-call/integration/alert-integration/alert-sources/cfengine.mdx b/en/on-call/integration/alert-integration/alert-sources/cfengine.mdx index 2e1eccd64..145f090e7 100644 --- a/en/on-call/integration/alert-integration/alert-sources/cfengine.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/cfengine.mdx @@ -60,16 +60,16 @@ The script does not parse the parameter file. It sends every `KEY='VALUE'` line 1. Log in to Mission Portal, click **Settings** in the top right, and open **Custom notification scripts** -2. Click **Add script**, upload `flashduty_custom_action.sh`, and enter a name (for example `Flashduty`) and a description +2. Click **Add a script**, upload `flashduty_custom_action.sh`, and enter a name (for example `Flashduty`) and a description 3. Click **Save** -On the **Dashboard**, create an alert or edit an existing one, select the `Flashduty` script uploaded in the previous step in the notification settings, and save. One script can be associated with many alerts; associate it with every alert that should reach Flashduty. +On the **Dashboard**, create an alert or edit an existing one, tick **Custom action** in the notification settings, tick the `Flashduty` script uploaded in the previous step, and save. One script can be associated with many alerts; associate it with every alert that should reach Flashduty. -To keep notifying while an alert stays triggered, choose a reminder interval in the alert's **Remind me** setting. Reminders also run the script, and Flashduty merges them into the existing alert. +To keep notifying while an alert stays triggered, choose a reminder interval after ticking **Set reminders** in the alert. Reminders also run the script, and Flashduty merges them into the existing alert. diff --git a/en/on-call/integration/alert-integration/alert-sources/ghost-inspector.mdx b/en/on-call/integration/alert-integration/alert-sources/ghost-inspector.mdx index d07fc15c7..0b3cf6ab5 100644 --- a/en/on-call/integration/alert-integration/alert-sources/ghost-inspector.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/ghost-inspector.mdx @@ -38,9 +38,10 @@ Ghost Inspector's notification settings have three levels — organization, suit 1. Open the test, its suite, or the organization settings page, whichever level you want to configure -2. Click **Settings → Notifications** -3. Under **Webhooks**, add a new one and paste the full Flashduty push URL (it must include `integration_key`) -4. Save +2. Click **Settings**, then select **Notifications** in the left sidebar +3. Under **Webhooks**, set **Enabled** to **Yes** (the default, **Use suite setting**, sends nothing unless the suite or organization has webhooks on), then click **Add webhook** +4. Paste the full Flashduty push URL (it must include `integration_key`) and keep the delivery option at **Always send**. Flashduty needs both failing and passing results; the other options, **Passing result only** and **Failing result only**, would stop the alert from opening or recovering +5. Click **Save changes** diff --git a/en/on-call/integration/alert-integration/alert-sources/gitguardian.mdx b/en/on-call/integration/alert-integration/alert-sources/gitguardian.mdx index 586e7afe0..fd6704ae6 100644 --- a/en/on-call/integration/alert-integration/alert-sources/gitguardian.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/gitguardian.mdx @@ -37,9 +37,9 @@ You need permission to manage integrations in the GitGuardian workspace. -1. In the GitGuardian dashboard, go to **Settings → Workspace → Integrations → Destinations → Custom webhook** -2. Personal workspace: create a webhook, enter a name, and paste the complete Flashduty integration Push URL as the target URL. The URL must include `integration_key` -3. Business workspace: create the webhook at team level. To receive every incident in the workspace, create it under the **All-incidents team**; to receive only one team's incidents, create it under that team +1. In the GitGuardian dashboard, go to **Settings → Integrations → Destinations → Custom webhook** +2. A webhook belongs to a team. To receive every incident in the workspace, click **Add integration** on the **All-incidents team** row; to receive only one team's incidents, use that team's row +3. On the **Configuration** tab, paste the complete Flashduty integration Push URL into **Webhook URL** (it must include `integration_key`) and click **Next** GitGuardian generates a signature token for the webhook. Flashduty authenticates by the `integration_key` in the Push URL and does not verify the signature, so you do not need to enter the token in Flashduty. @@ -47,22 +47,22 @@ GitGuardian generates a signature token for the webhook. Flashduty authenticates -Select these events: +On the **Events** tab, enter an **Events name**, turn on **Internal monitoring**, and under **Notify when** select these events (or click **Select all**): -| GitGuardian event | `action` | Effect in Flashduty | +| Option in GitGuardian | `action` | Effect in Flashduty | | :--- | :--- | :--- | | New incident detected | `incident_triggered` | Triggers an alert | -| New occurrence detected | `new_occurrence` | Triggers or updates the alert | -| Incident Validity changed | `incident_validity_changed` | Triggers or updates the alert | -| Incident Severity changed | `incident_severity_changed` | Triggers or updates the alert; the severity follows | +| Incident has new occurrence | `new_occurrence` | Triggers or updates the alert | +| Secret validity change | `incident_validity_changed` | Triggers or updates the alert | +| Incident status change → Severity change | `incident_severity_changed` | Triggers or updates the alert; the severity follows | | Risk score updated (Business plan) | `incident_risk_score_updated` | Triggers or updates the alert | | Incident regression | `incident_regression` | Triggers or updates the alert | -| Incident reopened | `incident_reopened` | Triggers or updates the alert | -| Incident resolved | `incident_resolved` | Recovers the alert | -| Incident ignored | `incident_ignored` | Recovers the alert | +| Incident status change → Reopened | `incident_reopened` | Triggers or updates the alert | +| Incident status change → Resolved | `incident_resolved` | Recovers the alert | +| Incident status change → Ignored | `incident_ignored` | Recovers the alert | -You must select **Incident resolved** and **Incident ignored**, or the Flashduty alert does not recover when the incident is handled. +You must select **Resolved** and **Ignored** under **Incident status change**, or the Flashduty alert does not recover when the incident is handled. Assignment, comment, feedback, access, public sharing, and Honeytoken events do not change alert state. Flashduty returns success for them and creates no alert, so you do not need to select them. @@ -75,7 +75,7 @@ To page only for high-risk leaks, add filtering rules to the webhook by severity Trigger a new incident in the workspace and confirm that Flashduty receives an active alert. Then mark the incident **Resolved** in GitGuardian and confirm that the alert recovers. -The test message sent from GitGuardian only verifies that the URL is reachable: Flashduty returns success but creates no alert. +**Send test message** in the webhook's menu (the three dots on its row) only verifies that the URL is reachable: Flashduty returns success but creates no alert. @@ -90,15 +90,15 @@ Changes to severity, validity, occurrence count, or detector name do not change ## Status and severity --- -The alert status follows `action`: `incident_resolved` and `incident_ignored` recover the alert, and every other event in the table above triggers it. A reopened incident triggers a new alert with the same Alert Key. +The alert status follows `action`: `incident_resolved` and `incident_ignored` recover the alert, and every other event in the table above triggers it. A validity, severity, or risk score change on an incident that is already resolved or ignored is ignored and does not re-open the alert. A reopened incident triggers a new alert with the same Alert Key. The severity follows `incident.severity`: | GitGuardian severity | Flashduty severity | | :--- | :--- | -| `high` | Critical | +| `critical`, `high` | Critical | | `medium` | Warning | -| `low` | Info | +| `low`, `info` | Info | | `unknown`, empty, or any other value | Warning | `unknown` means GitGuardian has not rated the incident yet, so Flashduty treats it as Warning. @@ -124,7 +124,7 @@ The severity follows `incident.severity`: --- - **No alert was created**: confirm the matching event is selected and that the webhook's filtering rules do not exclude the incident. GitGuardian states that webhook delivery is best effort and not guaranteed -- **The alert did not recover**: confirm **Incident resolved** and **Incident ignored** are selected +- **The alert did not recover**: confirm **Resolved** and **Ignored** are selected under **Incident status change** - **Flashduty returns an invalid-parameter error**: confirm the target URL is complete and includes `integration_key` - **An ignored incident is reopened**: a new alert is created with the same Alert Key diff --git a/en/on-call/integration/alert-integration/alert-sources/instatus.mdx b/en/on-call/integration/alert-integration/alert-sources/instatus.mdx index 04679217e..85a5ac4f7 100644 --- a/en/on-call/integration/alert-integration/alert-sources/instatus.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/instatus.mdx @@ -54,7 +54,9 @@ One integration can follow several status pages. Alerts from different pages are -Instatus has no button that sends a test notification. To verify: +Saving the subscriber sends a validation delivery right away (the **RUN** button next to the Webhook URL field sends another). Flashduty recognizes it and answers with success, no alert. + +To verify with a real incident instead: 1. In Instatus, go to **Incidents** and click **Add incident**. Set the status to **Investigating**, select an affected component, set it to **Major outage**, then save and notify subscribers. Flashduty shows an incident alert and a component alert, both Critical 2. Add an update to that incident with the status **Resolved**, set the component back to **Operational**, and notify subscribers. Both alerts recover @@ -79,7 +81,8 @@ Instatus sends one JSON payload each time an incident is added or updated, a com | `incident.id` | Incident ID | Alert Key, label `incident_id` | | `incident.name` | Incident name | Alert title | | `incident.status` | Incident status | Alert status, label `incident_status` | -| `incident.impact` | Incident impact | Alert severity, label `impact` | +| `incident.impact` | Incident impact | Label `impact`, informational only: on an incident created through the Instatus dashboard this carries the same word as `status` (e.g. `Investigating`), not an outage severity | +| `incident.affected_components[].status` | Status of each affected component | Alert severity — the worst one across all affected components; used as a fallback only when there are none | | `incident.url` | Incident link | Label `incident_url` | | `incident.incident_updates` | Incident updates | The body of the latest update is the alert description, truncated above 8 KB | @@ -122,15 +125,17 @@ Renaming an incident or component, or changing the impact, does not change the A **Instatus incidents** -The alert severity comes from the impact (`impact`, which takes the same values as component status), and the alert status from the incident status (`status`): +The alert severity is the worst status across the incident's `affected_components` (same values as component status, only differently cased and spaced, e.g. `Major outage`), and the alert status comes from the incident status (`status`): -| Instatus `impact` | Flashduty severity | +| Instatus `affected_components[].status` | Flashduty severity | | :--- | :--- | -| `MAJOROUTAGE` | Critical | -| `PARTIALOUTAGE` | Warning | -| `DEGRADEDPERFORMANCE`, `OPERATIONAL` | Info | +| `Major outage` | Critical | +| `Partial outage` | Warning | +| `Degraded performance`, `Operational` | Info | | Empty or any other value | Warning | +An incident with no affected component falls back to the same mapping applied to `impact` instead — but on a dashboard-created incident, `impact` is usually just the `status` wording (e.g. `Investigating`), which matches none of these values and lands on Warning. + | Instatus `status` | Flashduty status | | :--- | :--- | | `INVESTIGATING`, `IDENTIFIED`, `MONITORING` | Trigger or update the alert | diff --git a/en/on-call/integration/alert-integration/alert-sources/kentik.mdx b/en/on-call/integration/alert-integration/alert-sources/kentik.mdx index d307760f9..c6651faa7 100644 --- a/en/on-call/integration/alert-integration/alert-sources/kentik.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/kentik.mdx @@ -37,8 +37,8 @@ Creating a notification channel requires the Administrator role in Kentik; Membe -1. Log in to the Kentik Portal and go to **Settings** → **Notifications** -2. Click **Add Notification Channel** and set **Type** to **Custom Webhook**. Do not choose the **JSON** type: Flashduty parses the output of the template below +1. Log in to the Kentik Portal and go to **Settings** → **Notification Channels** +2. Click **Add Notification Channel** and set **Type** to **Webhook** (listed as Custom Webhook). Do not choose the **JSON** type: Flashduty parses the output of the template below 3. Fill in the fields as follows: | Field | Value | @@ -47,7 +47,7 @@ Creating a notification channel requires the Administrator role in Kentik; Membe | **Status** | On | | **URL** | The full Flashduty integration push URL, including `integration_key` | | **Custom Headers** | Leave empty | -| **Custom Template** | Paste the template below without renaming any field | +| **Custom Template** | Click **Go to Notification Template Setup** and paste the template below into **TEMPLATE** on the **Template & Preview** tab, without renaming any field | | **Uglify JSON** | Keep the default | ```go-template @@ -75,7 +75,7 @@ Creating a notification channel requires the Administrator role in Kentik; Membe } ``` -4. Click **Add Notification Channel** to save +4. Click **Save** @@ -102,6 +102,7 @@ Do not use this channel for mitigation methods or Insights notifications: these Flashduty uses the Kentik alert ID (`AlarmID`, shown as **Alert ID** in Kentik) as the Alert Key. Every state-change notification of one Kentik alert, from Active to Cleared, carries the same alert ID, so they merge into one alert, and the clear notification closes it. - **Alerts per key**: an alert policy raises a separate alert for each key (one set of values of the policy dimensions) that matches the conditions. Each alert has its own ID, so each is a separate Flashduty alert that recovers on its own +- **Synthetics alerts per agent**: a Synthetics test raises a separate alert, with its own ID, for each test agent. A new failure after an alert clears gets a new alert ID and becomes a new Flashduty alert - Changes to the description, severity, metric values, or times do not change the Alert Key. Events without `AlarmID` are rejected - When one notification carries several events, each event maps to its own alert. A notification with no events is accepted but creates no alert @@ -150,6 +151,6 @@ The alert title is the Kentik event description (`Description`), such as `Alarm - **`AlarmID is required`**: the channel is used for mitigation or Insights notifications, or the template was changed. Use the channel only for alert policies and Synthetics tests - **The alert does not recover**: confirm that the alert is Cleared in Kentik. For policies with **Acknowledgement Required** on, the alert must be acknowledged in Kentik before it can clear (see [Kentik threshold policy settings](https://kb.kentik.com/v1/docs/threshold-policy-settings)) - **One policy creates several alerts**: the policy alerts on each set of dimension values separately; this is expected -- **Test notifications**: the content of the Kentik **Test** / **Test Notification Channels** buttons is defined by Kentik. If it carries an alert ID, Flashduty handles it as a regular alert; close that alert manually in Flashduty +- **Test notifications**: **Send Test Notification** on the **Template & Preview** tab sends mock data whose event description starts with `[TEST]`; Flashduty accepts it and creates no alert. If you first load a real alert with **Enter Alert ID**, the test carries that alert's real state, and Flashduty handles it as a real notification For field details, see [Kentik notification channels](https://kb.kentik.com/docs/notification-channel) and the [Kentik Custom Webhook templating reference](https://github.com/kentik/custom-notification-templates/blob/main/docs/TEMPLATING_REFERENCE.md). diff --git a/en/on-call/integration/alert-integration/alert-sources/langsmith.mdx b/en/on-call/integration/alert-integration/alert-sources/langsmith.mdx index 7ab897581..edef70dd5 100644 --- a/en/on-call/integration/alert-integration/alert-sources/langsmith.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/langsmith.mdx @@ -37,18 +37,18 @@ You can get the integration push URL in either of two ways. -1. Sign in to LangSmith, open the tracing project to monitor, go to the **Alerts** page, and create an alert rule: pick the metric (error count, feedback score, latency or cost), the threshold and the aggregation window (5 or 15 minutes) +1. Sign in to LangSmith, open the tracing project to monitor, go to **Monitoring** → **Alerts** (or the project's monitoring dashboard), click **Alert**, and create an alert rule: pick the metric (**Run Count**, **Cost**, **Errors**, **Feedback Score** or **Latency**), the threshold and the time window (1 to 60 minutes) 2. Under **Notification Settings**, choose **Webhook** and fill in: - **URL**: the full push URL of the Flashduty integration - **Headers**: leave empty - - **Request Body Template**: leave empty. LangSmith merges the fields listed under "Payload" below into the request body as top-level keys; it does no template substitution + - **Body**: leave empty. LangSmith merges the fields listed under "Payload" below into the request body as top-level keys; it does no template substitution 3. Save the alert rule -Click **Send Test Alert**. LangSmith does not validate the receiver's response, so the UI reports success even if Flashduty returns an error; check the Flashduty console for the alert instead. If the test payload has no `alert_rule_id`, Flashduty returns success and creates no alert. If it does carry one, an alert is created; close it manually. +Edit the Webhook action in the alert rule's notification settings and click **Send Test Notification**. LangSmith does not validate the receiver's response, so the UI reports success even if Flashduty returns an error; check the Flashduty console instead. The test payload carries the all-zero UUID `00000000-0000-0000-0000-000000000000` as `alert_rule_id`, and Flashduty returns success without creating an alert. @@ -86,7 +86,7 @@ The alert title is the rule name; if it is empty, `LangSmith alert - + -LangSmith does not validate the receiver's response. Flashduty drops a test payload that has no `alert_rule_id`, which is expected; real alerts are sent only when the metric actually crosses the threshold. +LangSmith does not validate the receiver's response. Flashduty drops a test payload (`alert_rule_id` missing or the all-zero UUID), which is expected; real alerts are sent only when the metric actually crosses the threshold. diff --git a/en/on-call/integration/alert-integration/alert-sources/limacharlie.mdx b/en/on-call/integration/alert-integration/alert-sources/limacharlie.mdx index 93ea25717..5cfe092f1 100644 --- a/en/on-call/integration/alert-integration/alert-sources/limacharlie.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/limacharlie.mdx @@ -40,8 +40,8 @@ You can obtain an integration push URL in either of the following ways. 1. Sign in to LimaCharlie, select the organization, and go to **Outputs** 2. Click **Add Output**. Set **Stream** to **Detections** and **Destination** to **Webhook** (one request per detection; do not choose Webhook Bulk) 3. Set **Name** to `flashduty` -4. Paste the complete Flashduty Push URL, including the `integration_key` parameter, into **dest_host** -5. Enter any string as **secret_key**. LimaCharlie uses it to compute the `lc-signature` request header. Flashduty does not verify that header +4. Paste the complete Flashduty Push URL, including the `integration_key` parameter, into **DESTINATION HOST** +5. Enter any string as **SECRET KEY**. LimaCharlie uses it to compute the `lc-signature` request header. Flashduty does not verify that header After you save, LimaCharlie sends one POST to this URL for every detection in the organization. The body is the LimaCharlie detection JSON. @@ -55,7 +55,7 @@ The webhook output forwards detections only. Confirm that the organization has e -LimaCharlie suggests testing an output on the **Audit** stream first. Temporarily set **Stream** to **Audit**, then edit the output to trigger an audit event. Flashduty returns 200 for requests that are not detections and creates no alert, so this step only proves the URL is reachable. Set **Stream** back to **Detections** afterwards. +The stream of an output can only be chosen when the output is created and cannot be changed afterwards. To check that the URL is reachable first, create a separate test output: set **Stream** to **Audit Logs**, **Destination** to **Webhook**, and **DESTINATION HOST** to the same Push URL. Then make a management change in the organization (for example, disable and re-enable a D&R rule) to trigger an audit event. Flashduty returns 200 for requests that are not detections and creates no alert, so this step only proves the URL is reachable. Delete the test output when you are done. For an end-to-end check, let a D&R rule match once and confirm the alert arrives in Flashduty. @@ -103,13 +103,13 @@ A detection is a one-shot event and LimaCharlie sends no recovery. In the channe -LimaCharlie disables a failing output for a while and re-enables it automatically. Editing the output configuration re-enables it immediately. Check that `dest_host` is the complete Push URL, and look at the `outputs/` entry under Errors in LimaCharlie Platform Logs for details. +LimaCharlie disables a failing output for a while and re-enables it automatically. Editing the output configuration re-enables it immediately. Check that **DESTINATION HOST** is the complete Push URL, and look at the `outputs/` entry under Errors in LimaCharlie Platform Logs for details. -Confirm that the output stream is **Detections** and that you chose **Webhook**, not Webhook Bulk. Requests from the Audit, Event, and Deployment streams are accepted by Flashduty but create no alert. +Confirm that the output stream is **Detections** and that you chose **Webhook**, not Webhook Bulk. Requests from the Audit Logs, Events, and Deployments streams are accepted by Flashduty but create no alert. diff --git a/en/on-call/integration/alert-integration/alert-sources/logrocket.mdx b/en/on-call/integration/alert-integration/alert-sources/logrocket.mdx index 690b11d67..7728f7d33 100644 --- a/en/on-call/integration/alert-integration/alert-sources/logrocket.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/logrocket.mdx @@ -35,10 +35,10 @@ You can obtain an integration push URL in either of the following ways. -1. In LogRocket, open the dashboard you want to alert on and create or edit a **Timeseries** chart (alerts are supported only on this chart type) -2. In the chart's alert settings, add an alert and choose the **Webhook** type -3. Paste the full Flashduty push URL, including `integration_key`, as the target URL -4. Set the trigger rule: the comparison (greater than or less than), the threshold, and the time interval to evaluate, then save the chart +1. In LogRocket, open **Analytics → Timeseries**, build the chart you want to alert on, and click **Save** (alerts are supported only on saved Timeseries charts) +2. Click **Alerts → Create Alert** at the top right of the chart, and enter an **Alert name** +3. Under **Trigger alert when**, set the comparison (**greater than** or **less than**), the threshold, and the time window, for example "Session count is less than 1 sessions within 5 minutes" +4. Under **Send alert via**, select **Webhook**, paste the full Flashduty push URL, including `integration_key`, into the **Webhook** field, and click **Save Alert** An account can have up to 100 alerts, all managed on the **Alerts** page in Settings. @@ -83,7 +83,7 @@ The LogRocket webhook carries no severity, and a metric crossing a threshold is | `threshold` / `threshold_unit` | Threshold and its unit | | `interval` / `interval_unit` | Evaluation interval and its unit (`MINUTES` or `HOURS`) | -The alert title and description come from `reason`, the text LogRocket generates from the alert settings. Without `reason` the title is `LogRocket alert `. +The alert title and description come from `reason`, which LogRocket fills with the alert name you entered. Without `reason` the title is `LogRocket alert `. ## Troubleshooting --- diff --git a/en/on-call/integration/alert-integration/alert-sources/obkio.mdx b/en/on-call/integration/alert-integration/alert-sources/obkio.mdx index 2e6807ed8..567c64f26 100644 --- a/en/on-call/integration/alert-integration/alert-sources/obkio.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/obkio.mdx @@ -37,11 +37,11 @@ The webhook is configured at the organization level and requires permission to c -1. In Obkio, click **Menu → your organization name → Change Organization's Advanced Parameters** -2. Find **Webhooks settings** and make sure **Webhook Type** is set to `Obkio` +1. In Obkio, click **More** (bottom left) **→ your organization name → Change Organization's Advanced Parameters** +2. Find **Webhooks Settings** and make sure **Webhook Type** is set to `Obkio` 3. Paste the full Flashduty push URL into **Webhook URL**; it must include `integration_key` -4. **Webhook Secrets** can stay empty; Flashduty does not verify signatures -5. Click **Save** +4. **Webhook Secret** can stay empty; Flashduty does not verify signatures +5. This page has no Save button. The value is saved when the field loses focus (for example, click an empty area of the page). Reload the page to confirm **Webhook URL** is still set diff --git a/en/on-call/integration/alert-integration/alert-sources/statuspal.mdx b/en/on-call/integration/alert-integration/alert-sources/statuspal.mdx index e404c830f..01fe3f7d9 100644 --- a/en/on-call/integration/alert-integration/alert-sources/statuspal.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/statuspal.mdx @@ -76,7 +76,7 @@ Statuspal pushes JSON. The `event` field is the event type, and `data.object` is | Field | Description | Use in Flashduty | | :--- | :--- | :--- | | `data.object.id` | Incident ID | Alert Key, label `incident_id` | -| `data.object.l_title` | Incident title in each language | Alert title (English first, otherwise the first title) | +| `data.object.l_title` | Incident title in each language | Alert title (English first, otherwise the first title; falls back to `data.object.title` when neither is present) | | `data.object.ends_at` | Incident end time | Recovers the alert when set, label `ends_at` | | `data.object.starts_at` | Incident start time | Label `starts_at` | | `data.object.service_ids` | IDs of the affected services | Label `service_ids` (comma-separated) | diff --git a/en/on-call/integration/alert-integration/alert-sources/stripe.mdx b/en/on-call/integration/alert-integration/alert-sources/stripe.mdx index f727fabc1..99141628a 100644 --- a/en/on-call/integration/alert-integration/alert-sources/stripe.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/stripe.mdx @@ -43,7 +43,7 @@ You can get the integration push URL in either of the following ways. You need a Stripe role that can manage webhooks, such as Administrator or Developer. -1. Sign in to the Stripe Dashboard, open the [Webhooks](https://dashboard.stripe.com/webhooks) tab in Workbench, and click **Create an event destination** +1. Sign in to the Stripe Dashboard, open the [Webhooks](https://dashboard.stripe.com/webhooks) tab in Workbench, and click **Add destination** 2. For **Events from**, select **Your account**. If you run a Connect platform and want events from connected accounts, select **Connected accounts** (create one destination for each scope if you need both) 3. Keep the default **API version**. If you are asked to choose an event payload style, choose **Snapshot**: thin events do not contain the object, so Flashduty cannot parse them @@ -71,7 +71,7 @@ If the destination subscribes to other event types (for example `charge.succeede 1. Click **Continue** and select **Webhook endpoint** as the destination type 2. For **Endpoint URL**, enter the full Flashduty push URL -3. Finish creating the destination. Flashduty does not use the signing secret (starting with `whsec_`) shown on the endpoint page, so you do not need to copy it +3. Optionally enter a **Destination name**, then click **Create destination**. Flashduty does not use the signing secret (starting with `whsec_`) shown on the endpoint page, so you do not need to copy it Webhook endpoints in test environments (sandbox or test mode) and in live mode are separate. To connect both, create an endpoint in each environment; they can use the same push URL. @@ -79,11 +79,12 @@ Webhook endpoints in test environments (sandbox or test mode) and in live mode a -Stripe has no "send test notification" button. Create real test events in a test environment in any of these ways: +The **Send test events** button on the destination page only shows Stripe CLI instructions and sends nothing. Create real test events in a test environment in any of these ways: - Run `stripe trigger charge.dispute.created` with the [Stripe CLI](https://docs.stripe.com/cli) - Pay with test card `4000000000000259`: the payment succeeds and is then disputed as fraudulent. Pay with `4000000000005423` to receive an early fraud warning -- Submit `winning_evidence` as the dispute evidence: the dispute closes as won and Flashduty recovers the alert +- Submit `winning_evidence` (or `losing_evidence`) as the dispute evidence: the dispute closes as won (or lost) and Flashduty recovers the alert. Fully refund the early-fraud-warning payment: Stripe sends `radar.early_fraud_warning.updated` with `actionable` set to `false` and Flashduty recovers the alert +- `payout.failed` needs a failed payout. A sandbox does not accept test bank accounts in its own payout settings; on a Connect platform, pay out from a test connected account whose bank account uses account number `000111111116`, with a destination that receives **Connected accounts** events Test events have `livemode` set to `false`. Flashduty creates alerts for them as usual and adds the label `livemode=false`. diff --git a/en/on-call/integration/alert-integration/alert-sources/tideways.mdx b/en/on-call/integration/alert-integration/alert-sources/tideways.mdx index e967315e3..c7b30e738 100644 --- a/en/on-call/integration/alert-integration/alert-sources/tideways.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/tideways.mdx @@ -4,7 +4,7 @@ description: "Send Tideways response time, error rate, missing data, exception, keywords: ["alert integration", "Tideways", "PHP", "APM", "webhook"] --- -Use the organization-level Webhook integration in Tideways to send performance and error notifications from your PHP applications to Flashduty On-call. Response time and error rate incidents have a full lifecycle: an alert triggers when the incident opens, updates while it continues, and recovers when it closes. Transaction failure rate and missing data notifications are sent once when they occur and never recover. An exception or slow SQL alert recovers when its error group is resolved or ignored in Tideways. +Use the organization-level Webhook integration in Tideways to send performance and error notifications from your PHP applications to Flashduty On-call. Response time and error rate incidents have a full lifecycle: an alert triggers when the incident opens, updates while it continues, and recovers when it closes. Transaction failure rate and missing data notifications are sent once when they occur and never recover. Exception and slow SQL notifications are sent when an error group is new, reopened, or reappears; Tideways sends nothing when the group is resolved, so those alerts do not recover automatically.
@@ -39,32 +39,33 @@ You need admin permission on the organization. The Tideways webhook only accepts 1. Open the organization's **Integrations** settings, click **Add New Integration**, and select **Webhook** 2. Enter a name and paste the full Flashduty push URL, including `integration_key`, as the URL -3. Save +3. Under the trigger options, tick **and when the alert is fixed**. It is off by default; without it Tideways sends no `closed` notification and incident alerts never recover in Flashduty +4. Save -Open the application's **Project Settings → Configure Notifications** and select the new webhook integration for each notification type that should page someone. The table shows how Flashduty handles each type. +Open the application's **Project Settings → Notifications**. For each notification rule that should page someone, click **Edit**, tick the new webhook integration, and save (use **Create Notification Rule** to add a rule type that is not listed yet). The table shows how Flashduty handles each type. -| Tideways notification | `type` | Effect in Flashduty | +| Tideways notification rule | `type` | Effect in Flashduty | | :--- | :--- | :--- | -| Response Time | `response_time` | Trigger, update, recover | -| Failure Rate | `error_rate` | Trigger, update, recover | -| Transaction response time | `transaction-response-time` | Trigger, update, recover | -| Transaction failure rate | `transaction-failure-rate` | Trigger (no recovery) | -| Missing Data | `missing-data` | Trigger (no recovery) | -| New exception | `exception` | Trigger (no recovery) | -| New slow SQL | `slow-sql` | Trigger (no recovery) | -| Weekly report, release, release comparison | `weekly_report`, `release`, `compare_release` | Acknowledged only, no alert | +| Service Response Time | `response_time` | Trigger, update, recover | +| Service Failure Rate | `error_rate` | Trigger, update, recover | +| Transaction Response Times | `transaction-response-time` | Trigger, update, recover | +| Transaction Failure Rates | `transaction-failure-rate` | Trigger (no recovery) | +| Heartbeat Monitoring | `missing-data` | Trigger (no recovery) | +| New Error/Exception | `exception` | Trigger (no recovery) | +| New Slow SQL Query | `slow-sql` | Trigger (no recovery) | +| Weekly Performance Report, New Release, release comparison | `weekly_report`, `release`, `compare_release` | Acknowledged only, no alert | -Push the application's response time above its threshold and confirm Flashduty receives an active alert. After the metric falls back and Tideways closes the incident, confirm the same alert recovers. +Push the application's response time above its threshold and confirm Flashduty receives an active alert. An incident opens once the value has exceeded the threshold over the rule's check period (5 to 60 minutes). After the metric falls back and Tideways closes the incident, confirm the same alert recovers. -The Tideways documentation does not say what the **Preview** button on the integration page sends. Its sample notification has the same shape as a real one, so Flashduty creates an alert for it as listed above. Close it manually after testing. +The **Preview** button on the integration page sends one `response_time` notification with status `opened` and a placeholder incident ID. Flashduty creates a Warning alert for it, and no `closed` notification follows, so close it manually after testing. @@ -79,7 +80,7 @@ Other types use their own object: - New exceptions and slow SQL: the error group ID (`notification.error_group.id`). A group that appears again merges into the same alert - Transaction failure rate and missing data: the organization, application, environment (`environment`), service (`service`), and transaction (`transaction`). The same check firing again merges into the same alert -Changes to the value, time, threshold, or occurrence count never change the Alert Key. A notification whose error group status is `resolved`, `not_error`, or `ignored` recovers the alert of that group. +Changes to the value, time, threshold, or occurrence count never change the Alert Key. An error group notification with status `resolved`, `not_error`, or `ignored` recovers the alert of that group. The exception rule only notifies for new, reappeared, reopened, and unacknowledged errors, so in practice a resolved group produces no notification; a reopened group merges into its existing alert. ## Status and severity --- @@ -98,7 +99,7 @@ When `status` is `closed`, or an error group is `resolved`, `not_error`, or `ign ## When alerts do not recover --- -Transaction failure rate and missing data notifications are sent once, and Tideways sends no matching recovery, so these alerts do not recover automatically. Exception and slow SQL alerts recover when the error group is resolved or ignored, if Tideways sends that notification. +Transaction failure rate and missing data notifications are sent once, and Tideways sends no matching recovery, so these alerts do not recover automatically. Exception and slow SQL alerts also stay active after the error group is resolved or ignored in Tideways, because Tideways sends no notification for that. Turn on [auto-close](/en/on-call/channel/create-edit) for the channel, with the timer starting from **Incident triggered** and a suggested duration of 24 hours. Missing data and new exceptions are normally handled within a working day. If the channel only receives response time and failure rate notifications, you can leave it off. @@ -120,7 +121,7 @@ Turn on [auto-close](/en/on-call/channel/create-edit) for the channel, with the - **Tideways shows a delivery failure**: confirm the URL uses HTTPS and includes `integration_key`. Tideways does not retry, and a response with status 400 or higher is only recorded in the integration's error log - **Flashduty returns an invalid-parameter error**: the message names the missing field (for example `notification.incident_id`) or the unsupported `type` -- **An alert did not recover**: response time, failure rate, and transaction response time incidents recover on `closed`, and exceptions and slow SQL recover when their error group is resolved or ignored in Tideways; turn on auto-close for transaction failure rate and missing data +- **An alert did not recover**: response time, failure rate, and transaction response time incidents recover on `closed`, and turn on auto-close for exceptions, slow SQL, transaction failure rate, and missing data. If incident alerts stay active after Tideways closes the incident, check that **and when the alert is fixed** is ticked on the webhook integration - **A weekly report or release notification created no alert**: these are not incidents, so Flashduty only acknowledges them For field details, see the [Tideways webhook documentation](https://support.tideways.com/documentation/reference/integrations/webhook.html). diff --git a/en/on-call/integration/alert-integration/alert-sources/wormly.mdx b/en/on-call/integration/alert-integration/alert-sources/wormly.mdx index 886cb5fee..d5a6a3a33 100644 --- a/en/on-call/integration/alert-integration/alert-sources/wormly.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/wormly.mdx @@ -35,7 +35,7 @@ You can get the integration push URL in either of the following ways. -1. Sign in to Wormly, go to **Contacts**, and click **Create a new contact** +1. Sign in to Wormly, go to **Contacts**, and click **Create New Contact** 2. Choose the **Webhook** channel 3. Paste the full Flashduty push URL into the URL field 4. Choose a JSON webhook type (`JSON` or `JSON - multipart/form encoding`; Flashduty parses both). Do not choose XML or Serialized PHP @@ -108,7 +108,7 @@ No. While a host stays down, each notification sent at an escalation level carri -Wormly's documentation does not describe the test notification. Flashduty acknowledges an empty JSON object, which has none of the known fields, and creates no alert. If the test notification carries a sample `hostid`, it creates an alert keyed on that `hostid`, which you can close manually in Flashduty. +The contact form's **Send Test** button always posts a trigger notification with a sample `hostid` (`5112`), so it opens an alert keyed on `5112`. No recovery notification follows a test, so close that alert manually in Flashduty. An empty JSON object with none of the known fields is acknowledged without creating an alert. diff --git a/en/on-call/integration/change-integration/argo-rollouts.mdx b/en/on-call/integration/change-integration/argo-rollouts.mdx new file mode 100644 index 000000000..4d13ff3d1 --- /dev/null +++ b/en/on-call/integration/change-integration/argo-rollouts.mdx @@ -0,0 +1,268 @@ +--- +title: "Argo Rollouts change integration" +description: "Sync Argo Rollouts releases to Flashduty On-call through the built-in Argo Rollouts Notifications webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Argo Rollouts", "Rollout", "canary", "blue-green", "progressive delivery", "Notifications", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +The Argo Rollouts controller has built-in **Notifications** (based on Argo's notifications-engine) that send messages while a Rollout progresses. This integration provides an `argo-rollouts-notification-configmap` configuration with one webhook service, four request body templates, and four triggers. Each pod template change of a Rollout (a new release revision) becomes one Flashduty change: it is recorded as Processing when the new revision starts rolling out, updated to Done when the rollout completes, and updated to Failed when it is aborted. + +Both the canary and blue-green strategies are recorded. Analysis run failures, pod replica changes, and other Rollout events are not changes and are not recorded. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Argo Rollouts** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `rollout`, `namespace`, or `strategy` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Argo Rollouts +--- + +The steps below need Kubernetes permission to edit ConfigMaps in the Argo Rollouts controller namespace (`argo-rollouts` by default) and to edit annotations on Rollouts. The Argo Rollouts controller must be able to reach the domain of the push URL. + + + + +Save the following as `flashduty-change.yaml` and replace `url` with the push URL copied above (including `?integration_key=...`): + +```yaml +data: + service.webhook.flashduty-change: | + url: + headers: + - name: Content-Type + value: application/json + + template.flashduty-change-updated: | + webhook: + flashduty-change: + method: POST + body: | + { + "event": "updated", + "event_time": {{ now | unixEpoch }}, + "rollout_uid": {{ .rollout.metadata.uid | toJson }}, + "name": {{ .rollout.metadata.name | toJson }}, + "namespace": {{ .rollout.metadata.namespace | toJson }}, + "revision": {{ dig "metadata" "annotations" "rollout.argoproj.io/revision" "" .rollout | toJson }}, + "strategy": {{ if dig "spec" "strategy" "blueGreen" "" .rollout }}"blueGreen"{{ else }}"canary"{{ end }}, + "images": [{{ range $i, $c := .rollout.spec.template.spec.containers }}{{ if $i }}, {{ end }}{{ $c.image | toJson }}{{ end }}] + } + + template.flashduty-change-completed: | + webhook: + flashduty-change: + method: POST + body: | + { + "event": "completed", + "event_time": {{ now | unixEpoch }}, + "rollout_uid": {{ .rollout.metadata.uid | toJson }}, + "name": {{ .rollout.metadata.name | toJson }}, + "namespace": {{ .rollout.metadata.namespace | toJson }}, + "revision": {{ dig "metadata" "annotations" "rollout.argoproj.io/revision" "" .rollout | toJson }}, + "strategy": {{ if dig "spec" "strategy" "blueGreen" "" .rollout }}"blueGreen"{{ else }}"canary"{{ end }}, + "images": [{{ range $i, $c := .rollout.spec.template.spec.containers }}{{ if $i }}, {{ end }}{{ $c.image | toJson }}{{ end }}] + } + + template.flashduty-change-aborted: | + webhook: + flashduty-change: + method: POST + body: | + { + "event": "aborted", + "event_time": {{ now | unixEpoch }}, + "rollout_uid": {{ .rollout.metadata.uid | toJson }}, + "name": {{ .rollout.metadata.name | toJson }}, + "namespace": {{ .rollout.metadata.namespace | toJson }}, + "revision": {{ dig "metadata" "annotations" "rollout.argoproj.io/revision" "" .rollout | toJson }}, + "strategy": {{ if dig "spec" "strategy" "blueGreen" "" .rollout }}"blueGreen"{{ else }}"canary"{{ end }}, + "images": [{{ range $i, $c := .rollout.spec.template.spec.containers }}{{ if $i }}, {{ end }}{{ $c.image | toJson }}{{ end }}] + } + + template.flashduty-change-skip-steps: | + webhook: + flashduty-change: + method: POST + body: | + { + "event": "skip_steps", + "event_time": {{ now | unixEpoch }}, + "rollout_uid": {{ .rollout.metadata.uid | toJson }}, + "name": {{ .rollout.metadata.name | toJson }}, + "namespace": {{ .rollout.metadata.namespace | toJson }}, + "revision": {{ dig "metadata" "annotations" "rollout.argoproj.io/revision" "" .rollout | toJson }}, + "strategy": {{ if dig "spec" "strategy" "blueGreen" "" .rollout }}"blueGreen"{{ else }}"canary"{{ end }}, + "images": [{{ range $i, $c := .rollout.spec.template.spec.containers }}{{ if $i }}, {{ end }}{{ $c.image | toJson }}{{ end }}] + } + + trigger.on-rollout-updated: | + - send: [flashduty-change-updated] + + trigger.on-rollout-completed: | + - send: [flashduty-change-completed] + + trigger.on-rollout-aborted: | + - send: [flashduty-change-aborted] + + trigger.on-skip-steps: | + - send: [flashduty-change-skip-steps] +``` + +Merge it into `argo-rollouts-notification-configmap` (`--type merge` only adds or updates the keys above and leaves existing configuration alone): + +```bash +kubectl patch configmap argo-rollouts-notification-configmap -n argo-rollouts --type merge --patch-file flashduty-change.yaml +``` + +If the ConfigMap does not exist yet, first run `kubectl create configmap argo-rollouts-notification-configmap -n argo-rollouts`. If Argo Rollouts is installed with a Helm chart, put the same service, templates, and triggers into the chart's notifications configuration; otherwise the next upgrade overwrites the manual change. + +Notes: + +- Argo Rollouts derives a trigger's name from the Kubernetes event reason: `on-rollout-updated`, `on-rollout-completed`, `on-rollout-aborted`, and `on-skip-steps` fire on the matching event, so the trigger names cannot be changed and have no `when` condition +- The `event` value in each template is fixed; Flashduty uses it to tell what happened, so do not change it +- Every value in the templates is escaped with `toJson`; do not remove it. Do not rename the fields; `event`, `event_time`, `rollout_uid`, and `revision` must stay +- `event_time` is the controller's time when it sends the notification (Unix seconds); Flashduty uses it to apply status updates in order +- The service name `flashduty-change` can be changed, but the subscription annotations and the key under `webhook:` in the templates must match it + + +If you installed Argo Rollouts' `notifications-install.yaml`, the triggers `on-rollout-updated`, `on-rollout-completed`, and `on-rollout-aborted` already exist (each is a single line such as `- send: [rollout-updated]`). The configuration above overwrites them, and existing Slack or email subscriptions stop receiving notifications. Keep the existing templates and write the triggers as below; the two templates are merged when sent, and each notification service uses only its own part: + +```yaml + trigger.on-rollout-updated: | + - send: [rollout-updated, flashduty-change-updated] + trigger.on-rollout-completed: | + - send: [rollout-completed, flashduty-change-completed] + trigger.on-rollout-aborted: | + - send: [rollout-aborted, flashduty-change-aborted] +``` + +`on-skip-steps` is not a built-in trigger; use it as written above. + + + + + + +A trigger sends only when it is subscribed. Choose a scope: + +- **A single Rollout**: add four annotations to the Rollout + + ```bash + kubectl annotate rollout -n \ + 'notifications.argoproj.io/subscribe.on-rollout-updated.flashduty-change=' \ + 'notifications.argoproj.io/subscribe.on-rollout-completed.flashduty-change=' \ + 'notifications.argoproj.io/subscribe.on-rollout-aborted.flashduty-change=' \ + 'notifications.argoproj.io/subscribe.on-skip-steps.flashduty-change=' + ``` + +- **All Rollouts**: add an entry to `subscriptions` in `argo-rollouts-notification-configmap`. If `subscriptions` already exists, append to the existing list instead of overwriting it with the merge command from the previous step + + ```yaml + subscriptions: | + - recipients: + - flashduty-change + triggers: + - on-rollout-updated + - on-rollout-completed + - on-rollout-aborted + - on-skip-steps + ``` + +Subscribe all four triggers together: with only the start event subscribed, changes stay in Processing. + + + + + +Argo Rollouts has no way to send a test message. Change the image of a subscribed Rollout (for example `kubectl argo rollouts set image =`) and confirm that a Processing change appears in the Flashduty change list, then updates to Done when the rollout completes (or after you promote it through the last step). + + + + +## What one change is +--- + +One change is one release revision of one Rollout. The change key (change_key) is `/`: + +- `rollout_uid` is the Rollout's `metadata.uid`. The UID Kubernetes assigns to each object is unique for the whole life of the cluster, so a Rollout with the same name in another cluster, or a Rollout deleted and recreated, is a different Rollout +- `revision` is the Rollout's `rollout.argoproj.io/revision` annotation. Every pod template change, including a rollback to an older version, increases the revision by 1 + +So the start, completion, and abort of one revision update the same change; two releases of the same Rollout are two changes, and a rollback is a new change. Creating a Rollout that already carries the subscription annotations also records a change for revision 1 (Processing, then Done once it is available). Changes that do not alter the pod template, such as replica count or rollout steps, create no new revision and record no change. + +Flashduty rejects a request that lacks `event`, `rollout_uid`, `revision`, or `event_time`. + +## Status mapping +--- + +| Trigger | Event (`event`) | Meaning | Flashduty change status | +|---|---|---|---| +| `on-rollout-updated` | `updated` | A new release revision starts (including a Rollout's first creation) | Processing | +| `on-rollout-completed` | `completed` | The new revision was promoted to stable | Done | +| `on-skip-steps` | `skip_steps` | Rollback to the stable revision or to a revision inside the rollback window; steps are skipped | Done | +| `on-rollout-aborted` | `aborted` | The rollout was aborted: `kubectl argo rollouts abort`, a failed analysis, or the progress deadline (`progressDeadlineAbort`) | Failed | + +Done and Failed are end states; Flashduty records the change's end time. `event` values are case-sensitive, and other values are rejected. + +- When it rolls back to the stable revision, Argo Rollouts emits only `SkipSteps` and no `RolloutCompleted`, so `on-skip-steps` is also recorded as Done +- A blue-green release waiting for a manual promote, or a canary release stopped at a pause step, stays in Processing +- After an abort, if you run `kubectl argo rollouts retry` and the rollout eventually completes, the same change is updated from Failed to Done + +## Change content +--- + +- **Title**: `/: rollout revision ()`; images of several containers are comma-separated, and the parenthesized part is omitted when there are none +- **Link**: Argo Rollouts has no web page for a single release, so changes have no link + +Labels can be used for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `rollout` | Rollout name | +| `namespace` | Namespace of the Rollout | +| `rollout_uid` | The Rollout's `metadata.uid` | +| `revision` | Revision number of the release | +| `strategy` | Rollout strategy, `canary` or `blueGreen` | +| `image` | Images of the containers, comma-separated; truncated beyond 1024 bytes | +| `event` | Latest event: `updated`, `completed`, `skip_steps`, or `aborted` | + +## FAQ +--- + + + + +- Check the Argo Rollouts controller logs (`kubectl logs -n argo-rollouts deploy/argo-rollouts`) and confirm the Rollout has a `notifications.argoproj.io/subscribe..flashduty-change` annotation, or that `subscriptions` contains the trigger +- If the logs show `template 'flashduty-change-updated' is not supported`, confirm the configuration was written to `argo-rollouts-notification-configmap`; for Helm installs, check the corresponding values +- A Rollout whose pod template did not change creates no new revision, so there is no notification + + + + + +Not all four triggers are subscribed, or the release has not finished (a blue-green release waiting for a promote, or a canary release stopped at a pause step). Deleting a Rollout does not update its change. + + + + + +No. A notification with the same event and the same time is recorded once. + + + + + +Confirm the templates match this page. The response names the missing or unsupported field, for example `rollout_uid is missing`, `revision is missing`, or `unsupported event`. + + + + +For the related configuration, see the Argo Rollouts documentation on [Notifications](https://argo-rollouts.readthedocs.io/en/stable/features/notifications/), and the notifications-engine [Webhook](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/services/webhook/) service, [Triggers](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/triggers/), and [Templates](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/templates/). diff --git a/en/on-call/integration/change-integration/argocd.mdx b/en/on-call/integration/change-integration/argocd.mdx new file mode 100644 index 000000000..4fd9bf6d8 --- /dev/null +++ b/en/on-call/integration/change-integration/argocd.mdx @@ -0,0 +1,220 @@ +--- +title: "Argo CD change integration" +description: "Sync Argo CD application sync operations to Flashduty On-call through an Argo CD Notifications webhook service, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Argo CD", "ArgoCD", "GitOps", "Sync", "Notifications", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Argo CD pushes changes through its built-in **Notifications** (`argocd-notifications-controller`). This integration provides an `argocd-notifications-cm` configuration with one webhook service, one request body template, and one trigger. Each sync operation of an Argo CD Application becomes one Flashduty change: it is recorded as Processing when the sync starts and updated to Done, Failed, or Canceled when it ends. + +Automated syncs, manual syncs from the UI or CLI, and rollbacks are all sync operations and are all recorded. For sync-failed and health-degraded alerts, use the Argo CD alert integration; both integrations can be configured side by side. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Argo CD** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `application`, `project`, or `destination_namespace` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Argo CD +--- + +The steps below need Kubernetes permission to edit ConfigMaps in the Argo CD namespace (`argocd` by default) and to edit annotations on Applications or AppProjects. The Argo CD cluster must be able to reach the domain of the push URL. + + + + +Save the following as `flashduty-change.yaml` and replace `url` with the push URL copied above (including `?integration_key=...`): + +```yaml +data: + service.webhook.flashduty-change: | + url: + headers: + - name: Content-Type + value: application/json + + template.flashduty-change: | + webhook: + flashduty-change: + method: POST + body: | + { + "app_uid": {{ .app.metadata.uid | toJson }}, + "app_name": {{ .app.metadata.name | toJson }}, + "app_namespace": {{ .app.metadata.namespace | toJson }}, + "project": {{ .app.spec.project | toJson }}, + "destination": {{ dig "spec" "destination" "name" (dig "spec" "destination" "server" "" .app) .app | toJson }}, + "destination_namespace": {{ dig "spec" "destination" "namespace" "" .app | toJson }}, + "argocd_url": {{ .context.argocdUrl | toJson }}, + "phase": {{ dig "status" "operationState" "phase" "" .app | toJson }}, + "message": {{ dig "status" "operationState" "message" "" .app | toJson }}, + "started_at": {{ dig "status" "operationState" "startedAt" "" .app | toJson }}, + "finished_at": {{ dig "status" "operationState" "finishedAt" "" .app | toJson }}, + "revision": {{ dig "status" "operationState" "syncResult" "revision" (dig "status" "operationState" "operation" "sync" "revision" "" .app) .app | toJson }}, + "initiated_by": {{ dig "status" "operationState" "operation" "initiatedBy" "username" "" .app | toJson }}, + "automated": {{ dig "status" "operationState" "operation" "initiatedBy" "automated" false .app | toJson }}, + "dry_run": {{ dig "status" "operationState" "operation" "sync" "dryRun" false .app | toJson }} + } + + trigger.on-flashduty-change: | + - when: app.status.operationState != nil and app.status.operationState.phase in ['Running'] + oncePer: app.status.operationState?.startedAt + send: [flashduty-change] + - when: app.status.operationState != nil and app.status.operationState.phase in ['Succeeded', 'Failed', 'Error'] + oncePer: app.status.operationState?.startedAt + send: [flashduty-change] +``` + +Merge it into the existing `argocd-notifications-cm` (`--type merge` only adds or updates the keys above and leaves the rest of the configuration alone): + +```bash +kubectl patch configmap argocd-notifications-cm -n argocd --type merge --patch-file flashduty-change.yaml +``` + +If Argo CD is installed with the Helm chart, put `service.webhook.flashduty-change` under `notifications.notifiers`, the template under `notifications.templates`, and the trigger under `notifications.triggers`; otherwise the next upgrade overwrites manual edits. + +Notes: + +- Every value in the template is escaped with `toJson`, so quotes and line breaks in sync messages cannot break the JSON. Do not remove it. Do not rename fields; `app_uid`, `phase`, and `started_at` are required +- Optional fields are read with `dig`, so the template renders even when the application has never synced or the sync has no result yet +- The two trigger conditions cover the start and the end of a sync. `oncePer` is the sync operation's start time, so the start and the end of every sync operation are each sent once, even when Argo CD does not observe the state between two consecutive syncs. Do not remove it +- The service name `flashduty-change` differs from `flashduty` used by the alert integration, so the two integrations' push URLs do not interfere +- `argocd_url` comes from `context.argocdUrl` in `argocd-notifications-cm` and is used to build the change link. Without it, changes have no link but are still recorded + + + + + +A trigger sends only after it is subscribed. Choose one scope: + +- **One application**: add an annotation to the Application + + ```bash + kubectl patch application -n argocd --type merge \ + -p '{"metadata":{"annotations":{"notifications.argoproj.io/subscribe.on-flashduty-change.flashduty-change":""}}}' + ``` + +- **All applications in a project**: add the same annotation `notifications.argoproj.io/subscribe.on-flashduty-change.flashduty-change: ""` to the AppProject's `metadata.annotations` +- **All applications**: add an entry to `subscriptions` in `argocd-notifications-cm`. If `subscriptions` already exists (for example the entry added by the alert integration), append to the existing list instead of overwriting it with the merge command above + + ```yaml + subscriptions: | + - recipients: + - flashduty-change + triggers: + - on-flashduty-change + ``` + +When the subscription takes effect, each application that has synced before immediately sends the result of its latest sync, and Flashduty records it as one change with that sync's original start and end times. + + + + + +Argo CD has no button for sending a test message. From the `argocd-notifications-controller` Pod, use `argocd admin notifications template notify` to send one notification based on the application's current state: + +```bash +kubectl exec -n argocd deploy/argocd-notifications-controller -- \ + /usr/local/bin/argocd admin notifications template notify flashduty-change --recipient flashduty-change +``` + +The command prints debug logs of the request and response, including the full push URL with its `integration_key`, so do not paste the output anywhere public. A `200 OK` status on the `Received response:` line means Flashduty accepted the request. For an application that has synced before, this notification is the result of its latest sync and merges into that sync's existing record without adding a change; for an application that has never synced, Flashduty ignores it. + + + + + +Sync a subscribed application (click **Sync** in the UI, or run `argocd app sync `). Confirm that a Processing change appears in the Flashduty change list and is updated to Done or Failed when the sync ends. + + + + +## What one change is +--- + +One change is one sync operation of one application. Its change key (change_key) is `/`: + +- `app_uid` is the application's `metadata.uid`. Kubernetes assigns every object a UID that is unique over the whole lifetime of the cluster, so same-named applications in different Argo CD instances, and an application deleted and recreated, are different applications +- `started_at` is the sync operation's start time (`status.operationState.startedAt`, recorded in UTC). Argo CD writes it when the sync starts and keeps it through retries, and an application runs only one sync operation at a time + +So the start, the failed retries, and the final result of one sync update the same change, and two syncs of the same application are two changes, even when they sync the same revision. Changes to the application name, project, revision, or sync message do not change the change key. + +Flashduty rejects a request that lacks `app_uid` or `started_at`, or whose times are not in RFC 3339 format. + +## Status mapping +--- + +| Argo CD sync phase (`phase`) | Flashduty change status | +|---|---| +| `Running`, `Terminating` | Processing | +| `Succeeded` | Done | +| `Failed`, `Error` | Failed | +| `Failed` with the message `Operation terminated` (**Terminate** in the UI, or `argocd app terminate-op`) | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time. An operation that Argo CD terminates because of the sync timeout (the message contains `triggered by controller sync timeout`) is recorded as Failed. + +Sync phases are case-sensitive, and other values are rejected. The following deliveries return success without creating a change: an application with no sync operation yet (empty `phase`), and dry-run syncs. + +The recorded time is `started_at` when a sync starts and `finished_at` when it ends. While Argo CD retries a failed sync automatically, the phase stays `Running`, so the change is not marked Failed early. + +## Change content +--- + +- **Title**: `: sync to `. A Git commit shows its first 7 characters; other values, such as a Helm chart version, are shown as is. The revision or destination namespace part is omitted when empty +- **Link**: `/applications/`, only when `context.argocdUrl` is configured + +Labels can be used for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `application` | Application name | +| `app_uid` | The application's `metadata.uid` | +| `app_namespace` | Namespace of the Application object | +| `project` | Argo CD project of the application | +| `destination` | Destination cluster name, or the cluster address when no name is set | +| `destination_namespace` | Destination namespace | +| `revision` | Synced revision (Git commit or chart version) | +| `actor` | User who started the sync; `automated` for automated syncs | +| `phase` | Latest sync phase | +| `message` | Latest sync message, such as the failure reason, truncated beyond 1024 bytes | + +Empty fields are not written as labels. + +## FAQ +--- + + + + +- Check the `argocd-notifications-controller` logs (`kubectl logs -n argocd deploy/argocd-notifications-controller`) and confirm that the application has the `notifications.argoproj.io/subscribe.on-flashduty-change.flashduty-change` annotation, or that `subscriptions` includes `on-flashduty-change` +- If the logs show `template 'flashduty-change' is not supported` or `trigger 'on-flashduty-change' is not configured`, confirm the configuration is in `argocd-notifications-cm`; for Helm installs, check the corresponding values + + + + + +When a sync finishes within a few seconds, Argo CD may not observe the `Running` phase and sends only the end notification. Flashduty records the change directly in its end state. + + + + + +No. An event with the same phase and the same time is recorded only once. + + + + + +Confirm the template matches this page and every value goes through `toJson`. The response names the missing or unsupported field, such as `app_uid is missing`, `started_at is missing`, or `unsupported phase`. + + + + +For related configuration, see the Argo CD documentation on [Webhook](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/services/webhook/), [Triggers](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/triggers/), [Templates](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/templates/), and [Subscriptions](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/subscriptions/). diff --git a/en/on-call/integration/change-integration/azure-devops.mdx b/en/on-call/integration/change-integration/azure-devops.mdx new file mode 100644 index 000000000..e550e4463 --- /dev/null +++ b/en/on-call/integration/change-integration/azure-devops.mdx @@ -0,0 +1,157 @@ +--- +title: "Azure DevOps change integration" +description: "Sync Azure DevOps pipeline runs and classic release stage deployments to Flashduty On-call through Service Hooks, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Azure DevOps", "Pipelines", "Release", "Service Hooks", "Webhook"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use Azure DevOps Service Hooks (Web Hooks) to sync two kinds of objects to Flashduty On-call: + +- **Pipeline runs**: each run becomes one Flashduty change, from the run starting to it succeeding, failing, or being canceled. +- **Classic release stage deployments**: one deployment of a release to one stage becomes one change, from the deployment starting to it completing. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Azure DevOps** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `pipeline`, `project`, or `environment` +4. Click **Save** and copy the generated **push URL** + +
+ +## In Azure DevOps +--- + + + + +1. Open the project and go to **Project settings → Service hooks** +2. Click **Create subscription**, select the **Web Hooks** service, and click **Next** + +You need the Project Administrators role. + + + + + +Create one subscription per event as needed: + +| Trigger on this type of event | Object recorded | +|---|---| +| **Run state changed** | Pipeline run | +| **Release deployment started** | Release stage deployment (start) | +| **Release deployment completed** | Release stage deployment (end) | + +Use **Filters** to limit a subscription to a pipeline, release definition, or stage. Do not subscribe **Build completed** or **Run stage state changed**; Flashduty ignores them. + + + + + +1. **URL**: paste the full push URL of the Flashduty integration +2. **Basic authentication username / password**: leave empty; Flashduty authenticates with the `integration_key` in the push URL +3. **Resource details to send**: select **All**. With Minimal or None the delivery lacks the run id, release, and stage name, and Flashduty answers 400 +4. **Messages to send** and **Detailed messages to send**: keep the defaults. Flashduty uses the message Text as the change description and the link in the Markdown message as the link of release events (they have no separate link field); when a format is not sent, the description or link is empty +5. Click **Test** to verify, then **Finish** + + + + +**Test** sends a sample delivery; Flashduty answers success and records no change. + +## What one change is +--- + +| Azure DevOps object | Change identity (change_key) | Notes | +|---|---|---| +| Pipeline run | `run:` | The run id is the `buildId` in the run page link. The start, canceling, and completion events of one run are one change; a re-run is a new run and a new change | +| Release stage deployment | `release:/` (the stage's definition id, `definitionEnvironmentId` in the stage link of the event message) | Renaming a stage does not split its change. Redeploying the same release to the same stage stays one change and the later deployment overwrites its status. Different releases, or different stages of one release, are different changes | + +Azure DevOps run ids are unique only within an organization. Create a separate Flashduty integration for each Azure DevOps organization. + +## Status mapping +--- + +**Pipeline runs** (Run state changed) + +| state | result | Flashduty change status | +|---|---|---| +| `inProgress` | - | Processing | +| `canceling` | - | Processing | +| `completed` | `succeeded` | Done | +| `completed` | `failed` | Failed | +| `completed` | `canceled` | Canceled | + +**Release stage deployments** + +| Event / deployment status | Flashduty change status | +|---|---| +| Deployment started | Processing | +| Deployment completed, `succeeded` | Done | +| Deployment completed, `partiallySucceeded` | Done | +| Deployment completed, `failed` | Failed | +| Deployment completed, `canceled` | Canceled | +| Deployment completed, `rejected` (approval refused) | Canceled | + +A state value Flashduty does not recognize makes the delivery answer 400 (`unknown run state`, `unknown run result`, `unknown deployment status`). The raw state is kept in the `state` label of the change event. + +These deliveries return success and record nothing: + +- **Build completed**, **Run stage state changed**, and any other event type +- The **Test** delivery of Service Hooks + +## Change content +--- + +| Field | Content | +|---|---| +| Title | Pipeline: `: run `; release: `: deploy to ` | +| Description | The text message of the Azure DevOps event | +| Link | The pipeline run page; for release events, the stage page from the event message | +| Change time | The run's finish time when it ends, otherwise the event's creation time | + +Labels can be used for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `kind` | `pipeline_run` or `release_deployment` | +| `pipeline`, `pipeline_id`, `run_id` | Pipeline name, pipeline id, run id (pipeline runs) | +| `project`, `release`, `release_id`, `environment`, `environment_id` | Project name, release name, release id, stage name, stage definition id (releases) | +| `state` | The raw Azure DevOps state, for example `completed/succeeded`, `queued`, `succeeded`. It differs per event, so do not route on it | + +Run events carry no project name, so pipeline runs have no `project` label. + +## FAQ +--- + + + + +No. When Azure DevOps retries a delivery, the content is identical to the original and Flashduty records it once. + + + + + +Flashduty records Pipelines run state events (Run state changed) and Release deployment events. Classic build pipelines do not send Run state changed; use YAML pipelines to have them recorded. + + + + + +Release deployment events carry no deployment id, so Flashduty identifies a deployment by release id and stage id; a redeployment updates the same change. + + + + + +- `resource.run.id is missing`, `resource.release.id is missing`, `resource.environment.name is missing`, `resource.environment.definitionEnvironmentId is missing` (or `resource.deployment.environment.id is missing`, `resource.deployment.environment.name is missing` on completed events): **Resource details to send** is not **All**, or the delivery does not come from Azure DevOps Service Hooks +- `unknown run state`, `unknown run result`, `unknown deployment status`: a state value Flashduty does not recognize yet +- `invalid createdDate`: a timestamp field in the delivery is malformed + + + diff --git a/en/on-call/integration/change-integration/bitbucket.mdx b/en/on-call/integration/change-integration/bitbucket.mdx new file mode 100644 index 000000000..a7eac835a --- /dev/null +++ b/en/on-call/integration/change-integration/bitbucket.mdx @@ -0,0 +1,120 @@ +--- +title: "Bitbucket change integration" +description: "Sync commit build statuses from Bitbucket Cloud (Pipelines and third-party CI) to Flashduty On-call through a repository webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Bitbucket", "Bitbucket Pipelines", "build status", "deployment", "Webhook", "CI/CD"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a Bitbucket Cloud repository webhook to sync the build statuses on commits to Flashduty On-call. Bitbucket Pipelines, and third-party CI that publishes build statuses through the Bitbucket API, produce these events. Each build status becomes one Flashduty change; when the state moves from in progress to successful, failed, or stopped, the same change is updated. + +Bitbucket has no separate deployment event, so build statuses are the source of pipeline results. We recommend enabling the webhook only on repositories whose pipelines deploy. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Bitbucket** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `repo` or `build_key` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Bitbucket +--- + + + + +In the repository, go to **Repository settings → Webhooks** and click **Add webhook**. You need repository admin permission. + + + + + +1. **Title**: a name you can recognize, such as `Flashduty` +2. **URL**: paste the complete Flashduty integration Push URL +3. **Status**: keep **Active** + + + + + +1. Under **Triggers**, select **Choose from a full list** +2. Expand **Repository** and select **Build status created** and **Build status updated** +3. Click **Save** + + + + +## What one change is +--- + +A Bitbucket build status has no id of its own; it is addressed by repository, commit, and status key (the API path `/commit//statuses/build/`). The Flashduty change identifier (change_key) is `//`, so the created and updated events of one build status update the same change. + +- Build statuses with different keys on the same commit (for example a test check and a lint check) are two changes +- The same key on two commits is two changes; Bitbucket Pipelines uses a distinct key for each run +- If a third-party CI reuses one key on the same commit (for example when re-running), Bitbucket overwrites the status. In Flashduty the same change returns to in progress and is updated with the new final state when it ends + +## Status mapping +--- + +Flashduty derives the status from `commit_status.state` in the payload: + +| Bitbucket build status | Flashduty change status | +|---|---| +| INPROGRESS | Processing | +| SUCCESSFUL | Done | +| FAILED | Failed | +| STOPPED | Canceled | + +Done, Failed, and Canceled are end states, and Flashduty records the change end time. STOPPED appears in the Bitbucket REST API's state enum; the webhook documentation lists only the first three states. + +These deliveries return success but create no change: `repo:push`, pull request, comment, and other events that are not build statuses, and statuses whose type is not `build`. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: ()`; the status key when there is no name | +| Description | The build status description, taken from the first event of the change only | +| Link | The build status url (the build's page in the CI); the commit's page in Bitbucket when it has none | + +The payload carries no branch, so there is no branch label. Labels can be used for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `repo` | Repository full name, `/` | +| `sha` | The commit hash the status belongs to | +| `actor` | Name of the user who published the status | +| `build_key` | The build status key | +| `state` | The latest Bitbucket build state | + +## FAQ +--- + + + + +- Confirm the webhook has **Build status created** and **Build status updated** selected; push and similar events create no change +- Check the recent deliveries and Flashduty's responses under the webhook's **View requests** +- Confirm the repository's pipeline or CI actually publishes build statuses on commits + + + + + +No. An event with the same state and update time is recorded once. When a delivery fails, Bitbucket retries up to two more times; retries add no event. + + + + + +- `unsupported commit_status.state`: a build state Flashduty does not support yet was received; contact us +- `repository.uuid is missing`, `commit_status.key is missing`, `commit_status.links.commit.href is missing the commit hash`: the payload is incomplete; confirm it comes from a Bitbucket Cloud repository webhook + + + diff --git a/en/on-call/integration/change-integration/buildkite.mdx b/en/on-call/integration/change-integration/buildkite.mdx new file mode 100644 index 000000000..a44fd0b5e --- /dev/null +++ b/en/on-call/integration/change-integration/buildkite.mdx @@ -0,0 +1,123 @@ +--- +title: "Buildkite change integration" +description: "Sync Buildkite pipeline builds to Flashduty On-call through a Buildkite webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Buildkite", "build", "deployment", "Webhook", "CI/CD"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a Buildkite organization's webhook notification service to sync pipeline builds to Flashduty On-call. Each build becomes one Flashduty change; every state of the build, from scheduled and running through failing to passed, failed, or canceled, updates that same change. + +We recommend sending only deployment pipelines: select those pipelines in the webhook, or use branch filtering to send builds of release branches only. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Buildkite** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `pipeline` or `ref` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Buildkite +--- + + + + +In your Buildkite organization, go to **Settings → Notification Services** and click **Add** next to **Webhook**. You need organization admin permission. + + + + + +1. **Description**: a name you can recognize, such as `Flashduty` +2. **Webhook URL**: paste the complete Flashduty integration Push URL +3. **Token**: keep the default; Flashduty authenticates with the `integration_key` in the Push URL + + + + + +1. Under **Events**, select `build.scheduled`, `build.running`, `build.failing`, `build.finished`, and `build.skipped` +2. Under **Pipelines**, choose the pipelines to send (all, specific pipelines, or the pipelines of specific teams or clusters) +3. To send only some branches, enter branch patterns under **Branch filtering**; leave it empty for all branches +4. Click **Add Webhook Notification** to save + + + + +## What one change is +--- + +One build is one change. Its change identifier (change_key) is the build's `build.id`, a UUID unique across Buildkite. Every `build.*` event of the same build updates the same change; two builds of the same pipeline and branch are two changes, and a rebuild creates a new build and a new change. + +## Status mapping +--- + +Flashduty takes the status from `build.state` in the delivery: + +| Buildkite build state | Flashduty change status | +|---|---| +| blocked (waiting on a block step) | Planned | +| creating, scheduled, waiting | Ready | +| running, failing, waiting_failed, canceling | Processing | +| passed | Done | +| failed | Failed | +| canceled, skipped, not_run | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives. A build waiting on a block step is delivered as `build.finished` with state `passed` and `blocked` set to `true`; Flashduty records it as Planned and updates it to the final status when the build continues and finishes. + +These deliveries return success but create no change: `ping` and other non-build events such as `job.*`, `agent.*`, and `cluster_token.*`. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: build # on ` | +| Description | The build message, usually the commit message | +| Link | The build's page in Buildkite | + +Use labels for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `pipeline` | Pipeline slug | +| `repo` | The pipeline's repository URL | +| `ref` | The build's branch | +| `sha` | The build's commit SHA (absent until Buildkite resolves the commit) | +| `actor` | Name of the user who triggered the build | +| `source` | How the build was triggered: `webhook`, `api`, `ui`, `trigger_job`, or `schedule` | +| `build_id` | Build UUID | +| `build_number` | Build number within the pipeline | +| `state` | The latest Buildkite build state; `blocked` while waiting on a block step | + +## FAQ +--- + + + + +- Make sure the webhook has the `build.*` events selected; `job.*` or `agent.*` events alone create no changes +- Make sure the build's pipeline and branch are within the webhook's **Pipelines** and **Branch filtering** settings +- At the bottom of the webhook settings page, click **Load recent requests** to see the last 20 deliveries and Flashduty's responses + + + + + +No. An event with the same state and time is recorded only once. + + + + + +- `unsupported build.state`: Flashduty received a build state it does not support yet; contact us +- `build.id is missing`: the delivery is incomplete; make sure it comes from Buildkite's webhook notification service + + + diff --git a/en/on-call/integration/change-integration/circleci.mdx b/en/on-call/integration/change-integration/circleci.mdx new file mode 100644 index 000000000..9fed1c03b --- /dev/null +++ b/en/on-call/integration/change-integration/circleci.mdx @@ -0,0 +1,130 @@ +--- +title: "CircleCI change integration" +description: "Sync CircleCI workflow results to Flashduty On-call through a CircleCI outbound webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "CircleCI", "workflow", "CI/CD", "Webhook"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a CircleCI project's outbound webhook to sync workflow results to Flashduty On-call. Each workflow becomes one Flashduty change, recorded once when the workflow ends. + +CircleCI sends the `workflow-completed` event only when a workflow ends and has no start event, so a change has no Processing state and is recorded directly with its end state: Done, Failed, or Canceled. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **CircleCI** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project`, `ref`, or `workflow` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure CircleCI +--- + + + + +1. In the CircleCI web app, open your organization and select **Projects**. In the target project's menu, choose **Project Settings** +2. In the sidebar, select **Webhooks** and click **Add Webhook** + +Webhooks are configured per project, and a project can have at most 5. Add one to each project you want to sync. + + + + + +1. **Webhook name**: a recognizable name, for example `Flashduty` +2. **URL**: paste the full push URL of the Flashduty integration +3. **Certificate Validation**: keep it enabled +4. **Secret token**: leave it empty. Flashduty authenticates with the `integration_key` in the push URL and does not verify `circleci-signature` +5. **Select an event**: select `workflow-completed` + +Selecting `job-completed` as well is harmless: job events do not produce changes and are ignored. + + + + + +Click **Test Ping Event**. Flashduty returns success and records no change. Then run a workflow and the change appears in the Flashduty change list. + + + + +## What one change is +--- + +| CircleCI object | Change key (change_key) | Notes | +|---|---|---| +| Workflow | `workflow.id` | Each workflow of a pipeline run has its own ID and becomes one Flashduty change; two runs on the same project and branch are two changes | + +## Status mapping +--- + +| CircleCI `workflow.status` | Flashduty change status | +|---|---| +| `success` | Done | +| `failed` | Failed | +| `error` | Failed | +| `unauthorized` | Failed | +| `canceled` | Canceled | + +These deliveries return success and record nothing: + +- `job-completed` (job-level events) +- `ping` (the test event) +- any other event type + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: on ()`, for example `webhook-service: build-test-deploy on main (1dc6aa6)` | +| Description | First line of the commit message (commit subject) | +| Link | The workflow's page in CircleCI | +| Change time | The workflow's end time (`workflow.stopped_at`) | + +Labels for routing and filtering the change list: + +| Label | Description | +|---|---| +| `project` | Project name | +| `project_slug` | Project slug, for example `github//` | +| `organization` | Organization name | +| `workflow` | Workflow name | +| `workflow_id` | Workflow ID | +| `pipeline_id` | Pipeline ID | +| `pipeline_number` | Pipeline number | +| `ref` | Branch or tag | +| `sha` | Full commit SHA | +| `actor` | Commit author name; the triggering username for GitLab or GitHub App projects | +| `circleci_state` | The raw CircleCI workflow status | + +## FAQ +--- + + + + +CircleCI outbound webhooks report only that a workflow or job has ended and send no start event. The change appears with its final status when the workflow ends. + + + + + +No. CircleCI retries later after a non-2xx response with the same content, and Flashduty deduplicates on the workflow end time, so the change is recorded once. + + + + + +- `workflow.id is missing`: the payload is incomplete; make sure it comes from a native CircleCI webhook +- `unknown workflow.status`: a workflow status that is not mapped yet; contact us to add it +- `invalid workflow.stopped_at` or `invalid happened_at`: a timestamp field is malformed + + + diff --git a/en/on-call/integration/change-integration/custom-event.mdx b/en/on-call/integration/change-integration/custom-event.mdx index 2c57529f7..0896d868e 100644 --- a/en/on-call/integration/change-integration/custom-event.mdx +++ b/en/on-call/integration/change-integration/custom-event.mdx @@ -61,14 +61,14 @@ Use the **push URL** shown on the integration details page. The URL format is: | :--- | :---: | :--- | :--- | | title | Yes | string | Change title, such as a release title, ticket title, or deployment task name. | | change_key | Yes | string | Change identifier. Events with the same `change_key` are treated as the same change. Subsequent events update the change status, labels, and link. | -| change_status | Yes | string | Change status. Enum values are case-sensitive: `Planned`, `Ready`, `Processing`, `Canceled`, and `Done`. | +| change_status | Yes | string | Change status. Enum values are case-sensitive: `Planned`, `Ready`, `Processing`, `Canceled`, `Done`, and `Failed`. | | event_time | No | integer | Event occurrence time as a Unix timestamp. Seconds and milliseconds are both supported. If omitted, Flashduty uses the time when the event is received. | | description | No | string | Change description, such as change content, impact scope, execution steps, or rollback plan. | | link | No | string | Change details link, such as a release, ticket, or CI/CD task URL. | | labels | No | map | Change labels. Both keys and values must be strings. We recommend following the Prometheus label naming convention for keys. Flashduty replaces special characters such as spaces, dots, and slashes in label keys with underscores. | -When `change_status` is `Done` or `Canceled`, Flashduty records the event time as the change end time. If you report a non-terminal status again, the end time is cleared. +When `change_status` is `Done`, `Canceled`, or `Failed`, Flashduty records the event time as the change end time. If you report a non-terminal status again, the end time is cleared. ### Response @@ -151,7 +151,7 @@ Labels describe events and should be as rich as possible: - **Change scope**: such as host, cluster, etc. - **Change ownership**: such as team, owner, etc. -- **Change lifecycle**: use the same `change_key` to report different `change_status` values as the change moves through planned, processing, completed, or canceled states. This helps restore the change process on the incident timeline. +- **Change lifecycle**: use the same `change_key` to report different `change_status` values as the change moves through planned, processing, completed, canceled, or failed states. This helps restore the change process on the incident timeline. ## FAQ diff --git a/en/on-call/integration/change-integration/flagsmith.mdx b/en/on-call/integration/change-integration/flagsmith.mdx new file mode 100644 index 000000000..624ff096e --- /dev/null +++ b/en/on-call/integration/change-integration/flagsmith.mdx @@ -0,0 +1,112 @@ +--- +title: "Flagsmith change integration" +description: "Sync Flagsmith feature flag and segment changes to Flashduty On-call through a Flagsmith audit log webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Flagsmith", "Feature Flag", "feature flag", "audit log", "Webhook"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a Flagsmith organisation-level audit log webhook to sync feature flag and segment changes to Flashduty On-call. Each audit log entry in Flagsmith that affects flag evaluation becomes one Flashduty change, for example changing a flag's state or remote config value, creating or deleting a flag, editing segment rules or segment overrides, publishing an environment feature version, or changing an identity override. + +Flagsmith sends changes that have already taken effect, so each change is recorded as **Done** directly. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Flagsmith** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Flagsmith +--- + + + + +1. Go to **Organisation Settings** and open the **Webhooks** tab +2. Create an audit log webhook + +You need organisation administrator permission. Use the organisation audit webhook (**Create audit webhook**). Besides audit log entries, Flagsmith also sends `FLAG_UPDATED` and `FLAG_DELETED` events to this URL; Flashduty returns success for them and records nothing. + + + + + +1. **URL**: paste the full push URL of the Flashduty integration +2. **Secret**: leave it empty. Flashduty authenticates the delivery by the `integration_key` in the push URL and does not verify `X-Flagsmith-Signature` +3. Enable the webhook and save + + + + +Flagsmith sends the audit log of every project in the organisation to this URL. After saving, make a change to any flag and it appears in the Flashduty change list. The **Test your webhook** button in the webhook dialog gets a success response from Flashduty and records no change. + +## What one change is +--- + +| Flagsmith object | Change key (change_key) | Notes | +|---|---|---| +| Audit log entry | `data.id` in the payload | Each save produces one audit log entry, which is one Flashduty change; turning a flag on and then off again is two changes | + +## Status mapping +--- + +| Flagsmith audit log entry (`related_object_type`) | Flashduty change status | +|---|---| +| `FEATURE` (flag created or deleted), `FEATURE_STATE` (flag state, remote config value, segment override, change request or scheduled change going live), `SEGMENT`, `EF_VERSION` (feature version published), `EDGE_IDENTITY` (identity override) | Done | + +These deliveries return success but record no change: + +- Entries of other types, such as change requests (`CHANGE_REQUEST`), environments, import requests, feature health, and release pipelines +- Flag metadata edits such as name, description, and tags (`Flag / Remote Config updated`) +- Entries that only schedule a change that has not taken effect yet (the log text contains `scheduled for`); Flagsmith sends a separate entry when the change goes live +- Deliveries whose event type is not `AUDIT_LOG_CREATED`, such as `FLAG_UPDATED` and `FLAG_DELETED` +- Flagsmith's test request + +## Change content +--- + +| Field | Content | +|---|---| +| Title | ` / : `, for example `Web Shop / Production: Flag state updated for feature: new_checkout`; project-level entries (such as creating a flag) have no environment | +| Description | Empty | +| Link | Empty. Flagsmith's payload contains neither a page URL nor the instance address | + +Labels can be used for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `project` | Project name | +| `environment` | Environment name; absent for project-level entries | +| `kind` | `related_object_type`, for example `FEATURE_STATE` | +| `actor` | Name of the user who made the change; absent when the change was made without a user (for example with a master API key) or the user has no name set | +| `audit_log_id` | Audit log entry ID | + +## FAQ +--- + + + + +No. A retry carries the same content as the original delivery, and Flashduty records it once. + + + + + +Check the ignore list in **Status mapping** above: metadata edits, the change request itself, and the creation of a scheduled change are not recorded. A record appears when the change request is committed and takes effect, or when the scheduled change goes live. Also confirm the webhook is configured at the organisation level and enabled. + + + + + +- `data.id is missing`: the payload lacks the audit log entry ID; confirm the delivery comes from a Flagsmith organisation webhook +- `invalid created_date`: the time field in the payload is malformed + + + diff --git a/en/on-call/integration/change-integration/gitea.mdx b/en/on-call/integration/change-integration/gitea.mdx new file mode 100644 index 000000000..414ea3ab2 --- /dev/null +++ b/en/on-call/integration/change-integration/gitea.mdx @@ -0,0 +1,141 @@ +--- +title: "Gitea change integration" +description: "Sync Gitea Actions workflow runs and releases to Flashduty On-call through a Gitea webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Gitea", "Gitea Actions", "workflow", "Release", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a Gitea repository or organization webhook to sync Gitea Actions workflow runs and releases to Flashduty On-call. Each workflow run and each release becomes one Flashduty change; every state of a run, from running to success, failure or cancellation, updates that same change. + +A Gitea webhook cannot filter workflow runs by workflow or by branch (its **Branch filter** applies only to push and branch events), so every run of every workflow in the repository becomes a change, including workflows that only build or test. Use the `workflow` and `ref` labels to route or filter deployment runs in Flashduty. + +This page covers Gitea. Forgejo names its Actions events differently and sends a different payload, so it is not supported; connect it through [custom change events](/en/on-call/integration/change-integration/custom-event) instead. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Gitea** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `repo` or `workflow` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Gitea +--- + + + + +- Repository: go to the repository's **Settings → Webhooks** and click **Add Webhook → Gitea** +- Organization: go to the organization's **Settings → Webhooks** and click **Add Webhook → Gitea**; events from every repository in the organization are sent + +You need admin permission on the repository or organization. The repository must have Gitea Actions enabled and an available runner. + + + + + +1. **Target URL**: paste the complete Flashduty integration Push URL +2. **HTTP Method**: select `POST` +3. **POST Content Type**: select `application/json` (`application/x-www-form-urlencoded` is also accepted) +4. **Secret**: leave empty; Flashduty authenticates with the `integration_key` in the Push URL + + + + + +1. Under **Trigger On**, select **Custom Events…** +2. Check **Workflow Run** and **Release** and uncheck the others; do not check **Workflow Jobs**, which does not produce changes +3. Leave **Branch filter** empty; it does not apply to workflow runs +4. Keep **Active** checked and click **Add Webhook** + + + + +Gitea's **Test Push Event** sends a fake `push` event; Flashduty returns success and records no change. + +## What one change is +--- + +| Gitea object | Change key (change_key) | Notes | +|---|---|---| +| Workflow run | `run:` | The in-progress and completed events of one run update the same change; two runs of the same workflow on the same branch are two changes. A rerun keeps the run ID, so it updates the original change: the change goes from an end status back to Processing, and the `run_attempt` label records which attempt it is | +| Release | `release:` | Publishing and deleting the same release update the same change | + +## Status mapping +--- + +| Gitea event | Gitea state | Flashduty change status | +|---|---|---| +| workflow_run, `requested` | `waiting` (waiting for a maintainer to approve the run) | Planned | +| workflow_run, `in_progress` | running (including being canceled) | Processing | +| workflow_run, `completed` | `success` | Done | +| workflow_run, `completed` | `failure` | Failed | +| workflow_run, `completed` | `cancelled` | Canceled | +| workflow_run, `completed` | `skipped` (every job was skipped, nothing ran) | Canceled | +| release | published | Done | +| release | deleted | Canceled | + +Done, Failed and Canceled are end statuses; Flashduty records the change's end time. + +These deliveries return success and record nothing: every other Gitea event type (including `workflow_job` and the `push` sent by the test button), the release `updated` action, draft releases, and a queued run (the `requested` event with state `queued`, `pending` or `requested`; the change starts when the run starts). + +## Change content +--- + +| Field | Workflow run | Release | +|---|---|---| +| Title | `: on ()` | `: release ` | +| Description | The run's display title (commit message or pull request title) | Release name (empty when it equals the tag) | +| Link | The run's page, or the repository's Actions page when missing | Release page | + +Labels can be used for routing and for filtering the change list: + +| Label | Workflow run | Release | +|---|---|---| +| `repo` | Repository full name, e.g. `octo-org/hello-world` | Same | +| `workflow` | Workflow name, usually the workflow file name such as `deploy.yaml` | — | +| `ref` | Branch of the run | Release target branch or commit | +| `sha` | Full commit SHA of the run | — | +| `version` | — | Release tag | +| `trigger` | Event that triggered the run, e.g. `push`, `schedule`, `workflow_dispatch` | — | +| `actor` | User who triggered the run | Publisher | +| `run_id` / `release_id` | Gitea object ID | Gitea object ID | +| `run_attempt` | Attempt number | — | +| `state` | Latest run state; `success`, `failure`, `cancelled` or `skipped` once the run ends | — | +| `prerelease` | — | `true` for a prerelease | + +## FAQ +--- + + + + +- Make sure the webhook has **Workflow Run** checked and that your Gitea version offers that event +- Open the webhook page's delivery history to see the request and Flashduty's response + + + + + +No. An event with the same state and time is recorded once. + + + + + +Gitea cannot filter webhook events by workflow. The **Branch filter** does not apply to workflow runs either. Use the integration's **Routes** to send deployment workflows to the right channel by the `workflow` or `ref` label. + + + + + +- `unsupported action`, `unsupported workflow_run.status` or `unsupported workflow_run.conclusion`: a run state Flashduty does not support yet was received; please contact us +- `workflow_run.id is missing` or `release.id is missing`: the payload is incomplete; make sure it comes from a native Gitea webhook + + + diff --git a/en/on-call/integration/change-integration/github.mdx b/en/on-call/integration/change-integration/github.mdx new file mode 100644 index 000000000..07d479f62 --- /dev/null +++ b/en/on-call/integration/change-integration/github.mdx @@ -0,0 +1,132 @@ +--- +title: "GitHub change integration" +description: "Sync GitHub deployments and releases to Flashduty On-call through a GitHub webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "GitHub", "Deployment", "Release", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a GitHub repository or organization webhook to sync deployments and releases to Flashduty On-call. Each deployment and each release becomes one Flashduty change; every state of a deployment, from created and queued through running to success or failure, updates that same change. + +GitHub Actions jobs that declare an `environment` create deployments automatically, so repositories that release with Actions can connect without changing their workflows. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **GitHub** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `repo` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure GitHub +--- + + + + +- Repository: go to the repository's **Settings → Webhooks** and click **Add webhook** +- Organization: go to the organization's **Settings → Webhooks** and click **Add webhook**; events from every repository in the organization are sent + +You need admin permission on the repository or organization. + + + + + +1. **Payload URL**: paste the complete Flashduty integration Push URL +2. **Content type**: select `application/json` (`application/x-www-form-urlencoded` is also accepted) +3. **Secret**: leave it empty; Flashduty authenticates the request by the `integration_key` in the Push URL + + + + + +1. Select **Let me select individual events** +2. Check **Deployments**, **Deployment statuses**, and **Releases**, and uncheck **Pushes**, which is selected by default +3. Keep **Active** checked and click **Add webhook** + +After you save, GitHub sends a `ping`. Flashduty accepts it without creating a change. + + + + +## What one change is +--- + +| GitHub object | Change key (change_key) | Notes | +|---|---|---| +| Deployment | `deployment:` | The `deployment` event and every `deployment_status` event of one deployment update the same change; two deployments of the same repository to the same environment are two changes | +| Release | `release:` | Publishing, unpublishing, and deleting one release update the same change | + +## Status mapping +--- + +| GitHub event | GitHub state | Flashduty change status | +|---|---|---| +| deployment | created | Ready | +| deployment_status | waiting (waiting for environment approval) | Planned | +| deployment_status | pending, queued | Ready | +| deployment_status | in_progress | Processing | +| deployment_status | success | Done | +| deployment_status | failure, error | Failed | +| deployment_status | error from a GitHub Actions job canceled on the run page (`workflow_run.conclusion` is `cancelled`) | Canceled | +| release | published | Done | +| release | unpublished, deleted | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives. + +These deliveries are accepted without creating a change: `ping`, any other event type, the release actions `created`, `edited`, `released`, and `prereleased` (GitHub also sends `published` when a release is published, and that is the one recorded), and the deployment state `inactive` (an older deployment replaced by a newer one; its earlier result stays as it was). + +## Change content +--- + +| Field | Deployment | Release | +|---|---|---| +| Title | `: deploy () to ` | `: release ` | +| Description | The deployment's description | The release name (empty when it equals the tag) | +| Link | The deployment log (`log_url` or `target_url`), or the repository's Deployments page when there is none | The release page | + +Labels can be used in routes and to filter the change list: + +| Label | Deployment | Release | +|---|---|---| +| `repo` | Full repository name, such as `octo-org/hello-world` | Same | +| `environment` | Deployment environment | — | +| `ref` | The branch, tag, or SHA deployed | The release's target branch or commit | +| `sha` | Full commit SHA deployed | — | +| `version` | — | Release tag | +| `task` | Deployment task, usually `deploy` | — | +| `actor` | The user who created the deployment | The release author | +| `deployment_id` / `release_id` | GitHub object ID | GitHub object ID | +| `state` | The latest GitHub deployment state | — | +| `prerelease` | — | `true` for a pre-release | + +## FAQ +--- + + + + +- Make sure the webhook has **Deployments** and **Deployment statuses** checked. **Pushes** alone creates no changes +- Check the delivery history and Flashduty's responses under **Recent Deliveries** on the GitHub webhook page +- Only releases that use GitHub Deployments send deployment events, for example a GitHub Actions job that declares an `environment`, or a call to the Deployments API + + + + + +No. An event with the same state and time is recorded once. + + + + + +- `unsupported deployment_status.state`: Flashduty received a deployment state it does not support yet. Contact us +- `deployment.id is missing` or `release.id is missing`: the payload is incomplete. Make sure the delivery comes from a native GitHub webhook + + + diff --git a/en/on-call/integration/change-integration/gitlab.mdx b/en/on-call/integration/change-integration/gitlab.mdx new file mode 100644 index 000000000..7c67c1556 --- /dev/null +++ b/en/on-call/integration/change-integration/gitlab.mdx @@ -0,0 +1,133 @@ +--- +title: "GitLab change integration" +description: "Sync GitLab deployments to Flashduty On-call through a GitLab webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "GitLab", "Deployment", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a GitLab project or group webhook to sync deployments to Flashduty On-call. Each deployment becomes one Flashduty change; every state of a deployment, from waiting for approval through running to success, failure or cancellation, updates that same change. + +GitLab CI/CD jobs that declare an `environment` create deployments automatically, so projects that release with GitLab CI/CD can connect without changing their pipelines. This works for both GitLab.com and self-managed GitLab. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **GitLab** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure GitLab +--- + + + + +- Project: go to the project's **Settings → Webhooks** and click **Add new webhook** +- Group (GitLab Premium or higher): go to the group's **Settings → Webhooks** and click **Add new webhook**; deployments from every project in the group are sent + +Project webhooks need the Maintainer or Owner role on the project; group webhooks need the Owner role on the group. + + + + + +1. **URL**: paste the complete Flashduty integration Push URL +2. **Signing token** and **Secret token**: not needed; Flashduty authenticates the request with the `integration_key` in the Push URL + + + + + +1. Under **Trigger**, select only **Deployment events** and clear the default **Push events** +2. Keep **Enable SSL verification** selected and click **Add webhook** + +GitLab's **Test** feature cannot send deployment events. Other events sent with Test (such as Push events) get a success response from Flashduty but create no change. + + + + +## What one change is +--- + +| GitLab object | Change identifier (change_key) | Notes | +|---|---|---| +| Deployment | `deployment:` | Every Deployment event of one deployment updates the same change; two deployments of the same project to the same environment (including a retried deploy job) are two changes | + +`deployment_id` is unique within one GitLab instance. To connect several GitLab instances (for example GitLab.com and a self-managed instance), create one integration per instance. + +## Status mapping +--- + +| GitLab deployment status | Flashduty change status | +|---|---| +| blocked (waiting for approval or a manual action) | Planned | +| created | Ready | +| running | Processing | +| success | Done | +| failed | Failed | +| canceled, skipped | Canceled | + +Done, Failed and Canceled are end states; Flashduty records the change's end time. GitLab only sends events for blocked, running, success, failed and canceled. + +These deliveries get a success response but create no change: event types other than Deployment (Push, Pipeline and so on), and the protected-environment approval events `approved` and `rejected`. An approval event describes the approval record, not the deployment itself: after an approval GitLab sends `running` when the deployment starts, and after a rejection it sends `failed`; the change status follows those deployment events. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: deploy () to ` | +| Description | The title of the deployed commit (`commit_title`) | +| Link | The CI/CD job that ran the deployment; deployments created through the API or by a trigger job have no job, so the link is the project's Environments page | + +Labels can be used for routing and for filtering the change list: + +| Label | Content | +|---|---| +| `project` | Full project path, for example `acme/order-service` | +| `project_id` | GitLab project ID | +| `environment` | Deployment environment | +| `environment_tier` | Environment tier, for example `production` or `staging` | +| `ref` | Deployed branch or tag | +| `sha` | Short SHA of the deployed commit | +| `actor` | Username of the user who triggered the deployment | +| `deployment_id` | GitLab deployment ID | +| `state` | Latest GitLab deployment status | + +## FAQ +--- + + + + +- Make sure the webhook has **Deployment events** selected. With only **Push events** selected, no changes are created +- Check the deliveries and Flashduty's responses under **Recent events** on the GitLab webhook edit page +- Only GitLab deployments produce deployment events, for example a CI/CD job that declares an `environment`, or a call to the Deployments API + + + + + +No. An event with the same status and the same time is recorded only once. + + + + + +After a deployment is rejected, GitLab sends `failed`; Flashduty records the deployment status as Failed, with the `state` label set to `failed`. + + + + + +- `unsupported deployment status`: Flashduty received a deployment status it does not support yet; contact us +- `deployment_id is missing`: the payload is incomplete; make sure it comes from a native GitLab webhook + + + diff --git a/en/on-call/integration/change-integration/hcp-terraform.mdx b/en/on-call/integration/change-integration/hcp-terraform.mdx new file mode 100644 index 000000000..b7d708efa --- /dev/null +++ b/en/on-call/integration/change-integration/hcp-terraform.mdx @@ -0,0 +1,134 @@ +--- +title: "HCP Terraform change integration" +description: "Sync Terraform runs to Flashduty On-call through HCP Terraform workspace notifications, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "HCP Terraform", "Terraform Cloud", "Run", "Webhook", "infrastructure changes"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use HCP Terraform (formerly Terraform Cloud) workspace notifications to sync Terraform runs to Flashduty On-call. Each run becomes one Flashduty change; every state of a run, from created through planning, waiting for confirmation, and applying to completed, errored, or canceled, updates that same change. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **HCP Terraform** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `organization` or `workspace` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure HCP Terraform +--- + +Notifications are configured per workspace, so configure one for each workspace you want to connect. You need admin permission on the workspace. + + + + +In the workspace, go to **Settings → Notifications** and click **Create a notification**. + + + + + +1. **Destination**: select **Webhook** +2. **Name**: enter a recognizable name, such as `Flashduty` +3. **Webhook URL**: paste the complete Flashduty integration Push URL +4. **Token**: leave it empty; Flashduty authenticates with the `integration_key` in the Push URL + + + + + +1. Under **Run Events**, select **All events** +2. Under **Workspace Events** (drift detection, auto destroy, and so on), select **No events**; Flashduty ignores these notifications +3. Click **Create a notification** + +When you save, HCP Terraform sends a verification request. Flashduty accepts it without creating a change. You can verify again later with **Send a test**. + + + + +You can also manage this configuration with the Terraform `tfe` provider: a `tfe_notification_configuration` resource with `destination_type = "generic"`, `url` set to the Push URL, and `triggers` set to `["run:created", "run:planning", "run:needs_attention", "run:applying", "run:completed", "run:errored"]`. + +## What one change is +--- + +| HCP Terraform object | Change key (change_key) | Notes | +|---|---|---| +| Run | `run_id`, for example `run-FwnENkvDnrpyFC7M` | Every notification of one run updates the same change; two runs of the same workspace are two changes | + +## Status mapping +--- + +| Notification trigger | Run status (run_status) | Flashduty change status | +|---|---|---| +| run:created | pending | Ready | +| run:planning | planning | Processing | +| run:needs_attention | for example planned or policy_override (waiting for confirmation) | Planned | +| run:applying | applying | Processing | +| run:completed | applied, planned_and_finished, planned_and_saved | Done | +| run:completed | discarded (the run was discarded at the confirm step) | Canceled | +| run:errored | errored, policy_soft_failed | Failed | +| run:errored | canceled, force_canceled | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time. + +`planned_and_finished` means a run that only planned (no changes, or a plan-only run). It is also recorded as Done; use the `run_status` label to tell it apart. + +The following deliveries are accepted without creating a change: the verification request sent on save or by **Send a test** (trigger `verification`), health assessment notifications (`assessment:drifted`, `assessment:check_failure`, `assessment:failed`), and workspace notifications (`workspace:auto_destroy_reminder`, `workspace:auto_destroy_run_results`, `workspace:deleted`). + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `/: terraform run ` | +| Description | The run message (why the run was queued, such as a VCS commit message or a message entered manually) | +| Link | The run's page in HCP Terraform | + +Use labels for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `organization` | HCP Terraform organization name | +| `workspace` | Workspace name | +| `workspace_id` | Workspace ID, for example `ws-XdeUVMWShTesDMME` | +| `run_id` | Run ID | +| `run_status` | Run status in the latest notification | +| `actor` | User who created the run | + +## FAQ +--- + + + + +- Make sure the notification is enabled and **Run Events** are selected. **Workspace Events** alone create no changes +- Check recent deliveries and Flashduty's responses on the notification configuration page +- Notifications are per workspace; make sure the run's workspace has this notification configured + + + + + +No. An event with the same run, status, and time is recorded only once. + + + + + +No. A health assessment reports resources drifting from their configuration, not a change. Flashduty accepts it and ignores it. + + + + + +- `unsupported notifications[].trigger` or `unsupported notifications[].run_status`: Flashduty received a trigger or run status it does not support yet; contact us +- `run_id is missing`: the payload is incomplete; make sure it comes from an HCP Terraform webhook notification + + + diff --git a/en/on-call/integration/change-integration/jenkins.mdx b/en/on-call/integration/change-integration/jenkins.mdx new file mode 100644 index 000000000..bf2d842be --- /dev/null +++ b/en/on-call/integration/change-integration/jenkins.mdx @@ -0,0 +1,145 @@ +--- +title: "Jenkins change integration" +description: "Sync every build of your Jenkins deployment jobs to Flashduty On-call through the Jenkins Notification plugin, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Jenkins", "Notification plugin", "build", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use the Jenkins [Notification plugin](https://plugins.jenkins.io/notification/) to sync job builds to Flashduty On-call. Each build becomes one Flashduty change; the build's start and finish update that same change. + +Jenkins cannot tell whether a build changed anything, so add the notification only to **jobs that deploy**, not to jobs that only compile or test. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Jenkins** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `job` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Jenkins +--- + + + + +Go to **Manage Jenkins → System** and make sure **Jenkins URL** under **Jenkins Location** is set to the address of your Jenkins. Without it, notifications carry no build link, Flashduty cannot identify the build, and the delivery is rejected. + + + + + +Go to **Manage Jenkins → Plugins → Available plugins**, search for **Notification**, and install it. You need Jenkins administrator permission. + +The plugin also needs the **JUnit** plugin, which Jenkins does not install with it. If **Manage Jenkins → Plugins → Installed plugins** does not list JUnit, install it too. Without JUnit, no notification is sent and the build log shows `NoClassDefFoundError: hudson/tasks/test/AbstractTestResultAction`. + + + + + +1. Open the deployment job, click **Configure**, find the **Job Notifications** section, and click **Add Endpoint** +2. **Format**: select `JSON` +3. **Protocol**: select `HTTP` +4. **Event**: select `All Events`, so Flashduty sees the build both start and finish +5. **URL Source**: select `Credentials Store`, save the complete Flashduty integration Push URL as a **Secret text** credential, and select that credential in **URL**. With `Plain Text`, the plugin prints the full Push URL, including `integration_key`, in the log of every build +6. Keep **Branch** at the default `.*`, leave the other options at their defaults, and click **Save** + +If the job configuration is managed by a Jenkinsfile (for example, a multibranch pipeline), add the same settings to the Jenkinsfile's `properties`. You can generate the code on the pipeline's **Pipeline Syntax → Snippet Generator** page by selecting `properties: Set job properties`. + + + + + +Run the job once; the change appears in the Flashduty change list. The Notification plugin has no test button. If Jenkins cannot reach Flashduty, the build log shows `Failed to notify endpoint`; the plugin does not check the response, so a delivery that Flashduty rejects is not shown in Jenkins. + + + + +## What one change is +--- + +Each build is one change. Its change key (change_key) is `#`, for example `https://jenkins.example.com/job/deploy/18/#4711`. + +- Every phase of one build updates the same change +- Two builds of the same job are two changes +- When a job is deleted and recreated and its build numbers restart at 1, the queue IDs differ, so new builds are not merged into old ones +- When several Jenkins instances send to the same integration, their build URLs differ, so their builds are kept apart + +## Status mapping +--- + +| Build phase (phase) | Build result (status) | Flashduty change status | +|---|---|---| +| STARTED | — | Processing | +| COMPLETED, FINALIZED | SUCCESS | Done | +| COMPLETED, FINALIZED | UNSTABLE | Done | +| COMPLETED, FINALIZED | FAILURE | Failed | +| COMPLETED, FINALIZED | ABORTED, NOT_BUILT | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives. COMPLETED means the build steps have finished; FINALIZED means post-build actions (such as archiving artifacts) have finished too. Both carry the same result. + +UNSTABLE means every build step ran, but tests or quality checks reported problems, so it is recorded as Done; use the `result` label to filter these changes. + +The plugin sends QUEUED only when the build starts, never while the build waits in the queue. Flashduty accepts QUEUED without recording it, so a change appears when its build starts. + +A `notifyEndpoints` step in a pipeline with `phase` set to `NONE` is accepted without creating a change. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | ` #`, such as `platform/order-service/main #18` | +| Description | The endpoint's **Notes** option; empty when not set | +| Link | The build page | + +Labels can be used in routes and to filter the change list: + +| Label | Description | +|---|---| +| `job` | Full job name, including folders and the branch of a multibranch pipeline, such as `platform/order-service/main` | +| `build_number` | Build number | +| `branch` | The Git branch the build checked out | +| `commit` | The Git commit the build checked out | +| `phase` | The latest build phase | +| `result` | The build result, present once the build has finished | + +`branch` and `commit` are sent only by freestyle jobs that use Git under **Source Code Management**. A Pipeline job that checks out with the `git` step does not send them. A notification sent when the build starts can carry the values from before this build's checkout, so rely on the values at the end of the build. Route on `job`; otherwise the early and late events of one build can land in different channels. + +## FAQ +--- + + + + +- Make sure **Format** is `JSON` and **Protocol** is `HTTP` +- Make sure **Jenkins URL** is set under **Manage Jenkins → System** +- Look for `Notifying endpoint` or `Failed to notify endpoint` in the build log +- `NoClassDefFoundError: hudson/tasks/test/AbstractTestResultAction` in the build log means the JUnit plugin is missing. Install it +- When **Branch** is not `.*`, only builds that have a `BRANCH_NAME` environment variable matching it send notifications + + + + + +The plugin sends one notification when the build completes (COMPLETED) and another when post-build actions finish (FINALIZED). Both carry the same result, so the change status does not change. When both arrive within the same second, the second one is not recorded. To receive only one, set **Event** to `Job Finalized`, but then the running phase is not shown. + + + + + +Flashduty rejects a delivery in these cases: + +- `build.full_url is missing`: the Jenkins URL is not configured +- `build.queue_id is missing`: the payload has no queue ID. Make sure the delivery comes from the Notification plugin +- `build.status is missing`: an end phase arrived without a build result, usually from a pipeline calling `notifyEndpoints(phase: 'COMPLETED')` or `'FINALIZED'` before the result is set +- `must use Format JSON`: the endpoint's **Format** is `XML` +- `unsupported build.phase` or `unsupported build.status`: Flashduty received a phase or result it does not support yet. Contact us + + + diff --git a/en/on-call/integration/change-integration/jfrog-artifactory.mdx b/en/on-call/integration/change-integration/jfrog-artifactory.mdx new file mode 100644 index 000000000..4dcee68dd --- /dev/null +++ b/en/on-call/integration/change-integration/jfrog-artifactory.mdx @@ -0,0 +1,137 @@ +--- +title: "JFrog Artifactory change integration" +description: "Sync artifact deploys, deletes, moves, and copies from JFrog Artifactory to Flashduty On-call through a webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "JFrog", "Artifactory", "artifact", "Webhook", "change events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a JFrog Artifactory predefined webhook to sync artifact deploys, deletes, moves, and copies to Flashduty On-call. Each deployed artifact becomes one change, and deleting that same artifact later updates the change to Canceled; each move or copy becomes a change of its own. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **JFrog Artifactory** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `repo` or `path` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure JFrog Artifactory +--- + + + + +1. Sign in to the JFrog Platform and select **All Projects** or a specific project +2. Go to **Platform → Integrations → Webhooks** and click **New Webhook** +3. Keep the **Predefined** toggle selected (do not use Custom) + +You need admin or project admin permission. + + + + + +1. **Name**: for example, `flashduty-changes` +2. **URL**: paste the complete Flashduty integration Push URL +3. **Secret token**: leave empty; Flashduty authenticates with the `integration_key` in the Push URL + + + + + +1. Under **Artifacts**, select **Artifact was deployed**, **Artifact was deleted**, **Artifact was moved**, and **Artifact was copied** +2. Select the repositories to watch: all local repositories, a list of repositories, or include/exclude path patterns +3. Click **Test** to check connectivity, then click **Create** + +**Test** sends JFrog's sample data (checksum `sample_checksum`); Flashduty returns success but records no change. + + + + +## What one change is +--- + +JFrog payloads carry no change ID, so Flashduty identifies an artifact by its location plus its content checksum: + +| Artifactory event | Change key (change_key) | Notes | +|---|---|---| +| deployed, deleted | `artifact:/@` | Deploying and later deleting the same content update the same change; new content at the same path (a different checksum) is a new change | +| moved | `moved:/@ -> ` | One change per move | +| copied | `copied:/@ -> ` | One change per copy | + +For moved and copied, `/` is the artifact's original location and `` is the payload's `target_repo_path`. + +## Status mapping +--- + +| Artifactory event (event_type) | Flashduty change status | +|---|---| +| deployed | Done | +| moved | Done | +| copied | Done | +| deleted | Canceled | + +Artifactory sends artifact events after the operation completes, so each change has already ended when its first event arrives. + +The following deliveries return success but record no change: event domains other than artifacts (Artifact Properties, Docker, Builds, Release Bundles, and so on), `cached` (a remote repository caching a downloaded artifact, which is not a change), and the sample data sent by the **Test** button. + +## Change content +--- + +| Field | deployed, deleted | moved, copied | +|---|---|---| +| Title | `/ ()` | `move / () to `, or `copy ...` for a copy | +| Description | Empty | Empty | +| Link | The artifact's page in the JFrog Platform | The target location's page in the JFrog Platform | + +The link is built from the payload's `jpd_origin`; when the payload has no such field, the change has no link. + +Labels can be used in routes and to filter the change list: + +| Label | Description | +|---|---| +| `repo` | Repository key; for moved and copied, the original repository | +| `path` | The artifact's path in the repository | +| `name` | File name | +| `sha256` | SHA-256 checksum of the artifact's content | +| `source_repo_path` | moved and copied only: the original location | +| `target_repo_path` | moved and copied only: the target location | +| `actor` | The user or access token subject that performed the operation | +| `event_type` | Artifactory event: `deployed`, `deleted`, `moved`, or `copied` | + +## FAQ +--- + + + + +- Make sure the webhook is **Predefined** and has events under **Artifacts** selected +- Make sure the repository you deploy to is within the webhook's selected repositories +- Check the delivery records and Flashduty's responses on the webhook's **Troubleshooting** tab (on JFrog Cloud, the instance must have this feature enabled) + + + + + +Deploying a file with identical content to the same path adds an event to the existing change instead of creating a new one. Different content creates a new change. + + + + + +A retry adds an event but does not create a new change. JFrog payloads carry no event time, so Flashduty records each event at the time it is received and cannot recognize a retry. + + + + + +- `unsupported event_type`: Flashduty received an artifact event it does not support yet; contact us +- `data.repo_key is missing`, `data.path is missing`, `data.sha256 is missing`, or `data.target_repo_path is missing`: the payload is incomplete; make sure you use a Predefined webhook, not a Custom webhook with a customized payload + + + diff --git a/en/on-call/integration/change-integration/launchdarkly.mdx b/en/on-call/integration/change-integration/launchdarkly.mdx new file mode 100644 index 000000000..1d9422060 --- /dev/null +++ b/en/on-call/integration/change-integration/launchdarkly.mdx @@ -0,0 +1,144 @@ +--- +title: "LaunchDarkly change integration" +description: "Sync LaunchDarkly feature flag and segment changes to Flashduty On-call through a LaunchDarkly webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "LaunchDarkly", "Feature Flag", "feature flag", "Webhook"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a LaunchDarkly organization webhook to sync feature flag and segment changes to Flashduty On-call. Each flag or segment entry in LaunchDarkly's change history becomes one Flashduty change, for example turning a flag on or off, editing targeting rules, or changing the default rule. + +LaunchDarkly sends changes that have already taken effect, so each change is recorded as **Done** directly. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **LaunchDarkly** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project`, `environment`, or `flag` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure LaunchDarkly +--- + + + + +1. Click the **gear** icon in the left sidebar to open **Organization settings** +2. Click **Integrations**, find **Webhooks**, and click **Add new** + +You need a member role that can manage integrations, such as Admin. + + + + + +1. **Name**: enter a recognizable name, such as `Flashduty` +2. **URL**: paste the full push URL of the Flashduty integration +3. **Sign this webhook**: leave it unchecked. Flashduty authenticates the delivery by the `integration_key` in the push URL + + + + + +Without a policy, LaunchDarkly sends only flag changes in the **production** environment. To send other environments or segment changes, add this policy: + +```json +[ + { + "effect": "allow", + "actions": ["*"], + "resources": ["proj/*:env/*:flag/*"] + }, + { + "effect": "allow", + "actions": ["*"], + "resources": ["proj/*:env/*:segment/*"] + } +] +``` + +Replace `env/*` with a specific environment (such as `env/production`) to send only that environment. Accept the terms and click **Save settings**. + + + + +LaunchDarkly has no test delivery button. After saving, make one change to any flag and the record appears in the Flashduty change list. + +## What one change is +--- + +| LaunchDarkly object | Change key (change_key) | Notes | +|---|---|---| +| Change history entry | The entry's `_id` | Every save of a flag or segment creates one entry, which becomes one Flashduty change; turning the same flag on and then off is two changes | + +## Status mapping +--- + +| LaunchDarkly entry | Flashduty change status | +|---|---| +| A flag or segment change (on/off, targeting rules, default rule, variations, create, delete, archive, applying an approval request, and so on) | Done | + +These deliveries are accepted without creating a change: + +- Entries for other resource kinds, such as projects, environments, members, roles, webhooks, metrics, and experiments +- Entries that contain only the following actions, which do not change how a flag evaluates: + - Creating, updating, reviewing, or deleting an approval request (once an approval request is applied, LaunchDarkly sends the entry for that step) + - Creating, updating, or deleting scheduled changes (the entry for the scheduled change is sent when it runs) + - Name, description, tags, maintainer, temporary flag, deprecation, custom properties, rule descriptions, code references, flag links, followers, and segment exports + +## Change content +--- + +| Field | Content | +|---|---| +| Title | ` in : `, such as `Checkout redesign in production: turned on the flag`; project-wide actions (such as creating a flag) name no environment | +| Description | The change comment and LaunchDarkly's change details | +| Link | The flag or segment page in LaunchDarkly | + +Labels can be used in routes and to filter the change list: + +| Label | Description | +|---|---| +| `project` | Project key | +| `environment` | Environment key, such as `production`; absent for project-wide actions | +| `flag` | Flag key (flag changes) | +| `segment` | Segment key (segment changes) | +| `kind` | `flag` or `segment` | +| `action` | LaunchDarkly actions, comma-separated when there are several, such as `updateOn` or `updateRules` | +| `actor` | The name of the member who made the change, or the access token or application name for API changes | +| `audit_log_id` | Change history entry ID | + +## FAQ +--- + + + + +Without a policy, LaunchDarkly sends only flag changes in the production environment. Add a policy as described in **Choose what to send**. + + + + + +No. When a delivery fails, LaunchDarkly retries it once with the same content, and Flashduty records it once. + + + + + +LaunchDarkly does not guarantee chronological delivery. Flashduty uses the entry's own time (`date`) as the change time. + + + + + +- `_id is missing`: the payload is incomplete. Make sure the delivery comes from a native LaunchDarkly webhook +- `invalid date`: the time field in the payload is malformed + + + diff --git a/en/on-call/integration/change-integration/netlify.mdx b/en/on-call/integration/change-integration/netlify.mdx new file mode 100644 index 000000000..7adc35edd --- /dev/null +++ b/en/on-call/integration/change-integration/netlify.mdx @@ -0,0 +1,130 @@ +--- +title: "Netlify change integration" +description: "Sync Netlify deploys to Flashduty On-call through Netlify deploy notifications (HTTP POST request), as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Netlify", "deploy notifications", "Deploy notifications", "Webhook", "deployment events"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a Netlify project's deploy notifications to sync deploys to Flashduty On-call. Each deploy becomes one Flashduty change; every notification of that deploy, from waiting for approval and building to success or failure, updates that same change. + +Production deploys, branch deploys, and Deploy Previews are all sent; the `environment` label tells them apart. HTTP POST request deploy notifications are available on every Netlify plan. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Netlify** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Netlify +--- + +Each Netlify notification listens to one event, so add one notification for each event in the table below, all with the same Push URL. + + + + +In your Netlify project, go to **Project configuration → Notifications → Deploy notifications**, click **Add notification**, and select **HTTP POST request**. + + + + + +1. **Event to listen for**: select one event, see the next step +2. **URL to notify**: paste the complete Flashduty integration Push URL +3. **JWS secret token**: leave it empty; Flashduty authenticates the request by the `integration_key` in the Push URL +4. Click **Save** + + + + + +| Event | Needed | +|---|---| +| Deploy started | Required | +| Deploy succeeded | Required | +| Deploy failed | Required | +| Deploy restored | Recommended, records rollbacks | +| Deploy request pending, Deploy request accepted, Deploy request rejected | Add these when the project requires approval for untrusted deploys | + +Deploy locked, Deploy unlocked, and Deploy deleted are not needed: they do not change a deploy's result, and Flashduty accepts them without creating a change. + + + + +## What one change is +--- + +| Netlify object | Change key (change_key) | Notes | +|---|---|---| +| Deploy | The deploy ID (`id`) | Every notification of one deploy updates the same change; two deploys of the same project and branch are two changes | + +A rollback (Deploy restored) publishes an existing deploy again, so it updates that deploy's change with status Done. The rollback notification carries no rollback time, so the event time is when Flashduty receives it. + +## Status mapping +--- + +| Netlify event | Flashduty change status | +|---|---| +| Deploy request pending | Planned | +| Deploy request accepted | Ready | +| Deploy started | Processing | +| Deploy succeeded | Done | +| Deploy restored | Done | +| Deploy failed | Failed; Canceled when the build was canceled | +| Deploy request rejected | Canceled | + +Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: deploy () to `, such as `example-site: deploy main (f95f852) to production`; a manual deploy without a branch or commit gives `: deploy to ` | +| Description | The deploy's title, usually the commit message or the message entered for a manual deploy | +| Link | The deploy's page in the Netlify console, or the deploy's own URL when the payload has no `admin_url` | + +Labels can be used in routes and to filter the change list: + +| Label | Description | +|---|---| +| `project` | Netlify project name | +| `site_id` | Netlify project ID | +| `environment` | Deploy context: `production`, `deploy-preview`, `branch-deploy`, and so on | +| `ref` | The branch deployed | +| `sha` | Full commit SHA deployed | +| `deploy_id` | Netlify deploy ID | +| `review_id` | The pull request number of a Deploy Preview | +| `state` | The Netlify deploy state in the latest notification, such as `building`, `ready`, or `error` | +| `error_message` | Netlify's error message when a deploy fails | + +## FAQ +--- + + + + +Each Netlify notification sends one event. Make sure Deploy started, Deploy succeeded, and Deploy failed each have their own notification. + + + + + +No. When Netlify resends a notification that failed, Flashduty records it at the time of the event itself, and a notification with the same deploy, state, and time is recorded once. Deploy restored is the exception: it is recorded at the time Flashduty receives it, so a resent one is recorded again. + + + + + +- `unsupported X-Netlify-Event`: Flashduty received a Netlify event it does not support yet. Contact us +- `deploy id is missing`: the payload is incomplete. Make sure the delivery comes from a Netlify deploy notification + + + diff --git a/en/on-call/integration/change-integration/octopus-deploy.mdx b/en/on-call/integration/change-integration/octopus-deploy.mdx new file mode 100644 index 000000000..9378fa7ea --- /dev/null +++ b/en/on-call/integration/change-integration/octopus-deploy.mdx @@ -0,0 +1,130 @@ +--- +title: "Octopus Deploy change integration" +description: "Sync Octopus Deploy deployments (queued, started, succeeded, failed, canceled) to Flashduty On-call through a subscription webhook, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Octopus Deploy", "deployment", "Subscription", "Webhook"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use an Octopus Deploy subscription webhook to sync deployment progress to Flashduty On-call. Each Octopus deployment becomes one Flashduty change, and its status follows the deployment from queued to running to finished. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Octopus Deploy** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Octopus Deploy +--- + + + + +1. Go to **Configuration → Subscriptions** and click **Add Subscription** +2. **Name**: enter a recognizable name, such as `Flashduty` + +You need permission to manage subscriptions. + + + + + +In the filter's **Event Categories**, select these five: + +- Deployment queued +- Deployment started +- Deployment succeeded +- Deployment failed +- Deployment canceled + +Narrow the scope with the Projects, Environments, and other filters if needed. + + + + + +Under **Webhook Notifications**, turn the **Enabled** switch on (it is off by default and nothing is sent while it is off), then set **Payload URL** to the full push URL of the Flashduty integration. Leave the header empty: Flashduty authenticates with the `integration_key` in the push URL. Save the subscription. + + + + +Octopus Deploy has no test button. After saving, run a deployment and the change appears in the Flashduty change list. The change link depends on the Octopus server address in the payload. Octopus Cloud includes it automatically; for a self-hosted instance, set the public URL under **Configuration → Nodes → Configuration Settings**, otherwise the payload carries no server address and the change has no link. + +## What one change is +--- + +| Octopus object | Change key (change_key) | Notes | +|---|---|---| +| Deployment | The deployment ID, for example `Deployments-12519` | The queued, started, and finished events of one deployment are one change. Deploying the same release to the same environment again is another deployment, so another change | + +## Status mapping +--- + +| Octopus event category | Flashduty change status | +|---|---| +| Deployment queued (DeploymentQueued) | Ready | +| Deployment started (DeploymentStarted) | Processing | +| Deployment succeeded (DeploymentSucceeded) | Done | +| Deployment failed (DeploymentFailed) | Failed | +| Deployment canceled | Canceled | + +These deliveries return success but record no change: + +- Deliveries without an event category, and event categories that are not deployments (creation and modification of projects, releases, environments, deployment targets, and so on) +- Deployment resumed and Deployment precondition evaluated, which do not change the outcome of the deployment + +A category starting with `Deployment` that Flashduty does not recognize returns `InvalidParameter` with the category name in the message; other events are not affected. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: deploy to `, for example `Example Project: deploy 0.1.178 to Development` | +| Description | The Octopus event message, for example `Deploy to Development failed for Example Project release 0.1.178 to Development` | +| Link | The deployment's page in Octopus | +| Time | When the event occurred in Octopus (`Occurred`) | + +Labels can be used for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `project` / `project_id` | Project name / ID | +| `environment` / `environment_id` | Environment name / ID | +| `release` / `release_id` | Release version / ID | +| `deployment_id` | Deployment ID | +| `space_id` | Space ID | +| `actor` | User that triggered the event; `system` for automatic deployments | +| `octopus_state` | Octopus event category, for example `DeploymentFailed` | + +Names are read from the event message. When one cannot be read, its label is empty and the title uses the ID instead. + +## FAQ +--- + + + + +No. Octopus does not guarantee that each event is sent only once; a repeated event has the same occurrence time and category, and Flashduty records it once. + + + + + +- `Payload.Event.RelatedDocumentIds has no Deployments- id`: the deployment event carries no deployment ID; make sure the delivery comes from an Octopus subscription +- `unknown deployment event category`: a deployment event category we do not handle yet; contact us + + + + + +Octopus only includes the server address in the payload when a public URL is configured. See the setup notes above. + + + diff --git a/en/on-call/integration/change-integration/rundeck.mdx b/en/on-call/integration/change-integration/rundeck.mdx new file mode 100644 index 000000000..471bf4ff5 --- /dev/null +++ b/en/on-call/integration/change-integration/rundeck.mdx @@ -0,0 +1,135 @@ +--- +title: "Rundeck change integration" +description: "Sync every execution of your Rundeck jobs to Flashduty On-call through Rundeck's webhook notification, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Rundeck", "webhook notification", "job execution", "runbook automation"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use the [webhook notification](https://docs.rundeck.com/docs/manual/notifications/webhooks.html) of a Rundeck job to sync its executions to Flashduty On-call. Each execution becomes one Flashduty change; the execution's start and end update that same change. + +Rundeck cannot tell whether a job changes production, so add the notification only to **jobs that deploy or modify things**, not to read-only check jobs. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Rundeck** and enter an integration name +3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project` or `job` +4. Click **Save** and copy the generated **Push URL** + +
+ +## Configure Rundeck +--- + + + + +Open the job to sync, click **Edit**, and switch to the **Notifications** tab. + + + + + +Add a notification of type **Send Webhook** for each of **On Start**, **On Success**, **On Failure**, and **On Retryable Failure**: + +1. **URL(s)**: the full Push URL of the Flashduty integration +2. **Payload Format**: select `JSON`. Rundeck defaults to XML, which Flashduty does not accept +3. **Method**: select `POST` + +All four triggers are needed: On Start makes the change appear when the execution starts; On Success and On Failure give the end status; when the job has **Retry** set, the failed attempt sends only On Retryable Failure and not On Failure, so without it the change stays at Processing. + +The notification can also live in the `notification` section of the job definition (YAML or XML) and be applied with `rd jobs load` or a project import. + + + + + +Save and run the job once; the change appears in the Flashduty change list. The webhook notification has no test button. When Rundeck fails to reach Flashduty, it logs `Notification failed` in the Rundeck server log only; a delivery that Flashduty rejects is not shown on the job page. + + + + +## What one change is +--- + +Each job execution is one change. The change key (change_key) is Rundeck's execution id, for example `4711`. + +- The start and end notifications of one execution update the same change +- Two executions of the same job are two changes +- When a failed job is retried automatically, each retry is a new execution and therefore a new change +- An execution id is unique within one Rundeck server. Create a separate integration for each Rundeck server; otherwise equal execution ids from different servers merge into one change + +## Status mapping +--- + +| Trigger | Execution status (status) | Flashduty change status | +|---|---|---| +| On Start | running | Processing | +| On Success | succeeded | Done | +| On Failure | failed | Failed | +| On Failure | timedout (execution timeout) | Failed | +| On Failure | missed (missed its schedule) | Failed | +| On Failure | aborted (killed) | Canceled | +| On Retryable Failure | failed-with-retry | Failed | + +Done, Failed, and Canceled are end statuses; Flashduty records the change's end time. + +`On Average Duration Exceeded` reports an execution that is still running, not a new stage; Flashduty accepts it and records nothing. + +## Change content +--- + +| Field | Content | +|---|---| +| Title | `: run /`, for example `ops: run release/prod/deploy-app`; `: run execution ` when the job was deleted | +| Description | The job's description; empty when the job has none | +| Link | The execution's page in Rundeck | + +Labels can be used for routing and for filtering the change list: + +| Label | Description | +|---|---| +| `project` | Rundeck project name | +| `job` | Job name | +| `job_group` | Job group | +| `job_id` | Job ID | +| `execution_id` | Execution ID | +| `execution_type` | Execution type: `user` (manual), `scheduled`, or `user-scheduled` | +| `actor` | The user who started the execution | +| `rundeck_state` | Latest execution status | + +Job option values may contain secrets and are not recorded. + +## FAQ +--- + + + + +- Check that **Payload Format** is `JSON` +- Check that On Start, On Success, On Failure, and On Retryable Failure each have a notification +- Only job executions send notifications; ad hoc commands run from the **Commands** page do not +- Search the Rundeck server log for `Notification failed` to see why a delivery failed + + + + + +The end notification did not arrive. Common causes are a job with retries but no **On Retryable Failure** notification, or a network path from Rundeck to Flashduty that is down. Rundeck tries each notification once and does not resend it. + + + + + +Flashduty rejects a delivery in these cases: + +- `must use format JSON`: the notification's **Payload Format** is `XML` +- `execution is missing` or `execution.id is missing`: the body has no execution; check that it comes from a Rundeck webhook notification +- `unsupported status`: an execution status Flashduty does not support yet, for example a custom job status (`other`); contact us + + + diff --git a/en/on-call/integration/change-integration/unleash.mdx b/en/on-call/integration/change-integration/unleash.mdx new file mode 100644 index 000000000..47fa3bdea --- /dev/null +++ b/en/on-call/integration/change-integration/unleash.mdx @@ -0,0 +1,128 @@ +--- +title: "Unleash change integration" +description: "Sync Unleash feature flag changes to Flashduty On-call through an Unleash webhook integration, as change events you can correlate with alerts and incidents." +keywords: ["change integration", "Unleash", "Feature Flag", "feature flag", "Webhook"] +--- + +**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use an Unleash webhook integration to sync feature flag changes to Flashduty On-call. Each Unleash event becomes one Flashduty change, for example enabling or disabling a flag in an environment, adding or editing a strategy, changing variants, or archiving a flag. + +Unleash sends changes that have already taken effect, so each change is recorded as **Done** directly. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Unleash** and enter an integration name +3. To send changes to a specific channel, add rules in the integration's **Route** on labels such as `project`, `environment` and `flag` +4. Click **Save** and copy the generated **push URL** + +
+ +## Configure in Unleash +--- + + + + +1. Open the Unleash admin UI and go to **Integrations** +2. On the **Webhook** card, click **New integration** + +You need permission to manage integrations. + + + + + +1. **Webhook URL**: paste the full push URL from the Flashduty integration +2. **Content-Type**: keep the default `application/json` +3. **Authorization** and **Extra HTTP Headers**: leave empty; Flashduty authenticates with the `integration_key` in the push URL +4. **Body template**: leave empty. With no template Unleash sends the full event JSON, which is the format Flashduty parses + + + + + +1. **Events**: select the events below; other events are ignored + - `feature-created`, `feature-updated`, `feature-archived`, `feature-revived` + - `feature-environment-enabled`, `feature-environment-disabled` + - `feature-strategy-add`, `feature-strategy-update`, `feature-strategy-remove` + - `feature-variants-updated` +2. **Projects** and **Environments**: leave empty for all, or select only the scope you care about, such as production +3. Click **Save** + + + + +Unleash has no test-delivery button. After saving, change any flag (for example enable an environment) and the record appears in the Flashduty change list. + +## What one change is +--- + +| Unleash object | Change key (`change_key`) | Notes | +|---|---|---| +| Event | The event's `id` | Each action produces one event, which is one Flashduty change; enabling a flag and disabling it again are two changes | + +Event `id` increments within one Unleash instance. Create one integration per Unleash instance: if several instances share an integration, events with the same `id` are treated as the same change. + +## Status mapping +--- + +| Unleash event | Flashduty change status | +|---|---| +| `feature-created`, `feature-updated`, `feature-archived`, `feature-revived`, `feature-environment-enabled`, `feature-environment-disabled`, `feature-strategy-add`, `feature-strategy-update`, `feature-strategy-remove`, `feature-variants-updated` | Done | + +These deliveries return success but create no change: + +- Change request events such as `change-request-created`, `change-request-approved` and `change-request-applied`. When a change request is applied, Unleash sends one of the events in the table above for each flag change in it, and those are recorded +- Events that do not alter how a flag evaluates: tags, stale markers, description and type, project moves +- Events about other resources (projects, environments, users, segments) and deliveries without a `type` + +## Change content +--- + +| Field | Content | +|---|---| +| Title | ` in : `, for example `new-feature in production: enabled`; events with no environment (such as creating a flag) omit it | +| Description | Empty | +| Link | Empty. Unleash events carry no page URL | + +Labels for routing and for filtering the change list: + +| Label | Meaning | +|---|---| +| `project` | Project ID | +| `environment` | Environment name, such as `production`; absent for events with no environment | +| `flag` | Flag name | +| `strategy` | Strategy name, such as `flexibleRollout` (strategy events only) | +| `actor` | The actor, set only when it is an API token or service account; a user's email is never written to a label | +| `event_type` | Unleash event type, such as `feature-environment-enabled` | +| `event_id` | Unleash event ID | + +## FAQ +--- + + + + +No. When a delivery fails (a 50x or a network error) Unleash retries once with the same content, and Flashduty records it once. Unleash does not guarantee delivery order; Flashduty uses the event's own time (`createdAt`) as the change time. + + + + + +A change request does not alter production behavior until it is applied. On apply, Unleash sends the matching `feature-*` event for each flag change in it, and Flashduty records those events. + + + + + +- `id is missing`, `featureName is missing`: the body is incomplete. Make sure **Body template** is empty +- `invalid createdAt`: the event time is not in a valid format +- Body is not JSON: make sure **Content-Type** is `application/json` and that any **Body template** renders valid JSON + + + diff --git a/en/on-call/integration/change-integration/vercel.mdx b/en/on-call/integration/change-integration/vercel.mdx new file mode 100644 index 000000000..89a2c07b2 --- /dev/null +++ b/en/on-call/integration/change-integration/vercel.mdx @@ -0,0 +1,139 @@ +--- +title: "Vercel change integration" +description: "Sync deployments, promotions and rollbacks from a Vercel team webhook to Flashduty On-call as change events correlated with alerts and incidents." +keywords: ["change integration", "Vercel", "Deployment", "deployment events", "Instant Rollback", "Webhook"] +--- + +**Plan requirement**: This feature requires the On-call Standard plan or above. [Learn more](https://flashcat.cloud/flashduty/price/) + +Use a Vercel team webhook to sync deployments and production rollbacks (Instant Rollback) to Flashduty On-call. Each deployment becomes one Flashduty change; every state of the deployment, from created and built to succeeded, promoted, failed or canceled, updates that same change. + +Vercel team webhooks are available to Pro and Enterprise teams only; Hobby accounts cannot configure them. + +
+ +## In Flashduty On-call +--- + +1. In the Flashduty console, go to **Integration Center → Change Events** +2. Select **Vercel** and enter an integration name +3. To assign changes to specific channels, configure rules in the integration's **Routing** based on labels such as `project` or `environment` +4. Click **Save** and copy the generated **Push URL** + +
+ +## In Vercel +--- + + + + +In the Vercel dashboard, switch to the target team and go to **Settings → Webhooks**. You need permission to manage the team's webhooks. + + + + + +Under **Deployment Events**, select: + +- **Deployment Created** +- **Deployment Succeeded** +- **Deployment Promoted** +- **Deployment Rollback** +- **Deployment Error** +- **Deployment Cancelled** + +Project, Feature Flag and Firewall events are not deployment changes; if selected, Flashduty returns success without recording a change. + + + + + +1. Choose the projects to send: **All Team Projects** or specific projects +2. **Endpoint URL**: paste the full Flashduty push URL +3. Click **Create Webhook** + +Vercel then shows a secret. Flashduty does not need it; requests are authenticated by the `integration_key` in the push URL. + + + + +## What one change is +--- + +| Vercel object | Change key (change_key) | Notes | +|---|---|---| +| Deployment | `deployment:` | Every event of one deployment (an ID starting with `dpl_`) updates the same change; two deployments of the same project and commit are two changes | +| Rollback | `rollback::` | An Instant Rollback is a separate change and does not modify the records of the replaced or restored deployment | + +## Status mapping +--- + +| Vercel event | Flashduty change status | +|---|---| +| `deployment.created` | Ready | +| `deployment.ready` (built, checks running) | Processing | +| `deployment.succeeded` | Done | +| `deployment.promoted` (now serving production traffic) | Done | +| `deployment.error` | Failed | +| `deployment.canceled` | Canceled | +| `deployment.rollback` | Done | + +Done, Failed and Canceled are end states; Flashduty records the change's end time. + +These deliveries return success without recording a change: event types that do not start with `deployment.` (Project, Feature Flag, Firewall and others); deployment events about checks or integration actions; `deployment.cleanup` (the deployment is permanently deleted after its retention period, which does not change its earlier result). + +## Change content +--- + +| Field | Deployment | Rollback | +|---|---|---| +| Title | `: deploy () to `, or the deployment URL when there is no Git metadata | `: roll back production to ` | +| Description | First line of the Git commit message | Empty | +| Link | The deployment's page in the Vercel dashboard | Empty (Vercel rollback events carry no link) | + +Labels can be used for routing and for filtering the change list: + +| Label | Deployment | Rollback | +|---|---|---| +| `project` | Project name | — | +| `project_id` | Project ID (starts with `prj_`) | Same | +| `environment` | `production`, a custom environment such as `staging`, or `preview` when no target is set | `production` | +| `ref` | Git branch | — | +| `sha` | Full commit SHA | — | +| `actor` | Git username of the commit author | — | +| `deployment_id` | Deployment ID | — | +| `from_deployment_id` / `to_deployment_id` | — | IDs of the replaced / restored deployment | +| `state` | Latest Vercel event, for example `succeeded` | `rollback` | + +`ref`, `sha` and `actor` come from the deployment metadata of a connected GitHub, GitLab or Bitbucket repository; deployments made directly from the CLI do not have them. + +## FAQ +--- + + + + +After a production deployment builds successfully, Vercel sends `deployment.succeeded`, then `deployment.promoted` once production traffic has switched to it. Both map to Done and update the same change. + + + + + +No. Flashduty uses the time carried by the Vercel event, so the same event at the same time is recorded once. When a delivery fails, Vercel retries it for up to 24 hours. + + + + + +Rolling back from the same deployment to the same deployment produces the same change key, so the second rollback updates the first rollback's change (its last time becomes the second rollback's time) instead of creating a new one. Vercel rollback events carry only the two deployment IDs, not a rollback ID of their own. + + + + + +- `unsupported type`: Flashduty received a deployment event it does not support yet (for example `deployment.blocked` subscribed through the API). Select only the six events listed above, or contact us +- `payload.deployment.id is missing`: the payload is incomplete; make sure the request comes from a native Vercel webhook + + + diff --git a/en/on-call/integration/webhooks/alert-webhook.mdx b/en/on-call/integration/webhooks/alert-webhook.mdx index ec60001d3..4e1f7fff2 100644 --- a/en/on-call/integration/webhooks/alert-webhook.mdx +++ b/en/on-call/integration/webhooks/alert-webhook.mdx @@ -103,6 +103,7 @@ alt | string | Yes | Caption; may be an empty string | images | [][Image](#Image) | Yes | Alert image list; null when there are no images | | labels | map[string]string | No | Label KV, both Key and Value are strings | | event_cnt | int64 | No | Associated event count | +| detail_url | string | No | Console page for this alert, in the form `{console}/alert/detail/{alert_id}`; the field is omitted when the deployment has no console base configured | | incident | [Incident](#Incident) | No | Associated incident | diff --git a/en/rum/best-practices/sampling.mdx b/en/rum/best-practices/sampling.mdx index b29468e21..094ad3855 100644 --- a/en/rum/best-practices/sampling.mdx +++ b/en/rum/best-practices/sampling.mdx @@ -309,7 +309,11 @@ The base rule uses `hash(userId) % 100` instead of `Math.random()`, which brings ## Best practice 3: full error capture with proportional sampling for the rest -A common requirement is "cut data volume to 20%, but never miss an error". Setting `sessionSampleRate` to 20 will not do it: sampling works per session, and a session that loses the draw reports nothing at all — errors included (rule 1). You would lose roughly four fifths of your errors along with the volume. The correct shape is to collect every session so no error is lost, then bucket on a stable key inside `beforeSend` so only the winning share keeps full data: + +Starting with Web SDK **0.3.0**, enable `sessionOnError` (and `sessionReplayOnError` if you need error replays) to capture error sessions without writing your own `beforeSend`; see [on-error session capture](/en/rum/sdk/web/advanced-config#on-error-session-capture) for configuration, billing, and limitations. The recipe below remains available for older versions or custom event filtering. Its failed-request filtering differs from the new options: a failed resource event alone does not trigger on-error capture. + + +A common requirement is "cut data volume to 20%, but never miss an error". Setting `sessionSampleRate` to 20 will not do it: sampling works per session, and a session that loses the draw reports nothing at all — errors included (rule 1). You would lose roughly four fifths of your errors along with the volume. The custom filtering recipe below collects every session so no error is lost, then buckets on a stable key inside `beforeSend` so only the winning share keeps full data: - **Error events**: always kept — 100% of errors - **Failed requests**: always kept — 100% of API failures (HTTP 5xx and request failures are resource events, not error events) diff --git a/en/rum/quickstart/app-management.mdx b/en/rum/quickstart/app-management.mdx index ca7a20b6c..b4b0bc691 100644 --- a/en/rum/quickstart/app-management.mdx +++ b/en/rum/quickstart/app-management.mdx @@ -297,7 +297,7 @@ After disabling geo-location or IP address collection, the related filter and an The **Remote Configuration** tab lets you adjust collection and privacy parameters online, without code changes or a new release. When enabled, the configuration on this page overrides SDK initialization settings. When disabled, clients fall back to their SDK initialization settings and data collection continues uninterrupted. -- Remote Configuration is currently available for **Browser**, **iOS**, **Android** and **WeChat Mini Program** applications. Other platform types will be enabled as their SDKs ship support. +- Remote Configuration is currently available for **Browser**, **iOS**, **Android**, **Flutter** and **WeChat Mini Program** applications. Other platform types will be enabled as their SDKs ship support. - On SaaS the feature is rolled out account by account. If the **Remote Configuration** tab is not visible on the application detail page, contact support to enable it. On private deployments it is available by default. @@ -307,11 +307,15 @@ The **Remote Configuration** tab lets you adjust collection and privacy paramete |------|------|------| | **Session sample rate** | Integer 0–100 (%) | Percentage of sessions collected. Leave it empty to skip delivering this field; clients keep the value set at SDK initialization | | **Session replay sample rate** | Integer 0–100 (%) | Percentage of sessions recorded by Session Replay. If empty, the SDK setting applies | +| **On-error session capture** (`sessionOnError`) | On / Off / Use SDK setting | For sessions missed by session sampling, uploads up to the last minute of events on error and continues collection; requires Web SDK 0.3.0 or later | +| **On-error replay capture** (`sessionReplayOnError`) | On / Off / Use SDK setting | For collected sessions missed by replay sampling, uploads buffered replay on error and continues recording; requires Web SDK 0.3.0 or later | | **Trace sample rate** | Integer 0–100 (%) | A second session-level sampling pass within already-collected sessions, deciding which sessions inject trace headers into eligible requests; the outcome is consistent within one session. Overall trace coverage is roughly *session sample rate × trace sample rate*. If empty, the SDK setting applies | | **Replay privacy level** | `mask` / `mask-user-input` / `allow` | Default masking of page content in Session Replay: `mask` obscures text and hides input values; `mask-user-input` keeps page text and hides only what users typed; `allow` records the page as it is. Loosening the level starts collecting content that was not collected before, and replays already uploaded cannot be retroactively masked. The console asks you to confirm again before publishing | | **Custom configuration keys** | Key–value pairs typed as string / number / boolean / JSON | Delivered to clients together with the remote configuration and read by your application code; the platform does not interpret them. Up to 5 keys; each key name is at most 64 bytes (counted in UTF-8, not characters), each value at most 4 KB and nesting at most 3 levels (objects and arrays each count one level), and all custom entries together at most 16 KB | -iOS, Android, and WeChat Mini Program applications also show the **Remote Configuration** tab, but their SDKs read only the **session sample rate** and **custom configuration keys** (none of the three has Session Replay; the other values are neither delivered nor effective). Every SDK has to opt in with `remoteConfigurationEnabled: true` at initialization (off by default; an application that has not opted in never requests the configuration). On iOS this requires SDK 0.6.0 or later, see [iOS SDK Advanced Configuration](/en/rum/sdk/ios/advanced-config#remote-configuration); on Android it requires SDK 0.7.0 or later, see [Android SDK Advanced Configuration](/en/rum/sdk/android/advanced-config#remote-configuration-adjust-the-sample-rate-from-the-console). +The two on-error options are independent: **On** delivers `true`, **Off** delivers `false`, and **Use SDK setting** omits the field so the corresponding `init()` option applies (off if unset). Browser applications require Web SDK 0.3.0 or later with `remoteConfigurationEnabled: true` at initialization. Turning off on-error capture does not affect sessions selected by ordinary sampling. See [Web SDK on-error session capture](/en/rum/sdk/web/advanced-config#on-error-session-capture) for scope, billing, and limitations. + +iOS, Android, Flutter, and WeChat Mini Program applications also show the **Remote Configuration** tab, but their SDKs read only the **session sample rate** and **custom configuration keys** (none of them has Session Replay; the other values are neither delivered nor effective). Every SDK has to opt in with `remoteConfigurationEnabled: true` at initialization (off by default; an application that has not opted in never requests the configuration). On iOS this requires SDK 0.6.0 or later, see [iOS SDK Advanced Configuration](/en/rum/sdk/ios/advanced-config#remote-configuration); on Android it requires SDK 0.7.0 or later, see [Android SDK Advanced Configuration](/en/rum/sdk/android/advanced-config#remote-configuration-adjust-the-sample-rate-from-the-console); on Flutter it requires `flashcat_flutter_plugin` 0.2.0 or later, see [Flutter SDK Advanced Configuration](/en/rum/sdk/flutter/advanced-config#remote-configuration). Custom entries are delivered to clients and may be readable by end users. Never put secrets, access tokens, or personally sensitive information in them. diff --git a/en/rum/quickstart/faq.mdx b/en/rum/quickstart/faq.mdx index 52b1b2784..97eda8032 100644 --- a/en/rum/quickstart/faq.mdx +++ b/en/rum/quickstart/faq.mdx @@ -20,7 +20,7 @@ Confirm that the RUM SDK is correctly imported: ```html CDN Integration