Incorporated Dominika's comments

pabel-rh · pabel-rh · commit 9f58ac86de03 · 2025-11-04T10:38:18.000+05:30
diff --git a/artifacts/attributes.adoc b/artifacts/attributes.adoc
@@ -170,4 +170,4 @@
 :using-dynamic-plugins-book-title: Using dynamic plugins
 
 :scorecard-plugin-book-link: {product-docs-link}/html-single/understanding_and_visualizing_red_hat_developer_hub_project_health_using_scorecards/index
-:scorecard-plugin-book-link: Understanding and visualizing {product} project health using Scorecards
+:scorecard-plugin-book-title: Understanding and visualizing {product} project health using Scorecards
diff --git a/assemblies/assembly-configuring-scorecards-in-rhdh.adoc b/assemblies/assembly-configuring-scorecards-in-rhdh.adoc
@@ -1,10 +1,10 @@
 :_mod-docs-content-type: ASSEMBLY
 
 [id="assembly-configuring-scorecards-in-rhdh"]
-= Configuring Scorecards to view metrics in your {product} instance
+= Installing and configuring Scorecards to view metrics in your {product} instance
 :context: assembly-configuring-scorecards-in-rhdh
 
-You can configure one of the following Scorecards in your {product-very-short} instance using metrics and scoring capabilities from various data sources for software components in the {product-very-short} catalog:
+You can install and configure the following Scorecards to display metrics and visual health status for software components in the {product-very-short} catalog:
 
 * GitHub Scorecards
 * Jira Scorecards
diff --git a/modules/observe/scorecards/con-set-global-standards-for-metric-thresholds.adoc b/modules/observe/scorecards/con-set-global-standards-for-metric-thresholds.adoc
@@ -3,7 +3,7 @@
 [id="con-set-global-standards-to-configure-thresholds"]
 = Set global standards for metric thresholds
 
-To override the default thresholds set by a metric provider, you must update your `{product-very-short} app-config.yaml` file under the configuration path of the specific metric.
+To override the default thresholds set by a metric provider, you must update your {product-very-short} `{my-app-config-file}` file under the configuration path of the specific metric.
 
 The custom configuration completely replaces the provider's defaults. If you omit a threshold category (such as `success`), that category is not assigned.
 
diff --git a/modules/observe/scorecards/proc-configuring-github-scorecards-in-rhdh-instance.adoc b/modules/observe/scorecards/proc-configuring-github-scorecards-in-rhdh-instance.adoc
@@ -13,7 +13,7 @@ You can view GitHub metrics for software components registered in the {product-v
 * You must have {configuring-book-link}[added a custom {product-very-short} application configuration] and have enough permissions to change it.
 
 .Procedure
-To configure GitHub Scorecards in your RHDH instance, complete the following steps:
+To install and configure GitHub Scorecards in your {product-very-short} instance, complete the following steps:
 
 . To allow {product-very-short} to access the GitHub API, you must create and configure a GitHub App and add the necessary integration to your configuration file by completing the following steps:
 .. Create a https://docs.github.com/en/apps/overview[GitHub App] with the required permissions (Read-only for Contents to allow reading repositories).
@@ -31,7 +31,7 @@ To configure GitHub Scorecards in your RHDH instance, complete the following ste
 *** `GITHUB_INTEGRATION_HOST_DOMAIN` (e.g., `github.com`)
 *** `GITHUB_INTEGRATION_PRIVATE_KEY_FILE`
 
-. Configure the GitHub integration in your `{product-very-short} {my-app-config-file}`, by adding the `integrations.github` section:
+. Configure the GitHub integration in your {product-very-short} `{my-app-config-file}`, by adding the `integrations.github` section:
 +
 [source,yaml]
 ----
@@ -46,17 +46,7 @@ integrations:
             ${GITHUB_INTEGRATION_PRIVATE_KEY_FILE}
 ----
 
-. Add the catalog ingest entity by adding the `catalog` section in your `{product-very-short} {my-app-config-file}`
-+
-[source,yaml]
-----
-catalog:
-  locations:
-    - type: url
-      target: https://github.com/owner/repo/catalog-info.yaml
-----
-
-. Configure the GitHub Scorecard plugin in your `{product-very-short} dynamic-plugins-config.yaml` by adding the following code to your `{product-very-short} dynamic-plugins-config.yaml`:
+. Install the GitHub Scorecard plugin in your {product-very-short} `dynamic-plugins-config.yaml` by adding the following code to your {product-very-short} `dynamic-plugins-config.yaml`:
 +
 [source,yaml]
 ----
@@ -95,9 +85,17 @@ where:
 You must add the team entity to the Catalog to ensure the provided permissions are applicable.
 ====
 
-. (Optional) Configure metric threshold values.
+. Statically ingest the catalog entity by adding the `catalog.locations` section in your {product-very-short} `{my-app-config-file}` that links to the `catalog-info.yaml` file:
++
+[source,yaml]
+----
+catalog:
+  locations:
+    - type: url
+      target: https://github.com/owner/repo/catalog-info.yaml
+----
 
-.. To customize the thresholds for the **GitHub Open Pull Requests** (`github.open_prs`) metric, add the following section to your `{my-app-config-file}` file:
+. (Optional) To customize the thresholds for the **GitHub Open Pull Requests** (`github.open_prs`) metric, add the following section to your {product-very-short} `{my-app-config-file}` file:
 +
 [source,yaml]
 ----
diff --git a/modules/observe/scorecards/proc-configuring-jira-scorecards-in-rhdh-instance.adoc b/modules/observe/scorecards/proc-configuring-jira-scorecards-in-rhdh-instance.adoc
@@ -17,6 +17,7 @@ The following Jira versions are supported:
 * You must have {configuring-book-link}[added a custom {product-very-short} application configuration] and have enough permissions to change it.
 
 .Procedure
+To install and configure Jira Scorecards in your {product-very-short} instance, complete the following steps:
 
 . Create a Jira configuration token using one of the following methods, depending on your Jira product:
 ** Jira Cloud: https://id.atlassian.com/manage-profile/security/api-tokens[Create a personal token]. You must then create a `Base64-encoded` string using the following plain text format: `your-atlassian-email:your-jira-api-token`.
@@ -27,43 +28,49 @@ echo -n 'your-atlassian-email:your-jira-api-token' | base64
 ----
 ** Jira datacenter: Create and use a Personal Access Token (PAT) in your Jira datacenter account. For more information, see the https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html[Atlassian] documentation.
 
-. Add your Jira token (${JIRA_TOKEN}) to {configuring-book-link}#provisioning-your-custom-configuration[your {product-very-short} secrets] using the following key/value pairs.
+. Add your Jira configuration (${JIRA_TOKEN}) to {configuring-book-link}#provisioning-your-custom-configuration[your {product-very-short} secrets] using the following key/value pairs:
+*** `JIRA_TOKEN`
+*** `JIRA_BASE_URL`
 
-. Configure the Jira Scorecard plugin in your `{product-very-short} dynamic-plugins-config.yaml` using either a direct setup or a proxy setup.
-.. Use a direct setup: Add the following code to your `{product-very-short} dynamic-plugins-config.yaml`:
+. Install the Jira Scorecard plugin in your {product-very-short} `dynamic-plugins-config.yaml` using either a direct setup or a proxy setup.
+.. Use a direct setup: Add the following code to your {product-very-short} `dynamic-plugins-config.yaml`:
 +
 [source,yaml]
 ----
 plugins:
   - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:pr_1499__0.1.0!red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira
     disabled: false
 ----
-... In your `{product-very-short} {my-app-config-file}` file, add the following direct setup settings:
+... In your {product-very-short} `{my-app-config-file}` file, add the following direct setup settings:
 +
 [source,yaml]
 ----
-    pluginConfig:
-      jira:
-        baseUrl: ${JIRA_BASE_URL}
-        token: ${JIRA_TOKEN}
-        product: _<jira_product>_
+jira:
+  baseUrl: ${JIRA_BASE_URL}
+  token: ${JIRA_TOKEN}
+  product: _<jira_product>_
 ----
 where:
 
-`baseUrl`:: Enter the Jira URL.
-`token`:: Enter the Jira token (Base64 string for Cloud, PAT for Data Center).
-`product`:: Enter the supported product: `cloud` or `datacenter`. (`cloud` is the preferred option)
+`baseUrl`:: The base URL of your Jira instance, configured under ${JIRA_BASE_URL} in your {product-very-short} secrets.
+`token`:: The Jira token (Base64 string for Cloud, PAT for Data Center), configured under ${JIRA_TOKEN} in your {product-very-short} secrets.
+`product`:: Enter the supported product: `cloud` or `datacenter`.
 
-.. Use a proxy setup: In your `{product-very-short} dynamic-plugins-config.yaml`, add the following code:
+.. Use a proxy setup: In your {product-very-short} `dynamic-plugins-config.yaml`, add the following code:
 +
 [source,yaml]
 ----
 plugins:
   - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:pr_1499__0.1.0!red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira
     disabled: false
 ----
++
+[NOTE]
+====
+You must use the proxy setup to ensure configuration compatibility if the Roadie Jira Frontend Plugin is also in use.
+====
 
-... In your `{product-very-short} {my-app-config-file}` file, add the following proxy settings:
+... In your {product-very-short} `{my-app-config-file}` file, add the following proxy settings:
 +
 [source,yaml]
 ----
@@ -82,8 +89,9 @@ jira:
 ----
 where:
 
-`Authorization`:: Set any of the following header value:
-* For *Cloud*: `Basic YourCreatedAboveToken`
+`target`:: The base URL of your Jira instance, configured under ${JIRA_BASE_URL} in your {product-very-short} secrets.
+`Authorization`:: The Jira token, configured under ${JIRA_TOKEN} in your {product-very-short} secrets. Set the token value as one of the following values:
+* For *Cloud*: `Basic YourCreatedCloudToken`
 * For *Data Center*: `Bearer YourJiraToken`
 
 . Annotate the component entity in the `catalog-info.yaml`.
@@ -116,8 +124,18 @@ where:
 `jira/team`:: Optional: Enter the Jira team ID (not the team title).
 `jira/custom-filter`:: Optional: Enter a custom Jira Query Language (JQL) filter.
 
+. Statically ingest the catalog entity by adding the `catalog.locations` section in your {product-very-short} `{my-app-config-file}` that links to the `catalog-info.yaml` file
++
+[source,yaml]
+----
+catalog:
+  locations:
+    - type: url
+      target: https://github.com/owner/repo/catalog-info.yaml
+----
+
 . (Optional) Configure Jira Open Issues metric thresholds.
-.. To customize the thresholds for the *Jira Open Issues* (`jira.open_issues`) metric, add the following to your `{product-very-short} app-config.yaml` file:
+.. To customize the thresholds for the *Jira Open Issues* (`jira.open_issues`) metric, add the following to your {product-very-short} `{my-app-config-file}` file:
 +
 [source,yaml]
 ----
@@ -139,7 +157,7 @@ where:
 `scorecard:plugins:jira:open_issues:thresholds`:: Lists the default threshold values for the Jira open Issues metric.
 
 . (Optional) Define global or custom mandatory filters.
-.. You can apply global mandatory filters or define custom filters that entities can override. Add the following to your `{product-very-short} app-config.yaml`:
+.. You can apply global mandatory filters or define custom filters that entities can override. Add the following to your {product-very-short} `{my-app-config-file}`:
 +
 [source,yaml]
 ----
diff --git a/modules/observe/scorecards/proc-installing-scorecard-plugin-in-rhdh-instance.adoc b/modules/observe/scorecards/proc-installing-scorecard-plugin-in-rhdh-instance.adoc
@@ -37,8 +37,4 @@ plugins:
                       - isKind: component
   - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend:bs_1.42.5__1.0.0!red-hat-developer-hub-backstage-plugin-scorecard-backend
     disabled: false
-----
-where:
-
-`baseUrl`:: Enter the Jira URL.
-`token`:: Enter the Jira token.
+----
diff --git a/modules/observe/scorecards/ref-override-rules-to-configure-entity-specific-thresholds.adoc b/modules/observe/scorecards/ref-override-rules-to-configure-entity-specific-thresholds.adoc
@@ -3,7 +3,7 @@
 [id="ref-override-rules-to-configure-entity-specific-thresholds_{context}"]
 = Threshold rules to metrics for your Scorecard plugin
 
-You can override individual threshold rules for a specific component by using annotations in its `catalog-info.yaml` file. These annotations are merged with the existing global rules defined in your `{product-very-short} app-config.yaml` file.
+You can override individual threshold rules for a specific component by using annotations in its `catalog-info.yaml` file. These annotations are merged with the existing global rules defined in your {product-very-short} `{my-app-config-file}` file.
 
 .Annotation Format Reference
 
@@ -32,7 +32,7 @@ The annotation key follows a strict structure:
 
 .Example: Entity Annotation Override
 
-The following example describes the entity overriding only the `warning` and `error` rules for the `jira.open_issues` metric. The `success` rule falls back to the value defined in the global `{product-very-short} app-config.yaml` file.
+The following example describes the entity overriding only the `warning` and `error` rules for the `jira.open_issues` metric. The `success` rule falls back to the value defined in the global {product-very-short} `{my-app-config-file}` file.
 
 [source,yaml]
 ----
