feat: Add Grafana integration

docs/components/Grafana.mdx

@@ -0,0 +1,154 @@
+---
+title: "Grafana"
+---
+
+Connect Grafana alerts and data queries to SuperPlane workflows
+
+## Triggers
+
+<CardGrid>
+  <LinkCard title="On Alert Firing" href="#on-alert-firing" description="Trigger when a Grafana alert rule is firing" />
+</CardGrid>
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components";
+
+## Actions
+
+<CardGrid>
+  <LinkCard title="Query Data Source" href="#query-data-source" description="Execute a query against a Grafana data source and return the result" />
+</CardGrid>
+
+## Instructions
+
+To connect Grafana:
+1. In Grafana, go to Administration > Users and access > Service accounts.
+2. Create a Service Account and assign a role (Viewer/Editor/Admin as needed).
+3. Open the Service Account and create a token. Copy it immediately.
+4. (Legacy Grafana) If Service Accounts are unavailable, use an API key.
+5. Set the Base URL to your Grafana instance (e.g. https://grafana.example.com).
+6. Paste the token into SuperPlane and save.
+
+For the alert trigger:
+1. SuperPlane will attempt to automatically create/update a Grafana Webhook contact point.
+2. Route your alert rule to the contact point created by SuperPlane.
+3. If auto-provisioning is not available (permissions/API limitations), create a Webhook contact point manually using the webhook URL from SuperPlane.
+
+<a id="on-alert-firing"></a>
+
+## On Alert Firing
+
+The On Alert Firing trigger starts a workflow when Grafana Unified Alerting sends a firing alert webhook.
+
+### Setup
+
+1. SuperPlane attempts to automatically create/update a Grafana Webhook contact point for this trigger.
+2. If you set a Shared Secret in this trigger, SuperPlane includes it as an Authorization bearer token in the provisioned contact point.
+3. Route your alert rule to the contact point created by SuperPlane.
+4. If auto-provisioning is unavailable (permissions/API limitations), create the contact point manually using the webhook URL generated by SuperPlane.
+5. For manual setup with Shared Secret, add an HTTP header to the contact point:
+   - Authorization: Bearer <shared-secret>
+
+### Event Data
+
+The trigger emits the full Grafana webhook payload, including:
+- status (firing/resolved)
+- alerts array with labels and annotations
+- groupLabels, commonLabels, commonAnnotations
+- externalURL and other alerting metadata
+
+### Example Data
+
+```json
+{
+  "data": {
+    "alerts": [
+      {
+        "annotations": {
+          "summary": "Error rate above threshold"
+        },
+        "labels": {
+          "alertname": "HighErrorRate",
+          "service": "api"
+        },
+        "status": "firing"
+      }
+    ],
+    "commonLabels": {
+      "alertname": "HighErrorRate"
+    },
+    "externalURL": "http://grafana.local",
+    "ruleUid": "alert_rule_uid",
+    "status": "firing",
+    "title": "High error rate"
+  },
+  "timestamp": "2026-02-12T16:18:03.362582388Z",
+  "type": "grafana.alert.firing"
+}
+```
+
+<a id="query-data-source"></a>
+
+## Query Data Source
+
+The Query Data Source component executes a query against a Grafana data source using the Grafana Query API.
+
+### Use Cases
+
+- **Metrics investigation**: Run PromQL or other datasource queries from workflows
+- **Alert validation**: Validate alert conditions before escalation
+- **Incident context**: Pull current metrics into incident workflows
+
+### Configuration
+
+- **Data Source UID**: The Grafana datasource UID to query
+- **Query**: The datasource query (PromQL, InfluxQL, etc.)
+- **Time From / Time To**: Optional time range (relative like "now-5m" or absolute)
+- **Format**: Optional query format (depends on the datasource)
+
+### Output
+
+Returns the Grafana query API response JSON.
+
+### Example Output
+
+```json
+{
+  "data": {
+    "results": {
+      "A": {
+        "frames": [
+          {
+            "data": {
+              "values": [
+                [
+                  "2026-02-07T08:00:00Z",
+                  "2026-02-07T08:01:00Z"
+                ],
+                [
+                  1,
+                  1
+                ]
+              ]
+            },
+            "schema": {
+              "fields": [
+                {
+                  "name": "time",
+                  "type": "time"
+                },
+                {
+                  "name": "value",
+                  "type": "number"
+                }
+              ]
+            }
+          }
+        ]
+      }
+    }
+  },
+  "timestamp": "2026-02-12T16:18:03.362582388Z",
+  "type": "grafana.query.result"
+}
+```
+