v1.8.9

docs/make-docs

@@ -6,6 +6,15 @@
 # [Semantic versioning](https://semver.org/) is used to help the reader identify the significance of changes.
 # Changes are relevant to this script and the support docs.mk GNU Make interface.
 #
+# ## 8.0.1 (2024-07-01)
+#
+# ### Fixed
+#
+# - Update log suppression to catch new format of website /docs/ homepage REF_NOT_FOUND warnings.
+#
+#   These warnings are related to missing some pages during the build that are required for the /docs/ homepage.
+#   They were previously suppressed but the log format changed and without this change they reappear in the latest builds.
+#
 # ## 8.0.0 (2024-05-28)
 #
 # ### Changed
@@ -905,7 +914,7 @@ EOF
               -e '/Press Ctrl+C to stop/ d' \
               -e '/make/ d' \
               -e '/WARNING: The manual_mount source directory/ d' \
-              -e '/docs\/_index.md .* not found/ d'
+              -e '/"docs\/_index.md" not found/d'
     fi
     ;;
 esac

docs/sources/configure/_index.md

@@ -13,6 +13,22 @@ keywords:
 canonical: https://grafana.com/docs/oncall/latest/configure/
 aliases:
   - /docs/grafana-cloud/alerting-and-irm/oncall/configure/
+refs:
+  integrations:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/
+  jinja2-templating:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/
+  escalation-chains-and-routes:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/escalation-chains-and-routes/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/escalation-chains-and-routes/
 ---
 
 # Configure Grafana OnCall
@@ -28,26 +44,15 @@ Explore key settings and integrations that allow you to customize your incident
 
 Integrate with your tools and alert sources to begin routing alerts with Grafana OnCall.
 
-For detailed information on configuring integrations, refer to the [Integrations] documentation.
+For detailed information on configuring integrations, refer to the [Integrations](ref:integrations) documentation.
 
 ### Configure Escalation chains and routes
 
 Escalation chains allow you to customize alert routing to align with your team's processes and workflows.
 You have the flexibility to define how and when to escalate to different teams for different alerts.
 
-For information on configuration options, refer to [Escalation chains and routes].
+For information on configuration options, refer to [Escalation chains and routes](ref:escalation-chains-and-routes).
 
 ### Customize alert templates
 
-For detailed information on customizing alert templates, refer to the [Jinja2 templating] documentation.
-
-{{% docs/reference %}}
-[Integrations]: "/docs/oncall/ -> /docs/oncall/<ONCALL_VERSION>/integrations"
-[Integrations]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/integrations"
-
-[Escalation chains and routes]: "/docs/oncall/ -> /docs/oncall/<ONCALL_VERSION>/configure/escalation-chains-and-routes"
-[Escalation chains and routes]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/configure/escalation-chains-and-routes"
-
-[Jinja2 templating]: "/docs/oncall/ -> /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating"
-[Jinja2 templating]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating"
-{{% /docs/reference %}}
+For detailed information on customizing alert templates, refer to the [Jinja2 templating](ref:jinja2-templating) documentation.

docs/sources/configure/escalation-chains-and-routes/index.md

@@ -16,6 +16,22 @@ aliases:
   - /docs/grafana-cloud/alerting-and-irm/oncall/configure/escalation-chains-and-routes/
   - /docs/grafana-cloud/alerting-and-irm/oncall/escalation-chains-and-routes/
   - ../escalation-chains-and-routes/ # /docs/oncall/<ONCALL_VERSION>/escalation-chains-and-routes/
+refs:
+  notify-people:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/manage/notify/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/manage/notify/
+  routing-templates:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/#routing-template
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/#routing-template
+  outgoing-webhook:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/outgoing-webhooks/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/outgoing-webhooks/
 ---
 
 # Escalation Chains and Routes
@@ -135,14 +151,3 @@ For more information, refer to [Notify people].
 
 > **Important:** Linked Integrations and Routes are displayed in the right panel. Any change in the Escalation Chain will
 affect all linked Integrations and Routes.
-
-{{% docs/reference %}}
-[Notify people]: "/docs/oncall/ -> /docs/oncall/<ONCALL_VERSION>/manage/notify"
-[Notify people]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/manage/notify"
-
-[outgoing webhook]: "/docs/oncall/ -> /docs/oncall/<ONCALL_VERSION>/configure/outgoing-webhooks"
-[outgoing webhook]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/configure/outgoing-webhooks"
-
-[Routing Templates]: "/docs/oncall/ -> /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating#routing-template"
-[Routing Templates]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating#routing-template"
-{{% /docs/reference %}}

docs/sources/configure/integrations/_index.md

@@ -0,0 +1,97 @@
+---
+title: Grafana OnCall integrations
+menuTitle: Integrations
+description: An introduction to Grafana OnCall integrations.
+weight: 100
+keywords:
+  - OnCall
+  - Integrations
+  - Alerts
+  - Webhook integration
+  - Notifications
+canonical: https://grafana.com/docs/oncall/latest/configure/integrations/
+aliases:
+  - /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/
+  - /docs/grafana-cloud/alerting-and-irm/oncall/integrations/
+  - ../integrations/ # /docs/oncall/<ONCALL_VERSION>/configure/integrations/
+refs:
+  integration-references:
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/references/
+  group-id-templates:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/#grouping-id-template
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/#grouping-id-template
+  intergration-references:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/references/
+  appearance-templates:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/#appearance-templates
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/#appearance-templates
+  inbound-email:
+    - pattern: /docs/oncall
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/references/inbound-email/
+    - pattern: /docs/grafana-cloud
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/references/inbound-email/
+  alert-workflow:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/set-up/get-started/#learn-about-the-alert-workflow
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/set-up/get-started/#learn-about-the-alert-workflow
+  integration-labels:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/labels/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/labels/
+  routing-template:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/#routing-template
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/#routing-template
+  behavioral-templates:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/#behavioral-templates
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/#behavioral-templates
+  webhooks:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/outgoing-webhooks/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/outgoing-webhooks/
+  jinja2-templating:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/
+---
+
+# Grafana OnCall integrations
+
+An integration serves as the primary entry point for alerts that are processed by Grafana OnCall.
+Integrations receive alerts through a unique API URL, interpret them using a set of templates tailored for the specific monitoring system, and initiate
+escalations as necessary.
+
+For more information about how to configure an integration, refer to [Configure and manage integrations](https://grafana.com/docs/oncall/latest/configure/integrations/integration-management/).
+
+## Understand the integration alert flow
+
+- An alert is received on an integration’s **Unique URL** as an HTTP POST request with a JSON payload (or via [Inbound email](ref:inbound-email) for email integrations).
+
+- The incoming alert is routed according to the [Routing Template](ref:routing-template).
+
+- Alerts are grouped based on the [Grouping ID Template](ref:group-id-templates) and rendered using [Appearance Templates](ref:appearance-templates).
+
+- The alert group can be published to messaging platforms, based on the **Publish to Chatops** configuration.
+
+- The alert group is escalated to users according to the Escalation Chains selected for the route.
+
+- An alert group can be acknowledged or resolved with status updates based on its [Behavioral Templates](ref:behavioral-templates).
+
+- Users can perform actions listed in the [Alert Workflow](ref:alert-workflow) section.
+
+## Explore available integrations
+
+Refer to [Integration references](ref:intergration-references) for a list of available integrations and specific set up instructions.

docs/sources/configure/integrations/integration-management/index.md

@@ -0,0 +1,148 @@
+---
+title: Configure and manage integrations
+menuTitle: Manage integrations
+description: An overview of configuration options for Grafana OnCall integrations.
+weight: 100
+keywords:
+  - OnCall
+  - Integrations
+  - Alert routing
+  - Heartbeat monitoring
+  - Maintenance mode
+  - HTTP Endpoint
+canonical: https://grafana.com/docs/oncall/latest/configure/integrations/integration-management/
+aliases:
+  - /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/integration-management/
+  - ../integrations/ # /docs/oncall/<ONCALL_VERSION>/configure/integrations/integration-management/
+refs:
+  webhooks:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/outgoing-webhooks/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/outgoing-webhooks/
+  behavioral-templates:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/#behavioral-templates
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/#behavioral-templates
+  routing-template:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/#routing-template
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/#routing-template
+  integration-labels:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/labels/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/labels/
+  jinja2-templating:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/
+  configure-labels:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/labels/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/labels/
+  integration-references:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/references/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/references/
+  integration-templates:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/
+  appearance-templates:
+    - pattern: /docs/oncall/
+      destination: /docs/oncall/<ONCALL_VERSION>/configure/jinja2-templating/#appearance-templates
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/jinja2-templating/#appearance-templates
+---
+
+# Configure and manage integrations
+
+Integrations with Grafana OnCall help to ensure effective alert handling and efficiency notification routing.
+You can configure and manage each integrations settings to meet the needs of the teams that use it.
+This guide provides an overview on how to configure, customize and manage your integrations.
+
+You can manage or view your integrations current configuration at any time in the **Integration**s tab of Grafana OnCall.
+
+## Connect an integration
+
+To integrate Grafana OnCall with your chosen tools, follow these steps:
+
+1. Navigate to the **Integrations** tab in Grafana OnCall, and click **+ New integration**.
+1. Select your desired integration type from the [list of available integrations](ref:integration-references).
+If your desired integration is not listed, select **Webhook**.
+1. Provide a title and a description for your integration, assign it to a team, and click **Create Integration**.
+1. The Integration page will open, displaying details about the Integration.
+The provided HTTP Endpoint URL can be used to send events from an external monitoring system. Click the **How to connect** link for additional information.
+1. Configure your tool to send alerts to Grafana OnCall.
+1. Click **Send demo alert** to send a test alert to Grafana OnCall.
+
+## Customize the integration
+
+Explore ways to customize the behavior of your alerts from a specific integration:
+
+- Customize alerting grouping, auto-resolution, and auto-acknowledge templates to tailor the alert behavior for your team.
+- Modify [Appearance templates](ref:appearance-templates) to customize how alert groups are displayed in various parts of Grafana OnCall, such as the UI, phone and
+SMS, email, notifications, etc.
+- Add routes to your integration to direct alerts to different users and teams based on labels or other data.
+- Connect your escalation chains to routes to ensure the right people are notified at the right time.
+- Send demo alerts to an integration to validate that routes, templates, and escalations are functioning as expected. Consider using `Debug Maintenance mode`
+to avoid sending real notifications to your team.
+
+For detailed instructions, refer to:
+
+- [Integration templates](ref:integration-templates)
+- [Configure labels](ref:configure-labels)
+
+## Manage Maintenance Mode
+
+Maintenance Mode is useful when performing scheduled maintenance or updates on your infrastructure, which may trigger false alarms. There are two modes:
+
+- **Debug** - Test routing and escalations without real notifications. Alerts will be processed as usual, but no notifications will be sent to users.
+- **Maintenance** - Consolidate alerts into one during infrastructure work.
+
+To manage Maintenance Mode:
+
+1. Go to the Integration page and click **Three dots**.
+1. Select **Start Maintenance Mode**.
+1. Choose **Debug** or **Maintenance** mode.
+1. Set the **Duration** of Maintenance Mode.
+1. Click **Start**.
+1. To stop maintenance mode before its end, click **Three dots** and select **Stop Maintenance Mode**.
+
+## Heartbeat Monitoring
+
+OnCall heartbeat functions as a health check for alert group monitoring. You can configure your monitoring to regularly send alerts to the heartbeat endpoint.
+If OnCall doesn’t receive one of these alerts, it will create a new alert group and escalate it.
+
+To configure Heartbeat Monitoring:
+
+1. Go to the Integration page and click **Three dots**.
+1. Select **Heartbeat Settings**.
+1. Set **Heartbeat interval**.
+1. Copy the **Endpoint** into your monitoring system.
+
+If you need to disable heartbeat monitoring on an integration, use the **Reset** button to revert it to the inactive state.
+To restart heartbeat monitoring, send a request to the **Endpoint**.
+
+Refer to a specific integration’s documentation for more detailed instructions.
+
+## Manage and edit an integration
+
+Manage your existing integrations by navigating to the **Integrations** tab in Grafana OnCall and selecting the integration you want to manage.
+
+To edit the name of an integration:
+
+1. Navigate to the **Integrations** tab, select an integration from the list of enabled integrations.
+1. Click the **three dots** next to the integration name and select **Integration settings**.
+1. Provide a new name, description, and team, and click **Save**.
+
+## Explore available integrations
+
+Specific guidance and configuration options for each integration are available at [Integration references](ref:integration-references).