diff --git a/assemblies/assembly-scorecards-rhdh.adoc b/assemblies/assembly-scorecards-rhdh.adoc index 49478886c6..7161655b33 100644 --- a/assemblies/assembly-scorecards-rhdh.adoc +++ b/assemblies/assembly-scorecards-rhdh.adoc @@ -1,7 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="assembly-rhdh-observability"] -= Understanding and visualizing {product} project health using Scorecards += Evaluate project health using Scorecards :context: assembly-scorecards-rhdh include::modules/observe/scorecards/con-understand-scorecard-plugins.adoc[leveloffset=+1] diff --git a/modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc b/modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc index 6d46a8164e..d4b5930f00 100644 --- a/modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc +++ b/modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc @@ -1,9 +1,9 @@ :_mod-docs-content-type: CONCEPT [id="con-best-practices-for-threshold-rules"] -= Verify logical flow in threshold rules += Verify logical flow in Scorecard threshold rules -Threshold rule evaluation depends on the order of the rules. Because the system stops evaluation after a value matches the first applicable rule, you must sequence rules logically to ensure correct category assignments. +Since Scorecard evaluates rules in order and stops at the first match, proper sequencing is essential for accurate health classification. == Evaluation order for rules diff --git a/modules/observe/scorecards/con-how-thresholds-work.adoc b/modules/observe/scorecards/con-how-thresholds-work.adoc index cc7d3dfea1..467c3e317a 100644 --- a/modules/observe/scorecards/con-how-thresholds-work.adoc +++ b/modules/observe/scorecards/con-how-thresholds-work.adoc @@ -1,7 +1,7 @@ :_mod-docs-content-type: CONCEPT [id="con-how-thresholds-work_{context}"] -= How Thresholds work += Scorecard metric threshold categorization rules A threshold defines conditions or expressions to assign metric values to specific visual categories. diff --git a/modules/observe/scorecards/con-manage-metric-thresholds-in-scorecard-plugin.adoc b/modules/observe/scorecards/con-manage-metric-thresholds-in-scorecard-plugin.adoc index 492ba90e34..060d04c16c 100644 --- a/modules/observe/scorecards/con-manage-metric-thresholds-in-scorecard-plugin.adoc +++ b/modules/observe/scorecards/con-manage-metric-thresholds-in-scorecard-plugin.adoc @@ -1,6 +1,6 @@ :_mod-docs-content-type: CONCEPT [id="con-manage-metric-thresholds-in-scorecard-plugin_{context}"] -= Managing metric thresholds in your Scorecard plugin += Scorecard metric thresholds -The Scorecard plugin uses thresholds to translate raw metric values into visual health indicators (`Success`, `Warning`, or `Error`). Configuring these thresholds is the primary way platform engineers and developers define what constitutes a healthy component. \ No newline at end of file +You can configure thresholds to turn raw metrics into meaningful health indicators, such as `Success`, `Warning`, or `Error`, helping you identify healthy components and detect issues early. \ No newline at end of file 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 index 0500a92aac..763e0db5bd 100644 --- a/modules/observe/scorecards/con-set-global-standards-for-metric-thresholds.adoc +++ b/modules/observe/scorecards/con-set-global-standards-for-metric-thresholds.adoc @@ -1,13 +1,13 @@ :_mod-docs-content-type: CONCEPT [id="con-set-global-standards-to-configure-thresholds"] -= Set global standards for metric thresholds += Standardize Scorecard metric thresholds across components -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. +You can define global thresholds in your `{product-very-short} {my-app-config-file}` file to standardize health indicators across all components. Global configurations replace the default thresholds provided by a metric source. -The custom configuration completely replaces the provider's defaults. If you omit a threshold category (such as `success`), that category is not assigned. +If you omit a threshold category, such as `success`, the Scorecard plugin does not assign that category to the metric. -The following configuration defines a `success` threshold as 10 or fewer issues, which applies to all components using the `jira.open_issues` metric unless explicitly overridden by an entity annotation. +The following example defines thresholds for the `jira.open_issues` metric. These settings apply to all components using this metric unless an entity annotation overrides them. [source,yaml] ---- @@ -18,9 +18,9 @@ scorecard: thresholds: rules: - key: success - expression: '<10' # fewer than 10 open issues is Success + expression: '<10' # fewer than 10 open issues - key: warning - expression: '10-50' # Between 10 and 50 is a Warning + expression: '10-50' # Between 10 and 50 open issues - key: error - expression: '>50' # More than 50 open issues is an Error + expression: '>50' # More than 50 open issues ---- \ No newline at end of file diff --git a/modules/observe/scorecards/con-understand-scorecard-plugins.adoc b/modules/observe/scorecards/con-understand-scorecard-plugins.adoc index fd8711c01e..13059c53f0 100644 --- a/modules/observe/scorecards/con-understand-scorecard-plugins.adoc +++ b/modules/observe/scorecards/con-understand-scorecard-plugins.adoc @@ -1,20 +1,17 @@ :_mod-docs-content-type: CONCEPT [id="con-understand-scorecard-plugin_{context}"] -= Understand Scorecard plugins in {product} += Component health and compliance monitoring using Scorecards include::{docdir}/artifacts/snip-developer-preview-scorecard.adoc[] -The Scorecard plugin offers comprehensive, customizable insights into the health, security posture, and compliance of your components, services, and APIs. It centralizes Key Performance Indicators (KPIs) within {product} ({product-very-short}), so you do not have to consult multiple external systems. +You can use the Scorecard plugin in {product} {product-very-short} to quickly assess the health, security, and compliance of your services in one place. By bringing key performance indicators together in a single view, you can evaluate component quality and identify issues without jumping between multiple tools or systems. -The Scorecard plugin offers the following benefits: +Use the Scorecard plugin to achieve the following goals: -* Accelerated decision-making: Scorecards provide an at-a-glance view of component readiness. Engineering and platform teams can use this data to quickly identify risks and prioritize remediation efforts, enabling faster, more effective decisions. - -* Improved security and compliance: The plugin automatically surfaces compliance gaps against predefined standards (such as required security checks). This capability enforces best practices and helps maintain a stronger overall security posture. - -* Reduced context switching: Centralizing all KPIs in {product-very-short} reduces the time developers spend hunting for data across different tools. Developers can then focus more on building and shipping features. - -* Standardization and consistency: Scorecards help drive organizational consistency by clearly defining and measuring what "good" looks like for every service. This process fosters a more uniform and reliable ecosystem. +* Identify and prioritize risks: Use unified health data to make faster remediation decisions. +* Maintain security standards: Automatically surface compliance gaps to enforce best practices. +* Streamline workflows: Access all metrics in {product-very-short} to reduce development overhead. +* Standardize service quality: Define and measure consistent health criteria across the organization. image::rhdh/scorecard-sample.png[] diff --git a/modules/observe/scorecards/proc-authenticating-and-managing-scorecard-plugins.adoc b/modules/observe/scorecards/proc-authenticating-and-managing-scorecard-plugins.adoc index afaa2a623c..7ad4a6193e 100644 --- a/modules/observe/scorecards/proc-authenticating-and-managing-scorecard-plugins.adoc +++ b/modules/observe/scorecards/proc-authenticating-and-managing-scorecard-plugins.adoc @@ -1,17 +1,17 @@ :_mod-docs-content-type: PROCEDURE [id="proc-authenticating-and-managing-scorecard-plugins_{context}"] -= Authenticating and managing Scorecard plugins to control who sees the metrics += Installing and configuring Scorecard to view metrics -As an administrator, you can secure the connection to your metric providers by managing user access to the Scorecards using the Role-Based Access Control (RBAC) permissions. For users to view the Scorecard metrics, you must grant users with read access to the Scorecard metrics. You can configure these permissions either by modifying your RBAC CSV file directly or by using the RBAC Web UI. +To enable users to view Scorecard metrics, you need to grant read access using Role-Based Access Control (RBAC). You can configure these permissions either through the RBAC CSV file or the RBAC UI, depending on how you manage access in your environment. .Prerequisite * You have {authorization-book-link}#enabling-and-giving-access-to-rbac[enabled RBAC, have a policy administrator role in {product-very-short}, and have added `scorecard` to plugins with permission]. .Procedure -Use any of the following methods to set the required RBAC permissions: +Grant the required permissions by using one of the following methods: -* To use the CSV file, in your CSV file, you can directly add the following code: +* To use the RBAC CSV file, add the following policy to your CSV file to allow users to view metrics: + [source,yaml] ---- @@ -23,11 +23,11 @@ p, role:default/scorecard-viewer, catalog.entity.read, read, allow See {authorization-book-link}#ref-rbac-permission-policies_title-authorization[Permission policies reference]. * To use the RBAC Web UI, complete the following steps: -.. In your {product} menu, go to *Administration > RBAC*. -.. Select or create the *Role* to which you want to grant access to the Scorecards. -.. To enable read access for the Scorecard plugin, in *Add permission policies*, select *Scorecard* from the plugins dropdown. -.. Expand *Scorecard*, select *policy* with the following details, and click *Next*: +.. In the {product} menu, navigate to *Administration > RBAC*. +.. Select or create the *Role* that requires Scorecard access. +.. In the *Add permission policies* section, select *Scorecard* from the plugins dropdown. +.. Expand the *Scorecard* entry, select *policy* with the following details, and click *Next*: *** *Name*: `scorecard.metric.read` *** *Permission*: `read` + -image::rhdh/scorecard-create-role.png[] \ No newline at end of file +image::rhdh/scorecard-create-role.png[The RBAC UI showing the scorecard.metric.read permission selected for a role.] \ No newline at end of file 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 index 219a682ea8..62b3b68b52 100644 --- a/modules/observe/scorecards/proc-configuring-github-scorecards-in-rhdh-instance.adoc +++ b/modules/observe/scorecards/proc-configuring-github-scorecards-in-rhdh-instance.adoc @@ -1,15 +1,15 @@ :_mod-docs-content-type: PROCEDURE [id="proc-configuring-github-scorecards-in-rhdh-instance_{context}"] -= Configuring GitHub Scorecards to view GitHub metrics in your {product} instance += Integrating GitHub health metrics using Scorecards -To achieve enhanced visibility and control over your software components, you must configure the GitHub Scorecards plugin to integrate GitHub metrics directly into your {product-very-short} catalog. This allows engineering teams to centralize development data, quickly identify risks, and accelerate decision-making related to component health and security. +You can configure the GitHub Scorecard plugin to display repository metrics in your {product-very-short} catalog. This integration allows you to monitor component health and security risks directly from {product}. -To enable the GitHub metrics integration, you must create and configure an integration to grant {product-very-short} access to the GitHub API using either a https://docs.github.com/en/apps/overview[GitHub App] or a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token]. +You can grant {product-very-short} access to the GitHub API by using a https://docs.github.com/en/apps/overview[GitHub App] or a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token]. [IMPORTANT] ==== -For long-lived integrations or when accessing resources on behalf of an organization, you must use a GitHub App. +For long-lived integrations or organizational access, you must use a GitHub App. ==== .Prerequisites @@ -22,9 +22,9 @@ For long-lived integrations or when accessing resources on behalf of an organiza .Procedure To install and configure GitHub Scorecards in your {product-very-short} instance, complete the following steps: -. Establish GitHub API access: Choose one of the following methods to grant {product-very-short} access to the GitHub API, and then complete the required configuration procedure: +. Grant GitHub API access: Create one of the following authentication methods: ** Configure using a GitHub App. -... Create a https://docs.github.com/en/apps/overview[GitHub App] with the required permissions (Read-only for Contents to allow reading repositories) to grant access to the GitHub API, and then complete the required configuration procedure: +... Create a https://docs.github.com/en/apps/overview[GitHub App] with the required permissions (Read-only for Contents to allow reading repositories). + [NOTE] ==== @@ -45,7 +45,7 @@ You must install the GitHub App on the organization (or user account) that owns * `GITHUB_INTEGRATION_ORGANIZATION`:: Your GitHub organization name, such as `__`. * `GITHUB_INTEGRATION_PRIVATE_KEY_FILE`:: The saved *Private key* content. -... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the `integrations.github` section: +... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the authentication details to the `integrations.github` section: + [source,yaml] ---- @@ -61,7 +61,7 @@ integrations: ---- ** Configure using a GitHub token. -... Create a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token] to grant {product-very-short} access to the GitHub API. Choose one of the following token types with these minimum permissions: +... Create a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token] with the following permissions: **** https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic[Classic Personal Access Token] (PAT): Select the `repo` scope for read/write access to private repositories. **** https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token[Fine-Grained Personal Access Token] (PAT): ***** Choose the specific repositories that {product-very-short} must access. @@ -73,7 +73,7 @@ where: `GITHUB_TOKEN`:: The generated GitHub token. -... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the streamlined `integrations.github` section: +... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the authentication details to the `integrations.github` section: + [source,yaml] ---- @@ -83,7 +83,7 @@ integrations: token: ${GITHUB_TOKEN} ---- -. Install the GitHub Scorecard plugin by adding the following code to your {product-very-short} `dynamic-plugins-config.yaml` file: +. Enable the GitHub Scorecard plugin: Add the GitHub Scorecard module to your {product-very-short} `dynamic-plugins-config.yaml` file: + [source,yaml] ---- @@ -92,7 +92,7 @@ plugins: disabled: false ---- -. Link a component to the GitHub data source by editing the `catalog-info.yaml` file for your {product-very-short} entity and adding the required annotations as shown in the following code: +. Annotate catalog entities: Link a component to the GitHub data source by editing the `catalog-info.yaml` file for your {product-very-short} entity and adding the required annotations as shown in the following code: + [source,yaml] ---- @@ -122,17 +122,17 @@ where: You must add the team entity to the Catalog to ensure the provided permissions are applicable. ==== -. **Statically ingest the catalog entity** by adding the `catalog.locations` section in your {product-very-short} `{my-app-config-file}` file that links to the `catalog-info.yaml` file: +. Ingest the catalog entity: Add the location of your `catalog-info.yaml` to the `catalog.locations` section in your {product-very-short} `{my-app-config-file}` file: + [source,yaml] ---- catalog: locations: - type: url - target: https://github.com/owner/repo/catalog-info.yaml + target: https://github.com///catalog-info.yaml ---- -. (Optional) Customize the thresholds for the *GitHub Open Pull Requests* (`github.open_prs`) metric by adding the following section to your {product-very-short} `{my-app-config-file}` file: +. Optional: Customize thresholds: Define custom roles for the *GitHub Open Pull Requests* (`github.open_prs`) metric in 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 index 409980d286..b7cc0041b4 100644 --- a/modules/observe/scorecards/proc-configuring-jira-scorecards-in-rhdh-instance.adoc +++ b/modules/observe/scorecards/proc-configuring-jira-scorecards-in-rhdh-instance.adoc @@ -1,14 +1,11 @@ :_mod-docs-content-type: PROCEDURE [id="proc-configuring-jira-scorecards-in-rhdh-instance_{context}"] -= Configuring Jira Scorecards to view Jira metrics in your {product} instance += Integrating Jira health metrics using Scorecards -To bring critical project tracking and workflow data from Atlassian Jira directly into your {product-very-short} instance, you must configure the Jira Scorecards plugin. This integration provides engineering teams with a centralized view of development status and reduces context switching, enabling faster assessment of component readiness and delivery velocity. +You can configure the Jira Scorecard plugin to display project tracking and delivery velocity data in your {product-very-short} instance. This integration centralizes development status and facilitates the evaluation of component readiness. -The following Jira versions are supported: - -* Jira Cloud: API version 3 -* Jira Data Center: API version 2 +The plugin supports Jira Cloud (API v3) and Jira Data Center (API v2). .Prerequisites @@ -22,24 +19,24 @@ To install and configure Jira Scorecards in your {product-very-short} instance, [NOTE] ==== -You must use the proxy setup to ensure configuration compatibility if the Roadie Jira Frontend Plugin is also in use. +You must use the proxy setup to ensure configuration compatibility if you also use the Roadie Jira Frontend Plugin. ==== -. 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`. +. Generate 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 create a `Base64-encoded` string using the following plain text format: `your-atlassian-email:your-jira-api-token`. + [source,bash] ---- 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. +** Jira datacenter: Create a https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html[Personal Access Token (PAT)] in your Jira datacenter account. -. 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: +. Add Jira secrets: Define the following key/value pairs in {configuring-book-link}#provisioning-your-custom-configuration[your {product-very-short} secrets]: + -`JIRA_TOKEN`:: Enter your Jira token. +`JIRA_TOKEN`:: Enter your generated Jira token. `JIRA_BASE_URL`:: Enter your Jira base URL. -. Install the Jira Scorecard plugin in your {product-very-short} `dynamic-plugins-config.yaml` file using either a direct setup or a proxy setup. +. Configure the plugin: In your {product-very-short} `dynamic-plugins-config.yaml` file, enable the plugin 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` file: + @@ -99,8 +96,7 @@ where: * For *Cloud*: `Basic YourCreatedCloudToken` * For *Data Center*: `Bearer YourJiraToken` -. Annotate the component entity in the `catalog-info.yaml` file. -.. Link the component to the Jira data source by adding the necessary annotations: +. Annotate catalog entities: Add the Jira project key to the `metadata.annotations` section of the `catalog-info.yaml` file for your component: + [source,yaml] ---- @@ -130,17 +126,17 @@ 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}` file that links to the `catalog-info.yaml` file: +. Ingest the catalog entity: Add the location of your `catalog-info.yaml` to the `catalog.locations` section in the {product-very-short} `{my-app-config-file}` file: + [source,yaml] ---- catalog: locations: - type: url - target: https://github.com/owner/repo/catalog-info.yaml + target: https://github.com///catalog-info.yaml ---- -. (Optional) Configure *Jira Open Issues* metric thresholds by adding the following to your {product-very-short} `{my-app-config-file}` file: +. Optional: Define metric thresholds and filters: To customize health criteria or filter issues, add the *Jira Open Issues* metric thresholds to your {product-very-short} `{my-app-config-file}` file: + [source,yaml] ---- @@ -162,7 +158,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 that entities can override by adding the following code to your {product-very-short} `{my-app-config-file}` file: +. Optional: Define global or custom mandatory filters that entities can override by adding the following code to your {product-very-short} `{my-app-config-file}` 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 index b1ca67a831..b4248086b0 100644 --- a/modules/observe/scorecards/proc-installing-scorecard-plugin-in-rhdh-instance.adoc +++ b/modules/observe/scorecards/proc-installing-scorecard-plugin-in-rhdh-instance.adoc @@ -1,9 +1,9 @@ :_mod-docs-content-type: PROCEDURE [id="proc-installing-scorecard-plugin-in-rhdh-instance_{context}"] -= Installing the Scorecard plugin in your {product} instance += Enabling Scorecards -You must manually install and enable the plugin in your {product} instance. +To monitor component health and quality in {product-very-short}, you must enable the Scorecard plugin in your configuration. .Prerequisites * You have installed your {product-very-short} instance. diff --git a/modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc b/modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc index d2926df01b..338fec4a86 100644 --- a/modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc +++ b/modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc @@ -1,18 +1,18 @@ :_mod-docs-content-type: PROCEDURE [id="proc-viewing-scorecards-in-rhdh_{context}"] -= Viewing Scorecard metrics in {product} += Monitoring component health and readiness with Scorecard metrics -As a developer, you can view the GitHub and Jira metrics using Scorecards in your {product-very-short} instance to quickly gain at-a-glance visibility into the health and readiness of your software components. By accessing the *Scorecard* tab in your {product-very-short} instance, you eliminate context switching and can immediately verify security, compliance, and development metrics (like GitHub and Jira data). +View Scorecard metrics to evaluate the health and security of your software components directly in the {product-very-short} catalog. .Prerequisites * You have installed your {product-very-short} instance. -* You have either the GitHub or Jira Scorecard (or both) configured in your {product-very-short} instance. +* You have configured the GitHub or Jira Scorecard (or both) plugin. * You must have permissions to read the Scorecard metrics. .Procedure . In your {product-very-short} navigation menu, go to *Catalog*. . Select the software component (catalog entity) that has Scorecard metrics configured. -. On the component *Service* page, go to the *Scorecard* tab. -. To view the desired metrics, select the corresponding tile. \ No newline at end of file +. On the component *Service* page, click the *Scorecard* tab. +. Select a metric tile to view detailed data. \ No newline at end of file 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 index 923893404a..1c8ff9b7d2 100644 --- 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 @@ -1,13 +1,13 @@ :_mod-docs-content-type: REFERENCE [id="ref-override-rules-to-configure-entity-specific-thresholds_{context}"] -= Override rules to configure entity-specific thresholds += Override rules to configure entity-specific thresholds in Scorecards -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. +Use annotations in the `catalog-info.yaml` file of a component to override global threshold rules. These annotations merge with and take precedence over the global rules defined in your {product-very-short} `{my-app-config-file}` file. -.Annotation Format Reference +.Annotation structure -The annotation key follows a strict structure: +The annotation key must use the following format: `scorecard.io/{providerId}.thresholds.rules.{thresholdKey}: '{expression}'` [cols="1,2,2,2", options="header"] @@ -30,9 +30,9 @@ The annotation key follows a strict structure: | `>15` |=== -.Example: Entity Annotation Override +.Example: Override global Jira thresholds -The following example describes the entity overriding; that is, only the `warning` and `error` rules for the `jira.open_issues` metric. The `success` defaults rule to the value defined in the global {product-very-short} `{my-app-config-file}` file. +In the following example, the component overrides the `warning` and `error` rules for the `jira.open_issues` metric. The `success` rule remains unchanged from the global configuration. [source,yaml] ---- @@ -42,11 +42,10 @@ kind: Component metadata: name: critical-production-service annotations: - # Overrides the global 'warning' rule (e.g., changing '11-50' to '10-15') + # Changes global 'warning' from '11-50' to '10-15' scorecard.io/jira.open_issues.thresholds.rules.warning: '10-15' - # Overrides the global 'error' rule (e.g., changing '>50' to '>15') + # Changes global 'error' from '>50' to '>15' scorecard.io/jira.open_issues.thresholds.rules.error: '>15' - # The 'success' rule (<10) remains defined by the global app-config spec: type: service ---- \ No newline at end of file diff --git a/modules/observe/scorecards/ref-supported-metrics-providers.adoc b/modules/observe/scorecards/ref-supported-metrics-providers.adoc index 2eb70b28bc..4d981eceb6 100644 --- a/modules/observe/scorecards/ref-supported-metrics-providers.adoc +++ b/modules/observe/scorecards/ref-supported-metrics-providers.adoc @@ -1,13 +1,11 @@ :_mod-docs-content-type: REFERENCE [id="ref-supported-metric-providers_{context}"] -= Supported metric providers in {product} += Supported Scorecard metrics providers -The Scorecard plugin collects metrics from third-party data sources using metric providers. +When you need to understand what service metrics are available, the Scorecard plugin gathers data from third-party systems through metric providers. The following table helps you identify which metrics are available for each supported provider, so you can decide what data to use for evaluating your services. -The Scorecard node plugin provides the `scorecardMetricsExtensionPoint` extension point that is used to connect your backend plugin module that exports custom metrics via metric providers to the Scorecard backend plugin. - -The following metric providers are available: +The following metric providers are supported: [cols="1,1,2,3,1", options="header"] |=== @@ -16,12 +14,12 @@ The following metric providers are available: | GitHub | `github.open_prs` | GitHub open PRs -| Count of open Pull Requests in GitHub +| Number of open pull requests in GitHub. | number | Jira | `jira.open_issues` | Jira open issues -| The number of opened issues in Jira +| Number of open issues in Jira. | number |=== \ No newline at end of file diff --git a/modules/observe/scorecards/ref-supported-threshold-expressions.adoc b/modules/observe/scorecards/ref-supported-threshold-expressions.adoc index 7de0831bd7..bb6934c6f3 100644 --- a/modules/observe/scorecards/ref-supported-threshold-expressions.adoc +++ b/modules/observe/scorecards/ref-supported-threshold-expressions.adoc @@ -1,9 +1,9 @@ :_mod-docs-content-type: REFERENCE [id='ref-supported-threshold-expressions_{context}'] -= Supported Threshold expressions in {product} += Supported Scorecard threshold expression syntax -Threshold expressions are highly flexible and support standard mathematical and logical operators based on the data type of the metric. +Metric threshold expressions use mathematical and logical operators to evaluate data. Use the following operators to define health criteria based on the metric data type. [cols="1,2,3,4", options="header"] |=== @@ -12,15 +12,15 @@ Threshold expressions are highly flexible and support standard mathematical and | Number | `>`, `>=`, `<`, `<=`, `==`, `!=` | `>40` -| Assigns category if the value is greater than 40. +| The category applies if the value is greater than 40. | Number | `-` (Range) | `80-100` -| Assigns category if the value is between 80 and 100 (inclusive). +| The category applies if the value is between 80 and 100 (inclusive). | Boolean | `==`, `!=` | `==true` -| Assigns category if the value is exactly true. +| The category applies if the value is exactly true. |=== \ No newline at end of file diff --git a/modules/observe/scorecards/ref-threshold-rules-to-metrics-for-scorecard-plugin.adoc b/modules/observe/scorecards/ref-threshold-rules-to-metrics-for-scorecard-plugin.adoc index 4781f31b6c..3733f9c494 100644 --- a/modules/observe/scorecards/ref-threshold-rules-to-metrics-for-scorecard-plugin.adoc +++ b/modules/observe/scorecards/ref-threshold-rules-to-metrics-for-scorecard-plugin.adoc @@ -1,9 +1,9 @@ :_mod-docs-content-type: REFERENCE [id="ref-threshold-rules-to-metrics-for-scorecard-plugin_{context}"] -= Threshold rules to metrics for your Scorecard plugin += Scorecard metric threshold precedence -Thresholds are merged based on a strict priority order, allowing you to set defaults while granting specific entities the ability to override rules. +Threshold rules follow a specific order of precedence. Higher-priority configurations override lower-priority settings, allowing you to define global defaults with entity-specific exceptions. [cols="1,2,2,4", options="header"] |=== @@ -12,15 +12,15 @@ Thresholds are merged based on a strict priority order, allowing you to set defa | 1 (Highest) | Entity Annotations | `catalog-info.yaml` -| Override specific rules for an individual component. +| Overrides specific rules for a single component. | 2 (Medium) | App Configuration | `app-config.yaml` -| Set global rules that override provider defaults. +| Sets global rules that override provider defaults. | 3 (Lowest) | Provider Defaults | Backend Plugin Code -| Baseline rules defined by the metric source developer. +| Baseline rules defined by the metric source. |=== \ No newline at end of file diff --git a/titles/scorecard-plugin/master.adoc b/titles/scorecard-plugin/master.adoc index 769a759a42..31f64d18b6 100644 --- a/titles/scorecard-plugin/master.adoc +++ b/titles/scorecard-plugin/master.adoc @@ -1,7 +1,8 @@ include::artifacts/attributes.adoc[] :context: title-scorecard-plugin :imagesdir: images -:title: Understand and visualize {product} project health using Scorecards +// For 1.9, change the title to "Evaluate your project health using Scorecards" +:title: Evaluate project health using Scorecards :subtitle: Setting up, configuring, and managing customizable Project Health Scorecards :abstract: When using {product} ({product-very-short}), you can understand and visualize the health, security posture, and compliance of your software components so that you can centrally monitor Key Performance Indicators (KPIs) collected from third-party systems like GitHub and Jira without consulting multiple external tools. = {title}