@marble-sh/backstage-plugin-grafana-common 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @marble-sh/backstage-plugin-grafana-common
 
+## 1.2.1
+
+### Patch Changes
+
+- c9c9f23: Documentation: a full entity-annotation reference (exact matching semantics,
+  how the annotations combine, visibility gating, and error behavior for
+  unknown instance names) in the frontend and common READMEs, and a new
+  "Creating the Grafana service account and token" walkthrough in the backend
+  README — UI steps, the Grafana Cloud `glsa_` vs `glc_` token distinction,
+  and a per-feature permission table (Viewer covers all read paths;
+  `datasources:query` caveat for panel graphs under Enterprise/Cloud data
+  source permissions; Editor / `fixed:dashboards:writer` for the scaffolder
+  module).
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -12,16 +12,28 @@ It provides:
 
 ## Entity annotations
 
-| Annotation                     | Helper                   | Meaning                                                            |
-| ------------------------------ | ------------------------ | ------------------------------------------------------------------ |
-| `grafana/instance`             | `getGrafanaInstanceName` | Which configured Grafana instance the entity belongs to.           |
-| `grafana/dashboard-selector`   | `getDashboardSelector`   | Comma-separated title substrings; any match selects the dashboard. |
-| `grafana/dashboard-uid`        | `getDashboardUid`        | A single dashboard uid (exact, case-sensitive match).              |
-| `grafana/tag-selector`         | `getTagSelector`         | A comma-separated list of dashboard tags.                          |
-| `grafana/alert-label-selector` | `getAlertLabelSelector`  | A `key=value,...` list of alert label matchers.                    |
-
-`isGrafanaAvailable(entity)` returns `true` when an entity carries any of the
-above annotations, and is used to gate the Grafana entity tabs and cards.
+| Annotation                     | Helper                   | Meaning                                                                                                          |
+| ------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `grafana/instance`             | `getGrafanaInstanceName` | The `grafana.instances[].name` the entity belongs to (exact match). Absent = query all configured instances.     |
+| `grafana/dashboard-selector`   | `getDashboardSelector`   | Comma-separated, case-insensitive title substrings; **any** match selects the dashboard.                         |
+| `grafana/dashboard-uid`        | `getDashboardUid`        | A single dashboard uid (exact, case-sensitive match). Written by catalog discovery on its dashboard `Resource`s. |
+| `grafana/tag-selector`         | `getTagSelector`         | Comma-separated dashboard tags; the dashboard must carry **all** of them.                                        |
+| `grafana/alert-label-selector` | `getAlertLabelSelector`  | `key=value,...` alert label matchers; the rule's labels must contain **all** pairs.                              |
+
+The dashboard annotations combine with AND — a dashboard must pass every one
+the entity carries. Empty annotation values are treated as absent. The full
+matching semantics are documented in the
+[frontend plugin README](../grafana/README.md#entity-annotations).
+
+Three gating helpers decide whether an entity has Grafana content to show:
+
+- `isDashboardsAvailable(entity)` — any of `grafana/instance`,
+  `grafana/dashboard-selector`, `grafana/dashboard-uid`, or
+  `grafana/tag-selector` is present.
+- `isAlertsAvailable(entity)` — `grafana/instance` or
+  `grafana/alert-label-selector` is present.
+- `isGrafanaAvailable(entity)` — either of the above; used to gate the Grafana
+  entity tabs and cards.
 
 ```ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marble-sh/backstage-plugin-grafana-common",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Common functionality for the Grafana Backstage plugins (types, annotations, and API contracts)",
   "main": "./dist/index.cjs.js",
   "types": "./dist/index.d.ts",