diff --git a/artifacts/attributes.adoc b/artifacts/attributes.adoc index 7aea302480..1489dd2f17 100644 --- a/artifacts/attributes.adoc +++ b/artifacts/attributes.adoc @@ -168,3 +168,6 @@ :upgrading-book-title: Upgrading {product} :using-dynamic-plugins-book-link: {product-docs-link}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index :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-title: Understanding and visualizing {product} project health using Scorecards \ No newline at end of file diff --git a/artifacts/snip-developer-preview.adoc b/artifacts/snip-developer-preview-lightspeed.adoc similarity index 100% rename from artifacts/snip-developer-preview.adoc rename to artifacts/snip-developer-preview-lightspeed.adoc diff --git a/artifacts/snip-developer-preview-scorecard.adoc b/artifacts/snip-developer-preview-scorecard.adoc new file mode 100644 index 0000000000..f8e3417557 --- /dev/null +++ b/artifacts/snip-developer-preview-scorecard.adoc @@ -0,0 +1,6 @@ +[IMPORTANT] +==== +This section describes Developer Preview features in the Scorecard plugin. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. + +For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope]. +==== diff --git a/assemblies/assembly-configuring-scorecards-in-rhdh.adoc b/assemblies/assembly-configuring-scorecards-in-rhdh.adoc new file mode 100644 index 0000000000..821f6521e3 --- /dev/null +++ b/assemblies/assembly-configuring-scorecards-in-rhdh.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: ASSEMBLY + +[id="assembly-configuring-scorecards-in-rhdh"] += Installing and configuring Scorecards to view metrics in your {product} instance +:context: assembly-configuring-scorecards-in-rhdh + +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 + +include::modules/observe/scorecards/proc-configuring-github-scorecards-in-rhdh-instance.adoc[leveloffset=+1] + +include::modules/observe/scorecards/proc-configuring-jira-scorecards-in-rhdh-instance.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-scorecards-rhdh.adoc b/assemblies/assembly-scorecards-rhdh.adoc new file mode 100644 index 0000000000..c8c632814e --- /dev/null +++ b/assemblies/assembly-scorecards-rhdh.adoc @@ -0,0 +1,29 @@ +:_mod-docs-content-type: ASSEMBLY + +[id="assembly-rhdh-observability"] += Understanding and visualizing {product} project health using Scorecards +:context: assembly-scorecards-rhdh + +include::modules/observe/scorecards/con-understand-scorecard-plugins.adoc[leveloffset=+1] + +include::modules/observe/scorecards/con-supported-metrics-providers.adoc[leveloffset=+2] + +include::assembly-setting-up-scorecards-to-monitor-your-rhdh-health.adoc[leveloffset=+1] + +include::assembly-configuring-scorecards-in-rhdh.adoc[leveloffset=+1] + +include::modules/observe/scorecards/con-manage-metric-thresholds-in-scorecard-plugin.adoc[leveloffset=+1] + +include::modules/observe/scorecards/con-how-thresholds-work.adoc[leveloffset=+2] + +include::modules/observe/scorecards/ref-supported-threshold-expressions.adoc[leveloffset=+2] + +include::modules/observe/scorecards/ref-threshold-rules-to-metrics-for-scorecard-plugin.adoc[leveloffset=+2] + +include::modules/observe/scorecards/con-set-global-standards-for-metric-thresholds.adoc[leveloffset=+2] + +include::modules/observe/scorecards/ref-override-rules-to-configure-entity-specific-thresholds.adoc[leveloffset=+2] + +include::modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc[leveloffset=+2] + +include::modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-setting-up-scorecards-to-monitor-your-rhdh-health.adoc b/assemblies/assembly-setting-up-scorecards-to-monitor-your-rhdh-health.adoc new file mode 100644 index 0000000000..409bb9f7af --- /dev/null +++ b/assemblies/assembly-setting-up-scorecards-to-monitor-your-rhdh-health.adoc @@ -0,0 +1,9 @@ +:_mod-docs-content-type: ASSEMBLY + +[id="assembly-setting-up-scorecards-to-monitor-your-rhdh-health"] += Setting up Scorecards to monitor your {product} project health +:context: assembly-setting-up-scorecards-to-monitor-your-rhdh-health + +include::modules/observe/scorecards/proc-installing-scorecard-plugin-in-rhdh-instance.adoc[leveloffset=+1] + +include::modules/observe/scorecards/proc-authenticating-and-managing-scorecard-plugins.adoc[leveloffset=+1] \ No newline at end of file diff --git a/images/rhdh/scorecard-create-role.png b/images/rhdh/scorecard-create-role.png new file mode 100644 index 0000000000..c39e94b1b7 Binary files /dev/null and b/images/rhdh/scorecard-create-role.png differ diff --git a/images/rhdh/scorecard-sample.png b/images/rhdh/scorecard-sample.png new file mode 100644 index 0000000000..aa1860d38e Binary files /dev/null and b/images/rhdh/scorecard-sample.png differ diff --git a/modules/developer-lightspeed/con-about-developer-lightspeed.adoc b/modules/developer-lightspeed/con-about-developer-lightspeed.adoc index 3d2d966ea7..fb440177e3 100644 --- a/modules/developer-lightspeed/con-about-developer-lightspeed.adoc +++ b/modules/developer-lightspeed/con-about-developer-lightspeed.adoc @@ -3,7 +3,7 @@ [id="con-about-developer-lightspeed_{context}"] = About {ls-short} -include::{docdir}/artifacts/snip-developer-preview.adoc[] +include::{docdir}/artifacts/snip-developer-preview-lightspeed.adoc[] This early access program enables customers to share feedback on the user experience, features, capabilities, and any issues encountered. Your input helps ensure that {ls-short} better meets your needs when it is officially released and made generally available. diff --git a/modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc b/modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc new file mode 100644 index 0000000000..f7860aea5b --- /dev/null +++ b/modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc @@ -0,0 +1,33 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-best-practices-for-threshold-rules"] += Best practices for threshold rules + +Threshold rule evaluation is order-dependent. You must follow logical ordering to avoid unintended category assignments, as the system stops evaluation once a value matches the first rule. + +== Follow logical ordering + +Rules must be sequenced logically. Order rules from the most strict (smallest range) to the least strict (largest range) or ensure all ranges are mutually exclusive. + +=== Problematic rule order example + +If rules are ordered incorrectly, a less restrictive rule can prevent stricter rules from being evaluated: + +. `warning: <50`: Any value less than 50 triggers the warning rule and stops evaluation. +. `success: <10`: This rule is not evaluated because all values less than 10 have already matched the preceding warning rule. + +=== Correct ordering example + +Order the rules from the most restrictive value range to the least restrictive to ensure a logical flow. + +[source,yaml] +---- +# Correct Example: Order from most restrictive (Success) to least restrictive (Error) +rules: + - key: success + expression: '<10' # Only values below 10 + - key: warning + expression: '10-50' # Only values between 10 and 50 + - key: error + expression: '>50' # All remaining values above 50 +---- \ No newline at end of file diff --git a/modules/observe/scorecards/con-how-thresholds-work.adoc b/modules/observe/scorecards/con-how-thresholds-work.adoc new file mode 100644 index 0000000000..4fbec4e892 --- /dev/null +++ b/modules/observe/scorecards/con-how-thresholds-work.adoc @@ -0,0 +1,10 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-how-thresholds-work_{context}"] += How Thresholds work + +A threshold defines a condition or an expression that determines which visual category a metric value belongs to. + +* Evaluation Order: Threshold rules are evaluated in the order they are defined. The first matching rule is applied to the metric value. +* Allowed Categories: Only three keys are supported: `success`, `warning`, and `error`. +* Best Practice: Always order rules from the most restrictive to the least restrictive to ensure logical assignment. \ No newline at end of file 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 new file mode 100644 index 0000000000..492ba90e34 --- /dev/null +++ b/modules/observe/scorecards/con-manage-metric-thresholds-in-scorecard-plugin.adoc @@ -0,0 +1,6 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-manage-metric-thresholds-in-scorecard-plugin_{context}"] += Managing metric thresholds in your Scorecard plugin + +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 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 new file mode 100644 index 0000000000..0500a92aac --- /dev/null +++ b/modules/observe/scorecards/con-set-global-standards-for-metric-thresholds.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: CONCEPT + +[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} `{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. + +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. + +[source,yaml] +---- +scorecard: + plugins: + jira: + open_issues: + thresholds: + rules: + - key: success + expression: '<10' # fewer than 10 open issues is Success + - key: warning + expression: '10-50' # Between 10 and 50 is a Warning + - key: error + expression: '>50' # More than 50 open issues is an Error +---- \ No newline at end of file diff --git a/modules/observe/scorecards/con-supported-metrics-providers.adoc b/modules/observe/scorecards/con-supported-metrics-providers.adoc new file mode 100644 index 0000000000..add91718ae --- /dev/null +++ b/modules/observe/scorecards/con-supported-metrics-providers.adoc @@ -0,0 +1,25 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-supported-metric-providers_{context}"] += Supported metric providers in {product} + +The Scorecard plugin collects metrics from third-party data sources using metric providers. 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: + +[cols="1,1,2,3,1", options="header"] +|=== +| Provider | Metric ID | Title | Description | Type + +| GitHub +| `github.open_prs` +| GitHub open PRs +| Count of open Pull Requests in GitHub +| number + +| Jira +| `jira.open_issues` +| Jira open issues +| The number of opened issues in Jira +| number +|=== \ 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 new file mode 100644 index 0000000000..cf3ca151c4 --- /dev/null +++ b/modules/observe/scorecards/con-understand-scorecard-plugins.adoc @@ -0,0 +1,10 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-understand-scorecard-plugin_{context}"] += Understand Scorecard plugins in {product} + +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. + +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 new file mode 100644 index 0000000000..61801efbeb --- /dev/null +++ b/modules/observe/scorecards/proc-authenticating-and-managing-scorecard-plugins.adoc @@ -0,0 +1,31 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-authenticating-and-managing-scorecard-plugins_{context}"] += Authenticating and managing Scorecard plugins to control who sees the 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 provide 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. + +.Prerequisite + * You have {authorization-book-link}#enabling-and-giving-access-to-rbac[enabled RBAC, have a policy administrator role in Developer Hub, and have added scorecard to plugins with permission]. + +.Procedure +. Set the required RBAC permissions using any of the following methods: +** To use the csv file, in your csv file, you can directly add the following code: ++ +[source,yaml] +---- +g, user:default/, role:default/scorecard-viewer +p, role:default/scorecard-viewer, scorecard.metric.read, read, allow +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*: +**** *Name*: `scorecard.metric.read` +**** *Permission*: `read` + +image::rhdh/scorecard-create-role.png[] \ 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 new file mode 100644 index 0000000000..bcb3be2767 --- /dev/null +++ b/modules/observe/scorecards/proc-configuring-github-scorecards-in-rhdh-instance.adoc @@ -0,0 +1,123 @@ +:_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 + +You can view GitHub metrics for software components registered in the {product-very-short} catalog. To allow the {product-very-short} to access the GitHub API, you must create a GitHub App and configure the necessary integration. + +.Prerequisites + +* You have installed your {product-very-short} instance. +* You have {scorecard-plugin-book-link}#proc-installing-scorecard-plugin-in-rhdh-instance[installed the Scorecard images]. +* You must have permissions in GitHub to create and manage a https://docs.github.com/en/apps/overview[GitHub App]. +* 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 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). +.. Generate a client secret and a private key. +.. Install the app on the desired account/organization. +.. Save the following values: +*** `App ID` +*** `Client ID` +*** `Client secret` +*** `Private key` +.. Add your GitHub credentials to {configuring-book-link}#provisioning-your-custom-configuration[your {product-very-short} secrets] using the following key/value pairs. You can use these secrets in the {product-very-short} configuration files by using their respective environment variable names. +*** `GITHUB_INTEGRATION_APP_ID` +*** `GITHUB_INTEGRATION_CLIENT_ID` +*** `GITHUB_INTEGRATION_CLIENT_SECRET` +*** `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: ++ +[source,yaml] +---- +integrations: + github: + - host: ${GITHUB_INTEGRATION_HOST_DOMAIN} + apps: + - appId: ${GITHUB_INTEGRATION_APP_ID} + clientId: ${GITHUB_INTEGRATION_CLIENT_ID} + clientSecret: ${GITHUB_INTEGRATION_CLIENT_SECRET} + privateKey: | + ${GITHUB_INTEGRATION_PRIVATE_KEY_FILE} +---- + +. 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] +---- +plugins: + - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-github:bs_1.42.5__1.0.0!red-hat-developer-hub-backstage-plugin-scorecard-backend-module-github + disabled: false +---- + +. In your {product-very-short} entity that you want to configure for the GitHub Scorecard plugin, in the `catalog-info.yaml` file, link a component to the data source by adding the required annotations as shown in the following code: ++ +[source,yaml] +---- +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: my-service + annotations: + # Required: GitHub project slug in format "owner/repository" + github.com/project-slug: myorg/my-service + # Required: Entity source location + backstage.io/source-location: url:https://github.com/myorg/my-service +spec: + type: service + lifecycle: production + owner: __ +---- ++ +where: + +`annotations:github.com/project-slug`:: The GitHub repository format, for example, `owner/repository`. +`annotations:backstage.io/source-location`:: The entity source location format, for example, `url:https://github.com/owner/repository`. +`spec:owner`:: Your team name. ++ +[NOTE] +==== +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}` that links to the `catalog-info.yaml` file: ++ +[source,yaml] +---- +catalog: + locations: + - type: url + target: https://github.com/owner/repo/catalog-info.yaml +---- + +. (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] +---- +scorecard: + plugins: + github: + open_prs: + thresholds: + rules: + - key: success + expression: '<10' + - key: warning + expression: '10-50' + - key: error + expression: '>50' +---- ++ +where: + +`scorecard:plugins:github:open_prs:thresholds`:: Lists the default threshold values for the GitHub open PRs metric. + +[NOTE] +==== +To read more information about how to customize the threshold values, see link:https://documentation.example.com/scorecard-plugins-thresholds/[Thresholds in Scorecard plugins]. +==== \ No newline at end of file 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 new file mode 100644 index 0000000000..58ec02db73 --- /dev/null +++ b/modules/observe/scorecards/proc-configuring-jira-scorecards-in-rhdh-instance.adoc @@ -0,0 +1,180 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-configuring-jira-scorecards-in-rhdh-instance_{context}"] += Configuring Jira Scorecards to view GitHub metrics in your {product} instance + +To view project tracking data from Atlassian Jira in your {product-very-short} instance, configure Jira Scorecards. +The following Jira versions are supported: + +* Jira Cloud: API version 3 +* Jira Data Center: API version 2 + +.Prerequisites + +* You must have administrator privileges for Jira and {product-very-short}. +* You have installed your {product-very-short} instance. +* You have {scorecard-plugin-book-link}#proc-installing-scorecard-plugin-in-rhdh-instance[installed the Scorecard images]. +* 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`. ++ +[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. + +. 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` + +. 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: ++ +[source,yaml] +---- +jira: + baseUrl: ${JIRA_BASE_URL} + token: ${JIRA_TOKEN} + product: __ +---- +where: + +`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: ++ +[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: ++ +[source,yaml] +---- +proxy: + endpoints: + '/jira/api': + target: ${JIRA_BASE_URL} + headers: + Accept: 'application/json' + Content-Type: 'application/json' + X-Atlassian-Token: 'no-check' + Authorization: ${JIRA_TOKEN} # Must be configured in your environment +jira: + proxyPath: /jira/api + product: cloud # Change to 'datacenter' if using Jira Datacenter +---- ++ +where: + +`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`. +.. In the `catalog-info.yaml` file for the entity you want to configure, link the component to the Jira data source by adding the necessary annotations: ++ +[source,yaml] +---- +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: my-service + annotations: + jira/project-key: PROJECT + jira/component: Component + jira/label: UI + jira/team: 9d3ea319-fb5b-4621-9dab-05fe502283e + jira/custom-filter: 'reporter = "abc@xyz.com" AND resolution is not EMPTY' +spec: + type: website + lifecycle: experimental + owner: guests + system: examples + providesApis: [example-grpc-api] +---- ++ +where: + +`jira/project-key`:: Required: Enter the Jira project key. +`jira/component`:: Optional: Enter the Jira component name. +`jira/label`:: Optional: Enter the Jira label. +`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} `{my-app-config-file}` file: ++ +[source,yaml] +---- +scorecard: + plugins: + jira: + open_issues: + thresholds: + rules: + - key: success + expression: '<10' + - key: warning + expression: '10-50' + - key: error + expression: '>50' +---- ++ +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: ++ +[source,yaml] +---- +scorecard: + plugins: + jira: + open_issues: + options: + mandatoryFilter: Type = Task AND Resolution = Unresolved + customFilter: priority in ("Critical", "Blocker") +---- ++ +where: + +`mandatoryFilter`:: Optional: Replaces the default filter (`type = Bug and resolution = Unresolved`). +`customFilter`:: Optional: Specifies a global custom filter. The entity annotation `jira/custom-filter` overrides this value. + +For more information about how to customize the threshold values, see link:https://documentation.example.com/scorecard-plugins-thresholds/[Thresholds in Scorecard plugins]. \ No newline at end of file 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 new file mode 100644 index 0000000000..b1ca67a831 --- /dev/null +++ b/modules/observe/scorecards/proc-installing-scorecard-plugin-in-rhdh-instance.adoc @@ -0,0 +1,40 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-installing-scorecard-plugin-in-rhdh-instance_{context}"] += Installing the Scorecard plugin in your {product} instance + +You must manually install and enable the plugin in your {product} instance. + +.Prerequisites +* You have installed your {product-very-short} instance. +* You have provisioned your custom {installing-and-viewing-plugins-book-link}[dynamic plugins config map]. + +.Procedure + +* Add the following configuration in your {product-very-short} `dynamic-plugin-config.yaml` file: ++ +[source,yaml] +---- +plugins: + - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.42.5__1.0.0!red-hat-developer-hub-backstage-plugin-scorecard + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-scorecard: + entityTabs: + - path: '/scorecard' + title: Scorecard + mountPoint: entity.page.scorecard + mountPoints: + - mountPoint: entity.page.scorecard/cards + importName: EntityScorecardContent + config: + layout: + gridColumn: 1 / -1 + if: + allOf: + - 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 +---- \ No newline at end of file diff --git a/modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc b/modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc new file mode 100644 index 0000000000..bd8028d253 --- /dev/null +++ b/modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc @@ -0,0 +1,18 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-viewing-scorecards-in-rhdh_{context}"] += Viewing Scorecard metrics in {product} + +As a developer, you can view the GitHub and Jira metrics using the *Scorecards* in your {product-very-short} instance. + +.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 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 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 new file mode 100644 index 0000000000..daac66b18d --- /dev/null +++ b/modules/observe/scorecards/ref-override-rules-to-configure-entity-specific-thresholds.adoc @@ -0,0 +1,52 @@ +:_mod-docs-content-type: REFERENCE + +[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} `{my-app-config-file}` file. + +.Annotation Format Reference + +The annotation key follows a strict structure: +`scorecard.io/{providerId}.thresholds.rules.{thresholdKey}: '{expression}'` + +[cols="1,2,2,2", options="header"] +|=== +| Element | Description | Example Annotation | Example Value + +| `{providerId}` +| Unique identifier of the metric +| `scorecard.io/jira.open_issues...` +| `jira.open_issues` + +| `{thresholdKey}` +| The overridden category +| `...rules.warning` +| `success`, `warning`, or `error` + +| `{expression}` +| The new condition for the rule +| `...: '>15'` +| `>15` +|=== + +.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} `{my-app-config-file}` file. + +[source,yaml] +---- +# catalog-info.yaml +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: critical-production-service + annotations: + # Overrides the global 'warning' rule (e.g., changing '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') + 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-threshold-expressions.adoc b/modules/observe/scorecards/ref-supported-threshold-expressions.adoc new file mode 100644 index 0000000000..7de0831bd7 --- /dev/null +++ b/modules/observe/scorecards/ref-supported-threshold-expressions.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: REFERENCE + +[id='ref-supported-threshold-expressions_{context}'] += Supported Threshold expressions in {product} + +Threshold expressions are highly flexible and support standard mathematical and logical operators based on the data type of the metric. + +[cols="1,2,3,4", options="header"] +|=== +| Metric Type | Operator | Example Expression | Job Performed + +| Number +| `>`, `>=`, `<`, `<=`, `==`, `!=` +| `>40` +| Assigns category if the value is greater than 40. + +| Number +| `-` (Range) +| `80-100` +| Assigns category if the value is between 80 and 100 (inclusive). + +| Boolean +| `==`, `!=` +| `==true` +| Assigns category 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 new file mode 100644 index 0000000000..4781f31b6c --- /dev/null +++ b/modules/observe/scorecards/ref-threshold-rules-to-metrics-for-scorecard-plugin.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: REFERENCE + +[id="ref-threshold-rules-to-metrics-for-scorecard-plugin_{context}"] += Threshold rules to metrics for your Scorecard plugin + +Thresholds are merged based on a strict priority order, allowing you to set defaults while granting specific entities the ability to override rules. + +[cols="1,2,2,4", options="header"] +|=== +| Priority | Configuration Method | Location | Job Performed + +| 1 (Highest) +| Entity Annotations +| `catalog-info.yaml` +| Override specific rules for an individual component. + +| 2 (Medium) +| App Configuration +| `app-config.yaml` +| Set global rules that override provider defaults. + +| 3 (Lowest) +| Provider Defaults +| Backend Plugin Code +| Baseline rules defined by the metric source developer. +|=== \ No newline at end of file diff --git a/titles/scorecard-plugin/artifacts b/titles/scorecard-plugin/artifacts new file mode 120000 index 0000000000..f30b6dea60 --- /dev/null +++ b/titles/scorecard-plugin/artifacts @@ -0,0 +1 @@ +../../artifacts \ No newline at end of file diff --git a/titles/scorecard-plugin/assemblies b/titles/scorecard-plugin/assemblies new file mode 120000 index 0000000000..91646274db --- /dev/null +++ b/titles/scorecard-plugin/assemblies @@ -0,0 +1 @@ +../../assemblies \ No newline at end of file diff --git a/titles/scorecard-plugin/docinfo.xml b/titles/scorecard-plugin/docinfo.xml new file mode 100644 index 0000000000..5f7fe2ebac --- /dev/null +++ b/titles/scorecard-plugin/docinfo.xml @@ -0,0 +1,11 @@ +{title} +{product} +{product-version} +{subtitle} + + {abstract} + + + {company-name} Customer Content Services + + diff --git a/titles/scorecard-plugin/images b/titles/scorecard-plugin/images new file mode 120000 index 0000000000..5fa6987088 --- /dev/null +++ b/titles/scorecard-plugin/images @@ -0,0 +1 @@ +../../images \ No newline at end of file diff --git a/titles/scorecard-plugin/master.adoc b/titles/scorecard-plugin/master.adoc new file mode 100644 index 0000000000..27b7b3559e --- /dev/null +++ b/titles/scorecard-plugin/master.adoc @@ -0,0 +1,9 @@ +include::artifacts/attributes.adoc[] +:context: title-scorecard-plugin +:imagesdir: images +:title: Understanding and visualizing {product} 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} + +include::assemblies/assembly-scorecards-rhdh.adoc[leveloffset=+1] \ No newline at end of file diff --git a/titles/scorecard-plugin/modules b/titles/scorecard-plugin/modules new file mode 120000 index 0000000000..36719b9de7 --- /dev/null +++ b/titles/scorecard-plugin/modules @@ -0,0 +1 @@ +../../modules/ \ No newline at end of file