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..ea38f102a 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -4494,13 +4494,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 +4577,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..770ca7810 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -4494,13 +4494,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 +4577,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 b7d93e9d8..ea21d4c7a 100644 --- a/docs.json +++ b/docs.json @@ -1774,7 +1774,17 @@ { "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" ] }, { @@ -3172,7 +3182,17 @@ { "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" ] }, { 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/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/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/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/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/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/integration-docs/src/doc-map.mjs b/integration-docs/src/doc-map.mjs index 6f4a513ed..6a75a7fa4 100644 --- a/integration-docs/src/doc-map.mjs +++ b/integration-docs/src/doc-map.mjs @@ -100,6 +100,16 @@ export const docMap = { Rizhiyi: `${alertBase}/rizhiyi.mdx`, CustomChange: `${integrationBase}/change-integration/custom-event.mdx`, + GithubChange: `${integrationBase}/change-integration/github.mdx`, + GitlabChange: `${integrationBase}/change-integration/gitlab.mdx`, + HcpTerraformChange: `${integrationBase}/change-integration/hcp-terraform.mdx`, + ArgocdChange: `${integrationBase}/change-integration/argocd.mdx`, + NetlifyChange: `${integrationBase}/change-integration/netlify.mdx`, + VercelChange: `${integrationBase}/change-integration/vercel.mdx`, + JfrogArtifactoryChange: `${integrationBase}/change-integration/jfrog-artifactory.mdx`, + BuildkiteChange: `${integrationBase}/change-integration/buildkite.mdx`, + LaunchdarklyChange: `${integrationBase}/change-integration/launchdarkly.mdx`, + JenkinsChange: `${integrationBase}/change-integration/jenkins.mdx`, Jira: { zh: 'legacy/zh/jira-change.md', en: 'legacy/en/jira-change.md', diff --git a/zh/on-call/incident/search-view-incident.mdx b/zh/on-call/incident/search-view-incident.mdx index 8b9541d2c..b0e70f781 100644 --- a/zh/on-call/incident/search-view-incident.mdx +++ b/zh/on-call/incident/search-view-incident.mdx @@ -278,7 +278,7 @@ AI SRE 代某位成员执行的动作（例如[自动化规则](/zh/ai-sre/autom | 列 | 说明 | | :--- | :--- | -| **状态** | 变更事件的当前状态，包括已提单、即将开始、进行中、已取消、已完成 | +| **状态** | 变更事件的当前状态，包括已提单、即将开始、进行中、已取消、已完成、失败 | | **Change Key** | 变更事件的唯一标识 | | **标题** | 变更事件的简要描述 | | **描述** | 变更事件的详细说明 | diff --git a/zh/on-call/integration/change-integration/argocd.mdx b/zh/on-call/integration/change-integration/argocd.mdx new file mode 100644 index 000000000..7f4794b48 --- /dev/null +++ b/zh/on-call/integration/change-integration/argocd.mdx @@ -0,0 +1,220 @@ +--- +title: "Argo CD 变更集成" +description: "通过 Argo CD Notifications 的 Webhook 服务将应用同步（Sync）操作同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "Argo CD", "ArgoCD", "GitOps", "Sync", "Notifications", "Webhook", "部署事件"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +Argo CD 通过内置的 **Notifications**（`argocd-notifications-controller`）推送变更：本集成提供一段 `argocd-notifications-cm` 配置，包含一个 Webhook 服务、一个请求体模板和一个触发器。Argo CD 应用（Application）的每一次同步（Sync）操作对应一条 Flashduty 变更，同步开始时记录为 Processing，结束时更新为 Done、Failed 或 Canceled。 + +自动同步、在界面或 CLI 中手动同步、回滚（Rollback）都是同步操作，都会记录。应用的同步失败、健康降级告警请使用 Argo CD 告警集成，两者可以同时配置。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **Argo CD**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `application`、`project`、`destination_namespace`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 Argo CD 中配置 +--- + +以下操作需要能修改 Argo CD 所在命名空间（默认 `argocd`）中 ConfigMap 的 Kubernetes 权限，以及修改 Application 或 AppProject 注解的权限。Argo CD 集群需要能访问推送地址所在的域名。 + + + + +把下面的内容保存为 `flashduty-change.yaml`，将 `url` 替换为上一步复制的推送地址（包含 `?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] +``` + +合并到现有的 `argocd-notifications-cm`（`--type merge` 只增改上面这些键，不影响已有配置）： + +```bash +kubectl patch configmap argocd-notifications-cm -n argocd --type merge --patch-file flashduty-change.yaml +``` + +如果 Argo CD 通过 Helm Chart 安装，请把 `service.webhook.flashduty-change` 写到 `notifications.notifiers`，模板写到 `notifications.templates`，触发器写到 `notifications.triggers`，否则下次升级会覆盖手动修改。 + +配置说明： + +- 模板中的每个值都经过 `toJson` 转义，同步信息中的引号和换行不会破坏 JSON，请不要去掉。字段名不要修改，`app_uid`、`phase` 和 `started_at` 必须保留 +- 可选字段通过 `dig` 读取，应用从未同步过、同步尚未产生结果时模板也能正常渲染 +- 触发器的两个条件分别对应同步开始和同步结束。`oncePer` 取同步操作的开始时间，保证每一次同步操作的开始和结束各发送一次，即使连续两次同步之间 Argo CD 没有观察到中间状态，请不要去掉 +- 服务名 `flashduty-change` 与告警集成使用的 `flashduty` 不同，两个集成的推送地址互不影响 +- `argocd_url` 取自 `argocd-notifications-cm` 的 `context.argocdUrl`，用于生成变更链接；未配置时变更没有链接，不影响记录 + + + + + +触发器需要被订阅后才会发送。按需要的范围选择一种方式： + +- **单个应用**：在 Application 上添加注解 + + ```bash + kubectl patch application <应用名> -n argocd --type merge \ + -p '{"metadata":{"annotations":{"notifications.argoproj.io/subscribe.on-flashduty-change.flashduty-change":""}}}' + ``` + +- **一个项目下的所有应用**：在 AppProject 的 `metadata.annotations` 中添加同样的注解 `notifications.argoproj.io/subscribe.on-flashduty-change.flashduty-change: ""` +- **所有应用**：在 `argocd-notifications-cm` 的 `subscriptions` 中添加一项。如果已有 `subscriptions`（例如告警集成添加的那一项），请在原列表中追加，不要用上一步的 merge 命令整体覆盖 + + ```yaml + subscriptions: | + - recipients: + - flashduty-change + triggers: + - on-flashduty-change + ``` + +订阅生效时，已经同步过的应用会立即发送一次最近一次同步的结果，Flashduty 会按该次同步原本的开始、结束时间记录为一条变更。 + + + + + +Argo CD 没有发送测试消息的按钮。可以在 `argocd-notifications-controller` Pod 中用 `argocd admin notifications template notify` 按应用当前状态发送一次通知： + +```bash +kubectl exec -n argocd deploy/argocd-notifications-controller -- \ + /usr/local/bin/argocd admin notifications template notify flashduty-change <应用名> --recipient flashduty-change +``` + +命令会打印请求和响应的调试日志，其中包含完整的推送地址（含 `integration_key`），请不要把输出贴到公开位置。输出中 `Received response:` 一行的状态为 `200 OK` 即表示 Flashduty 已接受请求。应用同步过时，这条通知就是最近一次同步的结果，与该次同步已有的记录合并，不会新增变更；应用从未同步过时，Flashduty 直接忽略。 + + + + + +同步一个已订阅的应用（在界面点击 **Sync**，或执行 `argocd app sync <应用名>`），确认 Flashduty 的变更列表中出现一条 Processing 的变更，同步结束后更新为 Done 或 Failed。 + + + + +## 一条变更是什么 +--- + +一条变更对应一个应用的一次同步操作，变更标识（change_key）为 `/`： + +- `app_uid` 是应用的 `metadata.uid`。Kubernetes 为每个对象分配的 UID 在集群的整个生命周期内唯一，不同 Argo CD 实例中同名的应用、删除后重建的应用都是不同的应用 +- `started_at` 是同步操作的开始时间（`status.operationState.startedAt`，按 UTC 记录）。Argo CD 在同步开始时写入这个时间，重试期间保持不变，一个应用同一时刻只运行一个同步操作 + +因此同一次同步的开始、失败重试和最终结果更新同一条变更；同一个应用的两次同步是两条变更，即使同步的是同一个版本。应用名称、项目、版本和同步信息的变化不会改变变更标识。 + +请求缺少 `app_uid` 或 `started_at`，或者时间不是 RFC 3339 格式时，Flashduty 会拒绝该请求。 + +## 状态映射 +--- + +| Argo CD 同步阶段（`phase`） | Flashduty 变更状态 | +|---|---| +| `Running`、`Terminating` | Processing | +| `Succeeded` | Done | +| `Failed`、`Error` | Failed | +| `Failed`，信息为 `Operation terminated`（在界面点击 **Terminate** 或执行 `argocd app terminate-op`） | Canceled | + +Done、Failed 和 Canceled 是结束状态，Flashduty 会记录变更结束时间。因同步超时被 Argo CD 终止的操作（信息包含 `triggered by controller sync timeout`）记为 Failed。 + +同步阶段区分大小写，其他值会被拒绝。以下推送返回成功但不生成变更：应用还没有同步操作（`phase` 为空）、试运行（Dry Run）同步。 + +同步开始时记录的时间是 `started_at`，结束时是 `finished_at`。Argo CD 失败后自动重试期间，同步阶段保持 `Running`，不会提前记为 Failed。 + +## 变更内容 +--- + +- **标题**：`<应用名>: sync <版本> to <目标命名空间>`。版本为 Git 提交时显示前 7 位，Helm Chart 版本等其他值原样显示；没有版本或目标命名空间时省略对应部分 +- **链接**：`/applications/<应用名>`，配置了 `context.argocdUrl` 时才有 + +标签可用于路由和在变更列表中筛选： + +| 标签 | 说明 | +|---|---| +| `application` | 应用名 | +| `app_uid` | 应用的 `metadata.uid` | +| `app_namespace` | Application 对象所在的命名空间 | +| `project` | 应用所属的 Argo CD 项目 | +| `destination` | 目标集群名称，未设置名称时为集群地址 | +| `destination_namespace` | 目标命名空间 | +| `revision` | 同步的版本（Git 提交或 Chart 版本） | +| `actor` | 发起同步的用户；自动同步为 `automated` | +| `phase` | 最新的同步阶段 | +| `message` | 最新的同步信息，例如失败原因，超过 1024 字节时截断 | + +值为空的字段不会写入标签。 + +## 常见问题 +--- + + + + +- 查看 `argocd-notifications-controller` 的日志（`kubectl logs -n argocd deploy/argocd-notifications-controller`），确认应用上有 `notifications.argoproj.io/subscribe.on-flashduty-change.flashduty-change` 注解，或 `subscriptions` 中包含 `on-flashduty-change` +- 日志中出现 `template 'flashduty-change' is not supported` 或 `trigger 'on-flashduty-change' is not configured` 时，确认配置已写入 `argocd-notifications-cm`，Helm 安装请检查对应的 values + + + + + +同步在几秒内完成时，Argo CD 可能没有观察到 `Running` 阶段，只发送结束通知。Flashduty 会直接按结束状态记录这条变更。 + + + + + +不会。同一阶段、同一时间的事件只记录一次。 + + + + + +确认模板与本文一致，所有值都经过 `toJson`。响应内容会指出缺少或不支持的字段，例如 `app_uid is missing`、`started_at is missing`、`unsupported phase`。 + + + + +相关配置请参阅 Argo CD 文档 [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/) 和 [Subscriptions](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/subscriptions/)。 diff --git a/zh/on-call/integration/change-integration/buildkite.mdx b/zh/on-call/integration/change-integration/buildkite.mdx new file mode 100644 index 000000000..85abb94b9 --- /dev/null +++ b/zh/on-call/integration/change-integration/buildkite.mdx @@ -0,0 +1,123 @@ +--- +title: "Buildkite 变更集成" +description: "通过 Buildkite Webhook 将流水线构建同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "Buildkite", "构建", "部署", "Webhook", "CI/CD"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +通过 Buildkite 组织的 Webhook 通知服务，将流水线的构建（Build）同步到 Flashduty On-call。每一次构建对应一条 Flashduty 变更；构建从排队、运行、出现失败到通过、失败或取消的每个状态，都会更新同一条变更。 + +建议只为部署类流水线开启推送：在 Webhook 中选择对应的流水线，或用分支过滤只推送发布分支的构建。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **Buildkite**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `pipeline`、`ref`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 Buildkite 中配置 +--- + + + + +进入 Buildkite 组织的 **Settings → Notification Services**，在 **Webhook** 一栏点击 **Add**。需要组织管理员权限。 + + + + + +1. **Description**：填写便于识别的名称，例如 `Flashduty` +2. **Webhook URL**：粘贴 Flashduty 集成的完整推送地址 +3. **Token**：保持默认即可，Flashduty 通过推送地址中的 `integration_key` 鉴权 + + + + + +1. 在 **Events** 中勾选 `build.scheduled`、`build.running`、`build.failing`、`build.finished` 和 `build.skipped` +2. 在 **Pipelines** 中选择要推送的流水线（全部、指定流水线、指定团队或集群的流水线） +3. 如需只推送部分分支，在 **Branch filtering** 中填写分支规则，留空表示所有分支 +4. 点击 **Add Webhook Notification** 保存 + + + + +## 一条变更是什么 +--- + +一次构建是一条变更，变更标识（change_key）是构建的 `build.id`（Buildkite 平台内唯一的 UUID）。同一次构建的所有 `build.*` 事件更新同一条变更；同一流水线、同一分支的两次构建是两条变更，重新构建（Rebuild）也会产生新的构建和新的变更。 + +## 状态映射 +--- + +Flashduty 按推送内容中的 `build.state` 确定状态： + +| Buildkite 构建状态 | Flashduty 变更状态 | +|---|---| +| blocked（等待 block step 解除） | Planned | +| creating、scheduled、waiting | Ready | +| running、failing、waiting_failed、canceling | Processing | +| passed | Done | +| failed | Failed | +| canceled、skipped、not_run | Canceled | + +Done、Failed 和 Canceled 是结束状态，Flashduty 会记录变更结束时间。等待 block step 的构建以 `build.finished` 推送，状态为 `passed` 且 `blocked` 为 `true`，Flashduty 将其记为 Planned，构建继续运行并结束后更新为最终状态。 + +以下推送返回成功但不生成变更：`ping`、`job.*`、`agent.*`、`cluster_token.*` 等非构建事件。 + +## 变更内容 +--- + +| 字段 | 内容 | +|---|---| +| 标题 | `<流水线名称>: build #<构建号> on <分支>` | +| 描述 | 构建的 message，通常是提交信息 | +| 链接 | Buildkite 中该构建的页面 | + +标签可用于路由和在变更列表中筛选： + +| 标签 | 说明 | +|---|---| +| `pipeline` | 流水线 slug | +| `repo` | 流水线的代码仓库地址 | +| `ref` | 构建的分支 | +| `sha` | 构建的提交 SHA（构建尚未解析出提交时不带此标签） | +| `actor` | 触发构建的用户名称 | +| `source` | 构建触发方式：`webhook`、`api`、`ui`、`trigger_job`、`schedule` | +| `build_id` | 构建 UUID | +| `build_number` | 流水线内的构建号 | +| `state` | 最新的 Buildkite 构建状态，等待 block step 时为 `blocked` | + +## 常见问题 +--- + + + + +- 确认 Webhook 勾选了 `build.*` 事件，只勾选 `job.*` 或 `agent.*` 事件不会产生变更 +- 确认构建所在的流水线和分支在 Webhook 的 **Pipelines** 和 **Branch filtering** 范围内 +- 在 Webhook 设置页底部点击 **Load recent requests**，查看最近 20 次推送和 Flashduty 的响应 + + + + + +不会。同一状态、同一时间的事件只记录一次。 + + + + + +- `unsupported build.state`：收到了 Flashduty 尚未支持的构建状态，请联系我们 +- `build.id is missing`：推送内容不完整，请确认推送来自 Buildkite 的 Webhook 通知服务 + + + diff --git a/zh/on-call/integration/change-integration/custom-event.mdx b/zh/on-call/integration/change-integration/custom-event.mdx index 5c9b08801..892016f2b 100644 --- a/zh/on-call/integration/change-integration/custom-event.mdx +++ b/zh/on-call/integration/change-integration/custom-event.mdx @@ -62,14 +62,14 @@ POST, Content-Type: application/json | :--- | :---: | :--- | :--- | | title | 是 | string | 变更标题，例如发布单标题、工单标题或部署任务名称。 | | change_key | 是 | string | 变更标识。相同 `change_key` 会被识别为同一个变更，后续事件会更新该变更的状态、标签和链接。 | -| change_status | 是 | string | 变更状态。枚举值（首字母大写）：`Planned` 计划中、`Ready` 待执行、`Processing` 执行中、`Canceled` 已取消、`Done` 已完成。 | +| change_status | 是 | string | 变更状态。枚举值（首字母大写）：`Planned` 计划中、`Ready` 待执行、`Processing` 执行中、`Canceled` 已取消、`Done` 已完成、`Failed` 失败。 | | event_time | 否 | integer | 事件发生时间，Unix 时间戳。支持秒级或毫秒级时间戳；未传时使用 Flashduty 接收事件的时间。 | | description | 否 | string | 变更描述，例如变更内容、影响范围、执行步骤或回滚方案。 | | link | 否 | string | 变更详情链接，例如发布单、工单或 CI/CD 任务地址。 | | labels | 否 | map | 变更标签集合，key 和 value 均为 string 类型。建议 key 遵循 Prometheus 标签命名规范；系统会将 key 中的空格、点号、斜杠等特殊字符替换为下划线。 | -当 `change_status` 为 `Done` 或 `Canceled` 时，Flashduty 会将该事件时间记录为变更结束时间；再次上报非结束状态时，结束时间会被清空。 +当 `change_status` 为 `Done`、`Canceled` 或 `Failed` 时，Flashduty 会将该事件时间记录为变更结束时间；再次上报非结束状态时，结束时间会被清空。 ### 请求响应 @@ -152,7 +152,7 @@ curl -X POST '{api_host}/event/push/change/standard?integration_key={integration - **变更的应用范围**：如 host、cluster 等 - **变更的归属信息**：如 team、owner 等 -- **变更的生命周期**：同一个变更在计划、执行、完成或取消时，使用相同 `change_key` 持续上报不同 `change_status`，便于在故障时间线上还原变更过程 +- **变更的生命周期**：同一个变更在计划、执行、完成、取消或失败时，使用相同 `change_key` 持续上报不同 `change_status`，便于在故障时间线上还原变更过程 ## 常见问题 diff --git a/zh/on-call/integration/change-integration/github.mdx b/zh/on-call/integration/change-integration/github.mdx new file mode 100644 index 000000000..080a48edb --- /dev/null +++ b/zh/on-call/integration/change-integration/github.mdx @@ -0,0 +1,132 @@ +--- +title: "GitHub 变更集成" +description: "通过 GitHub Webhook 将 Deployment 部署和 Release 发布同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "GitHub", "Deployment", "Release", "Webhook", "部署事件"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +通过 GitHub 仓库或组织的 Webhook，将部署（Deployment）和发布（Release）同步到 Flashduty On-call。每一次部署、每一个 Release 对应一条 Flashduty 变更；部署从创建、排队、执行到成功或失败的每个状态，都会更新同一条变更。 + +GitHub Actions 中声明了 `environment` 的任务会自动创建 Deployment，因此使用 Actions 发布的仓库无需改动流水线即可接入。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **GitHub**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `repo`、`environment`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 GitHub 中配置 +--- + + + + +- 仓库级：进入仓库 **Settings → Webhooks**，点击 **Add webhook** +- 组织级：进入组织 **Settings → Webhooks**，点击 **Add webhook**，组织下所有仓库的事件都会推送 + +需要仓库或组织的管理员权限。 + + + + + +1. **Payload URL**：粘贴 Flashduty 集成的完整推送地址 +2. **Content type**：选择 `application/json`（选择 `application/x-www-form-urlencoded` 同样可以接收） +3. **Secret**：留空即可，Flashduty 通过推送地址中的 `integration_key` 鉴权 + + + + + +1. 选择 **Let me select individual events** +2. 勾选 **Deployments**、**Deployment statuses** 和 **Releases**，取消默认勾选的 **Pushes** +3. 保持 **Active** 勾选，点击 **Add webhook** + +保存后 GitHub 会发送一次 `ping`，Flashduty 返回成功但不会生成变更。 + + + + +## 一条变更是什么 +--- + +| GitHub 对象 | 变更标识（change_key） | 说明 | +|---|---|---| +| Deployment | `deployment:` | 同一次部署的 `deployment` 事件和所有 `deployment_status` 事件更新同一条变更；同一仓库、同一环境的两次部署是两条变更 | +| Release | `release:` | 发布、取消发布、删除同一个 Release 更新同一条变更 | + +## 状态映射 +--- + +| GitHub 事件 | GitHub 状态 | Flashduty 变更状态 | +|---|---|---| +| deployment | created | Ready | +| deployment_status | waiting（等待环境审批） | Planned | +| deployment_status | pending、queued | Ready | +| deployment_status | in_progress | Processing | +| deployment_status | success | Done | +| deployment_status | failure、error | Failed | +| deployment_status | error，且来自在运行页面被取消的 GitHub Actions 任务（`workflow_run.conclusion` 为 `cancelled`） | Canceled | +| release | published | Done | +| release | unpublished、deleted | Canceled | + +Done、Failed 和 Canceled 是结束状态，Flashduty 会记录变更结束时间。 + +以下推送返回成功但不生成变更：`ping`、未列出的其他事件类型、Release 的 `created`、`edited`、`released`、`prereleased` 动作（发布时 GitHub 会同时发送 `published`，以 `published` 为准）、部署状态 `inactive`（旧部署被新部署取代，不改变旧部署已有的结果）。 + +## 变更内容 +--- + +| 字段 | Deployment | Release | +|---|---|---| +| 标题 | `<仓库>: deploy (<短 SHA>) to <环境>` | `<仓库>: release ` | +| 描述 | Deployment 的 description | Release 名称（与 tag 相同时为空） | +| 链接 | 部署日志（`log_url` 或 `target_url`），没有时为仓库的 Deployments 页面 | Release 页面 | + +标签可用于路由和在变更列表中筛选： + +| 标签 | Deployment | Release | +|---|---|---| +| `repo` | 仓库全名，例如 `octo-org/hello-world` | 同左 | +| `environment` | 部署环境 | — | +| `ref` | 部署的分支、tag 或 SHA | Release 的目标分支或提交 | +| `sha` | 部署的完整提交 SHA | — | +| `version` | — | Release tag | +| `task` | Deployment task，通常为 `deploy` | — | +| `actor` | 创建部署的用户 | 发布者 | +| `deployment_id` / `release_id` | GitHub 对象 ID | GitHub 对象 ID | +| `state` | 最新的 GitHub 部署状态 | — | +| `prerelease` | — | 预发布时为 `true` | + +## 常见问题 +--- + + + + +- 确认 Webhook 勾选了 **Deployments** 和 **Deployment statuses**。只勾选 **Pushes** 时不会产生变更 +- 在 GitHub Webhook 页面的 **Recent Deliveries** 查看推送记录和 Flashduty 的响应 +- 只有使用 GitHub Deployments 的发布才会产生部署事件，例如在 GitHub Actions 任务中声明 `environment`，或调用 Deployments API + + + + + +不会。同一状态、同一时间的事件只记录一次。 + + + + + +- `unsupported deployment_status.state`：收到了 Flashduty 尚未支持的部署状态，请联系我们 +- `deployment.id is missing` 或 `release.id is missing`：推送内容不完整，请确认推送来自 GitHub 原生 Webhook + + + diff --git a/zh/on-call/integration/change-integration/gitlab.mdx b/zh/on-call/integration/change-integration/gitlab.mdx new file mode 100644 index 000000000..35041c70c --- /dev/null +++ b/zh/on-call/integration/change-integration/gitlab.mdx @@ -0,0 +1,133 @@ +--- +title: "GitLab 变更集成" +description: "通过 GitLab Webhook 将部署（Deployment）同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "GitLab", "Deployment", "Webhook", "部署事件"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +通过 GitLab 项目或群组的 Webhook，将部署（Deployment）同步到 Flashduty On-call。每一次部署对应一条 Flashduty 变更；部署从等待审批、执行到成功、失败或取消的每个状态，都会更新同一条变更。 + +GitLab CI/CD 中声明了 `environment` 的任务会自动创建部署，因此使用 GitLab CI/CD 发布的项目无需改动流水线即可接入。GitLab.com 和自托管 GitLab 均适用。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **GitLab**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `project`、`environment`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 GitLab 中配置 +--- + + + + +- 项目级：进入项目 **Settings → Webhooks**，点击 **Add new webhook** +- 群组级（GitLab Premium 及以上）：进入群组 **Settings → Webhooks**，点击 **Add new webhook**，群组下所有项目的部署都会推送 + +项目级需要项目的 Maintainer 或 Owner 角色，群组级需要群组的 Owner 角色。 + + + + + +1. **URL**：粘贴 Flashduty 集成的完整推送地址 +2. **Signing token** 和 **Secret token**：无需配置，Flashduty 通过推送地址中的 `integration_key` 鉴权 + + + + + +1. 在 **Trigger** 中只勾选 **Deployment events**，取消默认勾选的 **Push events** +2. 保持 **Enable SSL verification** 勾选，点击 **Add webhook** + +GitLab 的 **Test** 功能不能发送部署事件；用 Test 发送的其他事件（例如 Push events）Flashduty 返回成功但不会生成变更。 + + + + +## 一条变更是什么 +--- + +| GitLab 对象 | 变更标识（change_key） | 说明 | +|---|---|---| +| Deployment | `deployment:` | 同一次部署的所有 Deployment 事件更新同一条变更；同一项目、同一环境的两次部署（包括重试部署任务）是两条变更 | + +`deployment_id` 在同一个 GitLab 实例内唯一。如果要接入多个 GitLab 实例（例如 GitLab.com 和自托管实例），请为每个实例创建一个集成。 + +## 状态映射 +--- + +| GitLab 部署状态 | Flashduty 变更状态 | +|---|---| +| blocked（等待审批或手动操作） | Planned | +| created | Ready | +| running | Processing | +| success | Done | +| failed | Failed | +| canceled、skipped | Canceled | + +Done、Failed 和 Canceled 是结束状态，Flashduty 会记录变更结束时间。GitLab 实际只在 blocked、running、success、failed、canceled 时推送事件。 + +以下推送返回成功但不生成变更：Deployment 以外的事件类型（Push、Pipeline 等）、受保护环境的审批事件 `approved` 和 `rejected`。审批事件描述的是审批记录而不是部署本身：批准后 GitLab 会在部署开始时推送 `running`，拒绝后会推送 `failed`，变更状态以这些部署事件为准。 + +## 变更内容 +--- + +| 字段 | 内容 | +|---|---| +| 标题 | `<项目>: deploy (<短 SHA>) to <环境>` | +| 描述 | 部署提交的标题（`commit_title`） | +| 链接 | 执行部署的 CI/CD 任务页面；通过 API 或 trigger 任务创建的部署没有任务，链接为项目的 Environments 页面 | + +标签可用于路由和在变更列表中筛选： + +| 标签 | 内容 | +|---|---| +| `project` | 项目完整路径，例如 `acme/order-service` | +| `project_id` | GitLab 项目 ID | +| `environment` | 部署环境 | +| `environment_tier` | 环境层级，例如 `production`、`staging` | +| `ref` | 部署的分支或 tag | +| `sha` | 部署提交的短 SHA | +| `actor` | 触发部署的用户名 | +| `deployment_id` | GitLab 部署 ID | +| `state` | 最新的 GitLab 部署状态 | + +## 常见问题 +--- + + + + +- 确认 Webhook 勾选了 **Deployment events**。只勾选 **Push events** 时不会产生变更 +- 在 GitLab Webhook 编辑页的 **Recent events** 查看推送记录和 Flashduty 的响应 +- 只有 GitLab 部署才会产生部署事件，例如在 CI/CD 任务中声明 `environment`，或调用 Deployments API + + + + + +不会。同一状态、同一时间的事件只记录一次。 + + + + + +是的。GitLab 拒绝部署后会推送 `failed`，Flashduty 按部署状态记录为 Failed，标签 `state` 为 `failed`。 + + + + + +- `unsupported deployment status`：收到了 Flashduty 尚未支持的部署状态，请联系我们 +- `deployment_id is missing`：推送内容不完整，请确认推送来自 GitLab 原生 Webhook + + + diff --git a/zh/on-call/integration/change-integration/hcp-terraform.mdx b/zh/on-call/integration/change-integration/hcp-terraform.mdx new file mode 100644 index 000000000..988c3c4b8 --- /dev/null +++ b/zh/on-call/integration/change-integration/hcp-terraform.mdx @@ -0,0 +1,134 @@ +--- +title: "HCP Terraform 变更集成" +description: "通过 HCP Terraform 工作区通知将 Terraform Run 同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "HCP Terraform", "Terraform Cloud", "Run", "Webhook", "基础设施变更"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +通过 HCP Terraform（原 Terraform Cloud）工作区的通知配置（Notification），将 Terraform Run 同步到 Flashduty On-call。每一次 Run 对应一条 Flashduty 变更；Run 从创建、Plan、等待确认、Apply 到完成、出错或取消的每个状态，都会更新同一条变更。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **HCP Terraform**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `organization`、`workspace`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 HCP Terraform 中配置 +--- + +通知按工作区配置，每个需要接入的工作区配置一次。需要该工作区的管理员权限。 + + + + +进入工作区，选择 **Settings → Notifications**，点击 **Create a notification**。 + + + + + +1. **Destination**：选择 **Webhook** +2. **Name**：填写便于识别的名称，例如 `Flashduty` +3. **Webhook URL**：粘贴 Flashduty 集成的完整推送地址 +4. **Token**：留空即可，Flashduty 通过推送地址中的 `integration_key` 鉴权 + + + + + +1. 在 **Run Events** 中选择 **All events** +2. 在 **Workspace Events**（漂移检测、自动销毁等）中选择 **No events**，Flashduty 会忽略这类通知 +3. 点击 **Create a notification** + +保存时 HCP Terraform 会发送一次验证请求，Flashduty 返回成功但不会生成变更。之后可以用 **Send a test** 再次验证。 + + + + +也可以使用 Terraform 的 `tfe` Provider 管理这项配置：`tfe_notification_configuration` 资源设置 `destination_type = "generic"`、`url` 为推送地址、`triggers` 为 `["run:created", "run:planning", "run:needs_attention", "run:applying", "run:completed", "run:errored"]`。 + +## 一条变更是什么 +--- + +| HCP Terraform 对象 | 变更标识（change_key） | 说明 | +|---|---|---| +| Run | `run_id`，例如 `run-FwnENkvDnrpyFC7M` | 同一个 Run 的所有通知更新同一条变更；同一工作区的两次 Run 是两条变更 | + +## 状态映射 +--- + +| 通知触发事件（trigger） | Run 状态（run_status） | Flashduty 变更状态 | +|---|---|---| +| run:created | pending | Ready | +| run:planning | planning | Processing | +| run:needs_attention | 例如 planned、policy_override（等待人工确认） | Planned | +| run:applying | applying | Processing | +| run:completed | applied、planned_and_finished、planned_and_saved | Done | +| run:completed | discarded（在确认步骤被放弃的 Run） | Canceled | +| run:errored | errored、policy_soft_failed | Failed | +| run:errored | canceled、force_canceled | Canceled | + +Done、Failed 和 Canceled 是结束状态，Flashduty 会记录变更结束时间。 + +`planned_and_finished` 表示只做了 Plan 的 Run（无变更或 Plan-only），同样记为 Done，可以通过 `run_status` 标签区分。 + +以下推送返回成功但不生成变更：保存配置或 **Send a test** 时的验证请求（trigger 为 `verification`）、健康评估通知（`assessment:drifted`、`assessment:check_failure`、`assessment:failed`）和工作区通知（`workspace:auto_destroy_reminder`、`workspace:auto_destroy_run_results`、`workspace:deleted`）。 + +## 变更内容 +--- + +| 字段 | 内容 | +|---|---| +| 标题 | `<组织>/<工作区>: terraform run ` | +| 描述 | Run 的 message（触发原因，例如 VCS 提交信息或手动填写的说明） | +| 链接 | HCP Terraform 中该 Run 的页面 | + +标签可用于路由和在变更列表中筛选： + +| 标签 | 说明 | +|---|---| +| `organization` | HCP Terraform 组织名称 | +| `workspace` | 工作区名称 | +| `workspace_id` | 工作区 ID，例如 `ws-XdeUVMWShTesDMME` | +| `run_id` | Run ID | +| `run_status` | 最新通知中的 Run 状态 | +| `actor` | 创建 Run 的用户 | + +## 常见问题 +--- + + + + +- 确认通知配置已启用，且勾选了 **Run Events**。只勾选 **Workspace Events** 时不会产生变更 +- 在通知配置页面查看最近的推送记录和 Flashduty 的响应 +- 通知按工作区配置，确认 Run 所在的工作区配置了该通知 + + + + + +不会。同一 Run、同一状态、同一时间的事件只记录一次。 + + + + + +不会。健康评估反映的是资源状态偏离配置，不是一次变更，Flashduty 收到后返回成功并忽略。 + + + + + +- `unsupported notifications[].trigger` 或 `unsupported notifications[].run_status`：收到了 Flashduty 尚未支持的触发事件或 Run 状态，请联系我们 +- `run_id is missing`：推送内容不完整，请确认推送来自 HCP Terraform 的 Webhook 通知 + + + diff --git a/zh/on-call/integration/change-integration/jenkins.mdx b/zh/on-call/integration/change-integration/jenkins.mdx new file mode 100644 index 000000000..742ed7ed0 --- /dev/null +++ b/zh/on-call/integration/change-integration/jenkins.mdx @@ -0,0 +1,145 @@ +--- +title: "Jenkins 变更集成" +description: "通过 Jenkins Notification 插件将部署任务的每次构建同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "Jenkins", "Notification 插件", "构建", "部署事件"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +通过 Jenkins 的 [Notification 插件](https://plugins.jenkins.io/notification/)，将任务（Job）的构建同步到 Flashduty On-call。每一次构建对应一条 Flashduty 变更；构建开始执行和结束时，都会更新同一条变更。 + +Jenkins 无法区分一次构建是否发布了变更，因此只需在**执行部署的任务**上配置通知，不要在单纯编译、测试的任务上配置。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **Jenkins**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `job`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 Jenkins 中配置 +--- + + + + +进入 **Manage Jenkins → System**，确认 **Jenkins Location** 中的 **Jenkins URL** 已填写为 Jenkins 的访问地址。未填写时推送内容不含构建链接，Flashduty 无法识别构建，会拒绝推送。 + + + + + +进入 **Manage Jenkins → Plugins → Available plugins**，搜索 **Notification** 并安装。需要 Jenkins 管理员权限。 + +该插件还依赖 **JUnit** 插件，但安装时不会自动带上。如果 **Manage Jenkins → Plugins → Installed plugins** 中没有 JUnit，请一并安装。缺少 JUnit 时插件不发送任何推送，构建日志中会出现 `NoClassDefFoundError: hudson/tasks/test/AbstractTestResultAction`。 + + + + + +1. 打开部署任务，点击 **Configure**，找到 **Job Notifications** 区域，点击 **Add Endpoint** +2. **Format**：选择 `JSON` +3. **Protocol**：选择 `HTTP` +4. **Event**：选择 `All Events`，Flashduty 才能同时看到构建开始和结束 +5. **URL Source**：选择 `Credentials Store`，把 Flashduty 集成的完整推送地址保存为 **Secret text** 凭据，并在 **URL** 中选择该凭据。选择 `Plain Text` 时，插件会在每次构建的日志中打印完整推送地址，包括 `integration_key` +6. **Branch** 保持默认的 `.*`，其余选项保持默认，点击 **Save** + +任务配置由 Jenkinsfile 管理（例如多分支流水线）时，在 Jenkinsfile 的 `properties` 中添加同样的配置，可通过流水线页面的 **Pipeline Syntax → Snippet Generator** 选择 `properties: Set job properties` 生成代码。 + + + + + +运行一次该任务，在 Flashduty 的变更列表中即可看到对应的变更。Notification 插件没有测试按钮。连接 Flashduty 失败时，构建日志中会出现 `Failed to notify endpoint`；插件不检查响应内容，Flashduty 拒绝的推送不会在 Jenkins 中显示。 + + + + +## 一条变更是什么 +--- + +每一次构建是一条变更，变更标识（change_key）为 `<构建完整地址>#<队列 ID>`，例如 `https://jenkins.example.com/job/deploy/18/#4711`。 + +- 同一次构建的所有阶段更新同一条变更 +- 同一任务的两次构建是两条变更 +- 任务被删除后重建、构建编号从 1 重新开始时，队列 ID 不同，不会与旧构建混为一条 +- 多个 Jenkins 实例推送到同一个集成时，构建地址不同，不会混淆 + +## 状态映射 +--- + +| 构建阶段（phase） | 构建结果（status） | Flashduty 变更状态 | +|---|---|---| +| STARTED | — | Processing | +| COMPLETED、FINALIZED | SUCCESS | Done | +| COMPLETED、FINALIZED | UNSTABLE | Done | +| COMPLETED、FINALIZED | FAILURE | Failed | +| COMPLETED、FINALIZED | ABORTED、NOT_BUILT | Canceled | + +Done、Failed 和 Canceled 是结束状态，Flashduty 会记录变更结束时间。COMPLETED 表示构建步骤执行完毕，FINALIZED 表示构建后操作（例如归档制品）也已完成，两者结果相同。 + +UNSTABLE 表示构建步骤全部执行完成，但测试或质量检查报告了问题，因此记为 Done；可以通过 `result` 标签筛选出这类变更。 + +插件只在构建开始时发送 QUEUED，构建在队列中等待期间不会推送。Flashduty 接收 QUEUED 但不记录，因此变更在构建开始时出现。 + +在流水线中调用 `notifyEndpoints` 步骤且 `phase` 为 `NONE` 时，推送返回成功但不生成变更。 + +## 变更内容 +--- + +| 字段 | 内容 | +|---|---| +| 标题 | `<任务完整名称> #<构建编号>`，例如 `platform/order-service/main #18` | +| 描述 | 通知地址中 **Notes** 选项的内容，未填写时为空 | +| 链接 | 构建页面 | + +标签可用于路由和在变更列表中筛选： + +| 标签 | 说明 | +|---|---| +| `job` | 任务完整名称，包含文件夹和多分支流水线的分支，例如 `platform/order-service/main` | +| `build_number` | 构建编号 | +| `branch` | 构建检出的 Git 分支 | +| `commit` | 构建检出的 Git 提交 | +| `phase` | 最新的构建阶段 | +| `result` | 构建结果，结束后才有 | + +只有在 **Source Code Management** 中配置了 Git 的自由风格任务才会推送 `branch` 和 `commit`；流水线（Pipeline）任务用 `git` 步骤检出时，推送中不含这两个字段。构建开始时的推送可能带着本次检出之前的值，请以构建结束时的值为准。请按 `job` 配置路由规则，否则同一次构建的前后事件可能进入不同的协作空间。 + +## 常见问题 +--- + + + + +- 确认 **Format** 选择的是 `JSON`，**Protocol** 选择的是 `HTTP` +- 确认 **Manage Jenkins → System** 中已填写 **Jenkins URL** +- 查看构建日志中是否有 `Notifying endpoint` 或 `Failed to notify endpoint` +- 构建日志中出现 `NoClassDefFoundError: hudson/tasks/test/AbstractTestResultAction` 时，说明缺少 JUnit 插件，安装后即可 +- **Branch** 不是 `.*` 时，只有带 `BRANCH_NAME` 环境变量且分支匹配的构建才会推送 + + + + + +插件在构建完成（COMPLETED）和构建后操作完成（FINALIZED）时各推送一次，两者结果相同，变更状态不变；两次推送在同一秒内到达时，第二次不会重复记录。只想接收一次时，可以把 **Event** 改为 `Job Finalized`，但这样就看不到执行中的阶段。 + + + + + +Flashduty 在以下情况拒绝推送： + +- `build.full_url is missing`：Jenkins URL 未配置 +- `build.queue_id is missing`：推送内容缺少队列 ID，请确认推送来自 Notification 插件 +- `build.status is missing`：结束阶段没有构建结果，通常是在流水线中构建结果确定之前调用了 `notifyEndpoints(phase: 'COMPLETED')` 或 `'FINALIZED'` +- `must use Format JSON`：通知地址的 **Format** 选择了 `XML` +- `unsupported build.phase` 或 `unsupported build.status`：收到了 Flashduty 尚未支持的阶段或结果，请联系我们 + + + diff --git a/zh/on-call/integration/change-integration/jfrog-artifactory.mdx b/zh/on-call/integration/change-integration/jfrog-artifactory.mdx new file mode 100644 index 000000000..1f53828d4 --- /dev/null +++ b/zh/on-call/integration/change-integration/jfrog-artifactory.mdx @@ -0,0 +1,137 @@ +--- +title: "JFrog Artifactory 变更集成" +description: "通过 JFrog Artifactory Webhook 将制品的上传、删除、移动和复制同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "JFrog", "Artifactory", "制品", "Webhook", "变更事件"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +通过 JFrog Artifactory 的预定义（Predefined）Webhook，将制品（Artifact）的上传、删除、移动和复制同步到 Flashduty On-call。每上传一个制品生成一条变更，之后删除同一个制品会把这条变更更新为已取消；每次移动或复制生成一条独立的变更。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **JFrog Artifactory**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `repo`、`path`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 JFrog Artifactory 中配置 +--- + + + + +1. 登录 JFrog Platform，选择 **All Projects** 或某个项目 +2. 进入 **Platform → Integrations → Webhooks**，点击 **New Webhook** +3. 保持 **Predefined** 开关选中（不要使用 Custom） + +需要管理员或项目管理员权限。 + + + + + +1. **Name**：例如 `flashduty-changes` +2. **URL**：粘贴 Flashduty 集成的完整推送地址 +3. **Secret token**：留空即可，Flashduty 通过推送地址中的 `integration_key` 鉴权 + + + + + +1. 在事件列表中选择 **Artifacts** 下的 **Artifact was deployed**、**Artifact was deleted**、**Artifact was moved** 和 **Artifact was copied** +2. 选择要监听的仓库：可选择全部本地仓库，也可以指定仓库或用包含/排除规则按路径筛选 +3. 点击 **Test** 检查连通性，再点击 **Create** + +**Test** 发送的是 JFrog 的示例数据（校验和为 `sample_checksum`），Flashduty 返回成功但不会生成变更。 + + + + +## 一条变更是什么 +--- + +JFrog 的推送内容里没有变更 ID，Flashduty 用制品所在位置加内容校验和标识一个制品： + +| Artifactory 事件 | 变更标识（change_key） | 说明 | +|---|---|---| +| deployed、deleted | `artifact:<仓库>/<路径>@` | 上传和之后删除同一份内容更新同一条变更；同一路径上传了新内容（校验和不同）是一条新变更 | +| moved | `moved:<仓库>/<路径>@ -> <目标>` | 一次移动一条变更 | +| copied | `copied:<仓库>/<路径>@ -> <目标>` | 一次复制一条变更 | + +对 moved 和 copied，`<仓库>/<路径>` 是制品原来的位置，`<目标>` 是推送中的 `target_repo_path`。 + +## 状态映射 +--- + +| Artifactory 事件（event_type） | Flashduty 变更状态 | +|---|---| +| deployed | Done | +| moved | Done | +| copied | Done | +| deleted | Canceled | + +Artifactory 的制品事件都在操作完成后推送，因此每条变更收到第一个事件时就已结束。 + +以下推送返回成功但不生成变更：制品以外的事件域（Artifact Properties、Docker、Builds、Release Bundles 等）、`cached`（远程仓库缓存了一个下载的制品，不是变更）、**Test** 按钮发送的示例数据。 + +## 变更内容 +--- + +| 字段 | deployed、deleted | moved、copied | +|---|---|---| +| 标题 | `<仓库>/<路径> ()` | `move <仓库>/<路径> () to <目标>`，复制时为 `copy ...` | +| 描述 | 空 | 空 | +| 链接 | JFrog Platform 中该制品的页面 | JFrog Platform 中目标位置的页面 | + +链接由推送中的 `jpd_origin` 生成；推送中没有该字段时变更没有链接。 + +标签可用于路由和在变更列表中筛选： + +| 标签 | 说明 | +|---|---| +| `repo` | 仓库名（Repository Key）；moved、copied 时为原仓库 | +| `path` | 制品在仓库中的路径 | +| `name` | 文件名 | +| `sha256` | 制品内容的 SHA-256 校验和 | +| `source_repo_path` | 仅 moved、copied：原位置 | +| `target_repo_path` | 仅 moved、copied：目标位置 | +| `actor` | 执行操作的用户或访问令牌主体 | +| `event_type` | Artifactory 事件：`deployed`、`deleted`、`moved` 或 `copied` | + +## 常见问题 +--- + + + + +- 确认 Webhook 是 **Predefined** 类型，并勾选了 **Artifacts** 下的事件 +- 确认上传的仓库在 Webhook 选择的仓库范围内 +- 在 Webhook 的 **Troubleshooting** 页查看推送记录和 Flashduty 的响应（JFrog Cloud 需要实例开启该功能） + + + + + +把内容完全相同的文件再次上传到同一路径，会在原来那条变更上追加一个事件，不会生成新变更。内容不同则生成新变更。 + + + + + +会追加一个事件，但不会生成新变更。JFrog 的推送内容不带事件时间，Flashduty 以收到推送的时间记录每个事件，因此无法识别重试。 + + + + + +- `unsupported event_type`：收到了 Flashduty 尚未支持的制品事件，请联系我们 +- `data.repo_key is missing`、`data.path is missing`、`data.sha256 is missing` 或 `data.target_repo_path is missing`：推送内容不完整，请确认使用的是 Predefined Webhook，而不是自定义了推送内容的 Custom Webhook + + + diff --git a/zh/on-call/integration/change-integration/launchdarkly.mdx b/zh/on-call/integration/change-integration/launchdarkly.mdx new file mode 100644 index 000000000..20cd7b9de --- /dev/null +++ b/zh/on-call/integration/change-integration/launchdarkly.mdx @@ -0,0 +1,144 @@ +--- +title: "LaunchDarkly 变更集成" +description: "通过 LaunchDarkly Webhook 将功能开关（Feature Flag）和用户分群（Segment）的变更同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "LaunchDarkly", "Feature Flag", "功能开关", "Webhook"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +通过 LaunchDarkly 组织级 Webhook，将功能开关（Flag）和用户分群（Segment）的变更同步到 Flashduty On-call。LaunchDarkly 的变更历史（Change history）中每一条 Flag 或 Segment 记录对应一条 Flashduty 变更，例如打开或关闭开关、修改定向规则、修改默认规则。 + +LaunchDarkly 推送的是已经生效的变更，因此每条变更都直接记录为 **Done**。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **LaunchDarkly**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `project`、`environment`、`flag`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 LaunchDarkly 中配置 +--- + + + + +1. 点击左侧栏的 **齿轮** 图标，进入 **Organization settings** +2. 点击 **Integrations**，找到 **Webhooks**，点击 **Add new** + +需要能管理集成的成员角色（例如 Admin）。 + + + + + +1. **Name**：填写便于识别的名称，例如 `Flashduty` +2. **URL**：粘贴 Flashduty 集成的完整推送地址 +3. **Sign this webhook**：无需勾选，Flashduty 通过推送地址中的 `integration_key` 鉴权 + + + + + +不添加策略（Policy）时，LaunchDarkly 只推送 **production** 环境的 Flag 变更。如需推送其他环境或 Segment 变更，添加如下策略： + +```json +[ + { + "effect": "allow", + "actions": ["*"], + "resources": ["proj/*:env/*:flag/*"] + }, + { + "effect": "allow", + "actions": ["*"], + "resources": ["proj/*:env/*:segment/*"] + } +] +``` + +将 `env/*` 替换为具体环境（例如 `env/production`）即可只推送该环境。勾选同意条款后点击 **Save settings**。 + + + + +LaunchDarkly 没有测试推送按钮。保存后在任一 Flag 上做一次变更，即可在 Flashduty 变更列表中看到记录。 + +## 一条变更是什么 +--- + +| LaunchDarkly 对象 | 变更标识（change_key） | 说明 | +|---|---|---| +| 变更历史记录（Change history entry） | 记录的 `_id` | 每次保存 Flag 或 Segment 产生一条记录，对应一条 Flashduty 变更；同一个开关先打开再关闭是两条变更 | + +## 状态映射 +--- + +| LaunchDarkly 记录 | Flashduty 变更状态 | +|---|---| +| Flag 或 Segment 的变更（开关、定向规则、默认规则、变体、创建、删除、归档、应用审批请求等） | Done | + +以下推送返回成功但不生成变更： + +- 其他资源类型的记录，例如项目、环境、成员、角色、Webhook、指标、实验 +- 只包含以下动作的记录，它们不改变 Flag 的求值结果： + - 审批请求的创建、修改、评审、删除（审批通过并应用后，LaunchDarkly 会推送应用这一步的记录） + - 定时变更的创建、修改和删除（到期执行时会推送执行的记录） + - 名称、描述、标签、维护者、临时标记、弃用标记、自定义属性、规则描述、代码引用、Flag 链接、关注者、Segment 导出 + +## 变更内容 +--- + +| 字段 | 内容 | +|---|---| +| 标题 | ` in <环境>: <动作描述>`，例如 `Checkout redesign in production: turned on the flag`；项目级动作（例如创建 Flag）不带环境 | +| 描述 | 变更备注（Comment）与 LaunchDarkly 的变更明细 | +| 链接 | LaunchDarkly 中该 Flag 或 Segment 的页面 | + +标签可用于路由和在变更列表中筛选： + +| 标签 | 说明 | +|---|---| +| `project` | 项目 key | +| `environment` | 环境 key，例如 `production`；项目级动作没有此标签 | +| `flag` | Flag key（Flag 变更） | +| `segment` | Segment key（Segment 变更） | +| `kind` | `flag` 或 `segment` | +| `action` | LaunchDarkly 动作，多个时以逗号分隔，例如 `updateOn`、`updateRules` | +| `actor` | 操作的成员姓名，通过 API 操作时为 Access token 或应用名称 | +| `audit_log_id` | 变更历史记录 ID | + +## 常见问题 +--- + + + + +未配置策略时 LaunchDarkly 只推送 production 环境的 Flag 变更。按上文 **选择推送范围** 添加策略。 + + + + + +不会。推送失败时 LaunchDarkly 会重试一次，重试内容与原推送相同，Flashduty 只记录一次。 + + + + + +LaunchDarkly 不保证按时间顺序推送。Flashduty 使用记录自身的时间（`date`）作为变更时间。 + + + + + +- `_id is missing`：推送内容不完整，请确认推送来自 LaunchDarkly 原生 Webhook +- `invalid date`：推送中的时间字段格式不正确 + + + diff --git a/zh/on-call/integration/change-integration/netlify.mdx b/zh/on-call/integration/change-integration/netlify.mdx new file mode 100644 index 000000000..5730e9ad2 --- /dev/null +++ b/zh/on-call/integration/change-integration/netlify.mdx @@ -0,0 +1,130 @@ +--- +title: "Netlify 变更集成" +description: "通过 Netlify 部署通知（HTTP POST request）将部署同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "Netlify", "部署通知", "Deploy notifications", "Webhook", "部署事件"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +通过 Netlify 项目的部署通知（Deploy notifications），将部署同步到 Flashduty On-call。每一次部署（Deploy）对应一条 Flashduty 变更；部署从等待审批、开始构建到成功或失败的每个通知，都会更新同一条变更。 + +生产部署、分支部署和 Deploy Preview 都会推送，可以用 `environment` 标签区分。Netlify 所有套餐都支持 HTTP POST request 类型的部署通知。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **Netlify**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `project`、`environment`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 Netlify 中配置 +--- + +Netlify 的每条通知只监听一个事件，需要为下表中的每个事件各添加一条通知，推送地址相同。 + + + + +进入 Netlify 项目，选择 **Project configuration → Notifications → Deploy notifications**，点击 **Add notification**，选择 **HTTP POST request**。 + + + + + +1. **Event to listen for**：选择一个事件，见下一步 +2. **URL to notify**：粘贴 Flashduty 集成的完整推送地址 +3. **JWS secret token**：留空即可，Flashduty 通过推送地址中的 `integration_key` 鉴权 +4. 点击 **Save** + + + + + +| 事件 | 是否需要 | +|---|---| +| Deploy started | 必需 | +| Deploy succeeded | 必需 | +| Deploy failed | 必需 | +| Deploy restored | 建议，记录回滚 | +| Deploy request pending、Deploy request accepted、Deploy request rejected | 项目开启了部署审批（不受信任的部署需要批准）时添加 | + +无需添加 Deploy locked、Deploy unlocked、Deploy deleted：它们不改变部署结果，Flashduty 返回成功但不生成变更。 + + + + +## 一条变更是什么 +--- + +| Netlify 对象 | 变更标识（change_key） | 说明 | +|---|---|---| +| Deploy | 部署 ID（`id`） | 同一次部署的所有通知更新同一条变更；同一项目、同一分支的两次部署是两条变更 | + +回滚（Deploy restored）重新发布的是一次已有的部署，因此会更新那次部署对应的变更，状态为 Done。回滚通知不带回滚时间，事件时间为 Flashduty 收到通知的时间。 + +## 状态映射 +--- + +| Netlify 事件 | Flashduty 变更状态 | +|---|---| +| Deploy request pending | Planned | +| Deploy request accepted | Ready | +| Deploy started | Processing | +| Deploy succeeded | Done | +| Deploy restored | Done | +| Deploy failed | Failed；构建被取消时为 Canceled | +| Deploy request rejected | Canceled | + +Done、Failed 和 Canceled 是结束状态，Flashduty 会记录变更结束时间。 + +## 变更内容 +--- + +| 字段 | 内容 | +|---|---| +| 标题 | `<项目名>: deploy <分支> (<短 SHA>) to <部署上下文>`，例如 `example-site: deploy main (f95f852) to production`；手动部署没有分支和提交时为 `<项目名>: deploy to <部署上下文>` | +| 描述 | 部署的 title，通常是提交信息或手动部署时填写的说明 | +| 链接 | Netlify 控制台中这次部署的页面；推送中没有 `admin_url` 时为这次部署的访问地址 | + +标签可用于路由和在变更列表中筛选： + +| 标签 | 说明 | +|---|---| +| `project` | Netlify 项目名 | +| `site_id` | Netlify 项目 ID | +| `environment` | 部署上下文：`production`、`deploy-preview`、`branch-deploy` 等 | +| `ref` | 部署的分支 | +| `sha` | 部署的完整提交 SHA | +| `deploy_id` | Netlify 部署 ID | +| `review_id` | Deploy Preview 对应的 Pull Request 编号 | +| `state` | 最新通知中的 Netlify 部署状态，例如 `building`、`ready`、`error` | +| `error_message` | 部署失败时 Netlify 给出的错误信息 | + +## 常见问题 +--- + + + + +Netlify 的每条通知只推送一个事件。请确认 Deploy started、Deploy succeeded、Deploy failed 三个事件都已各自添加了一条通知。 + + + + + +不会。Netlify 重发推送失败的通知时，Flashduty 按事件本身的时间记录，同一部署、同一状态、同一时间的通知只记录一次。Deploy restored 通知按收到时间记录，是例外：它的重发会再记录一次。 + + + + + +- `unsupported X-Netlify-Event`：收到了 Flashduty 尚未支持的 Netlify 事件，请联系我们 +- `deploy id is missing`：推送内容不完整，请确认推送来自 Netlify 部署通知 + + + diff --git a/zh/on-call/integration/change-integration/vercel.mdx b/zh/on-call/integration/change-integration/vercel.mdx new file mode 100644 index 000000000..d616b904a --- /dev/null +++ b/zh/on-call/integration/change-integration/vercel.mdx @@ -0,0 +1,139 @@ +--- +title: "Vercel 变更集成" +description: "通过 Vercel 团队 Webhook 将部署、上线和回滚同步到 Flashduty On-call，作为变更事件与告警、故障关联。" +keywords: ["变更集成", "Vercel", "Deployment", "部署事件", "Instant Rollback", "Webhook"] +--- + +**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +通过 Vercel 团队的 Webhook，将部署（Deployment）和生产环境回滚（Instant Rollback）同步到 Flashduty On-call。每一次部署对应一条 Flashduty 变更，部署从创建、构建到成功、上线、失败或取消的每个状态，都会更新同一条变更。 + +Vercel 的团队 Webhook 仅对 Pro 和 Enterprise 团队开放，Hobby 账号无法配置。 + +
+ +## 在 Flashduty On-call +--- + +1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件** +2. 选择 **Vercel**，填写集成名称 +3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `project`、`environment`）配置规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 Vercel 中配置 +--- + + + + +在 Vercel 控制台切换到目标团队，进入 **Settings → Webhooks**。需要团队的 Webhook 管理权限。 + + + + + +在 **Deployment Events** 中勾选： + +- **Deployment Created** +- **Deployment Succeeded** +- **Deployment Promoted** +- **Deployment Rollback** +- **Deployment Error** +- **Deployment Cancelled** + +Project、Feature Flag、Firewall 事件不是部署变更，勾选后 Flashduty 返回成功但不会生成变更。 + + + + + +1. 选择要推送的项目：**All Team Projects** 或指定项目 +2. **Endpoint URL**：粘贴 Flashduty 集成的完整推送地址 +3. 点击 **Create Webhook** + +Vercel 创建后会显示一个 Secret，Flashduty 不需要它，通过推送地址中的 `integration_key` 鉴权。 + + + + +## 一条变更是什么 +--- + +| Vercel 对象 | 变更标识（change_key） | 说明 | +|---|---|---| +| 部署 | `deployment:` | 同一次部署（`dpl_` 开头的 ID）的所有事件更新同一条变更；同一项目、同一提交的两次部署是两条变更 | +| 回滚 | `rollback::` | 一次 Instant Rollback 是一条独立变更，不修改被替换或被恢复的部署的记录 | + +## 状态映射 +--- + +| Vercel 事件 | Flashduty 变更状态 | +|---|---| +| `deployment.created` | Ready | +| `deployment.ready`（构建完成，Checks 执行中） | Processing | +| `deployment.succeeded` | Done | +| `deployment.promoted`（开始承接生产流量） | Done | +| `deployment.error` | Failed | +| `deployment.canceled` | Canceled | +| `deployment.rollback` | Done | + +Done、Failed 和 Canceled 是结束状态，Flashduty 会记录变更结束时间。 + +以下推送返回成功但不生成变更：非 `deployment.` 开头的事件类型（Project、Feature Flag、Firewall 等）；与 Checks、集成动作相关的部署事件；`deployment.cleanup`（部署在保留期结束后被永久删除，不改变该部署已有的结果）。 + +## 变更内容 +--- + +| 字段 | 部署 | 回滚 | +|---|---|---| +| 标题 | `<项目>: deploy <分支> (<短 SHA>) to <环境>`，没有 Git 信息时为部署域名 | `<项目 ID>: roll back production to <恢复的部署 ID>` | +| 描述 | Git 提交信息的第一行 | 空 | +| 链接 | Vercel 控制台中该部署的页面 | 空（Vercel 回滚事件不带链接） | + +标签可用于路由和在变更列表中筛选： + +| 标签 | 部署 | 回滚 | +|---|---|---| +| `project` | 项目名称 | — | +| `project_id` | 项目 ID（`prj_` 开头） | 同左 | +| `environment` | `production`、自定义环境（例如 `staging`），未指定目标时为 `preview` | `production` | +| `ref` | Git 分支 | — | +| `sha` | 完整提交 SHA | — | +| `actor` | 提交者的 Git 用户名 | — | +| `deployment_id` | 部署 ID | — | +| `from_deployment_id` / `to_deployment_id` | — | 被替换 / 被恢复的部署 ID | +| `state` | 最新的 Vercel 事件，例如 `succeeded` | `rollback` | + +`ref`、`sha`、`actor` 来自连接 GitHub、GitLab 或 Bitbucket 仓库时的部署元数据，通过 CLI 直接部署时没有这些标签。 + +## 常见问题 +--- + + + + +生产部署构建成功后 Vercel 先发送 `deployment.succeeded`，切换生产流量后再发送 `deployment.promoted`。两者都是 Done，更新的是同一条变更。 + + + + + +不会。Flashduty 使用 Vercel 事件自带的时间，同一事件、同一时间只记录一次。推送失败时 Vercel 会在 24 小时内重试。 + + + + + +从同一个部署回滚到同一个部署时变更标识相同，第二次回滚会更新第一次的变更（最后时间更新为第二次），不会新建变更。Vercel 的回滚事件只带两个部署 ID，没有独立的回滚 ID。 + + + + + +- `unsupported type`：收到了 Flashduty 尚未支持的部署事件（例如通过 API 订阅的 `deployment.blocked`），请只勾选上文列出的 6 个事件，或联系我们 +- `payload.deployment.id is missing`：推送内容不完整，请确认推送来自 Vercel 原生 Webhook + + +