Merge branch 'main' into sc-22948-update-grafana

content/backstage/plugins/cost-insights.md

@@ -24,7 +24,7 @@ gettingStarted:
 
   - intro: Create a CostInsights client which implements the CostInsightsApi interface.
   - intro:
-      Cost Insights currently does not provide a CostInsightsApi client out of the box, but there are templates and examples in the Backstage repo. Here's an exploration into [Cost Insights for AWS](https://github.com/backstage/backstage/blob/master/plugins/cost-insights/contrib/aws-cost-explorer-api.md).
+      Cost Insights currently does not provide a CostInsightsApi client out of the box, but there are templates and examples in the Backstage repo. Here's an exploration into [Cost Insights for AWS](https://github.com/backstage/community-plugins/blob/main/workspaces/cost-insights/plugins/cost-insights/contrib/aws-cost-explorer-api.md).
     language: typescript
     code: |
       // path/to/CostInsightsClient.ts

content/backstage/plugins/jira.md

@@ -50,8 +50,7 @@ gettingStarted:
         '/jira/api':
           target: '<JIRA_URL>'
           headers:
-            Authorization:
-              $env: JIRA_TOKEN
+            Authorization: ${JIRA_TOKEN}
             Accept: 'application/json'
             Content-Type: 'application/json'
             X-Atlassian-Token: 'nocheck'
@@ -75,7 +74,7 @@ gettingStarted:
     language: typescript
     code: |
       // packages/app/src/components/catalog/EntityPage.tsx
-      import { EntityJiraOverviewCard, isJiraAvailable } from '@roadiehq/backstage-plugin-jira';
+      import { EntityJiraOverviewCard, isJiraAvailable, hasJiraQuery } from '@roadiehq/backstage-plugin-jira';
 
       const overviewContent = (
         <Grid container spacing={3} alignItems="stretch">
@@ -85,6 +84,12 @@ gettingStarted:
                 <EntityJiraOverviewCard />
               </Grid>
             </EntitySwitch.Case>
+            <EntitySwitch.Case if={hasJiraQuery}>
+               <Grid item md={6}>
+                 {/* This card can be used as an alternative or in addition to the overview card */}
+                 <EntityJiraQueryCard title="Our Custom Query" />
+               </Grid>
+             </EntitySwitch.Case>
           </EntitySwitch>
         </Grid>
       );
@@ -98,6 +103,8 @@ gettingStarted:
           jira/project-key: <example-jira-project-key>
           jira/component: <example-component> # optional, you might skip this value to fetch data for all components
           jira/token-type: Bearer # optional, used for Activity stream feed. If you are using Basic auth you can skip this.
+          jira/label: <example-label> # optional, refine filter based on a label or labels (CSV)
+          jira/all-issues-jql: # optional, used by EntityJiraQueryCard, this query supports basic templating with the above annotations if present, and information from the user profile. e.g. "assignee = {{ userEmail }} AND label = ({{ label }})"
 
   - intro: Even though you can use Bearer token please keep in mind that Activity stream feed will only contain entries that are visible to anonymous users. In order to view restricted content you will need to authenticate via Basic authentication, as described in official documentation (https://developer.atlassian.com/server/framework/atlassian-sdk/consuming-an-activity-streams-feed/#authentication).
 

content/backstage/plugins/tech-insights.md

@@ -211,6 +211,6 @@ const ttlWithAHumanReadableValue = { timeToLive: { weeks: 2 } }; // Deletes item
 
 ## More information
 
-* [Tech Insights backend README file](https://github.com/backstage/backstage/tree/master/plugins/tech-insights-backend)
-* [Tech Insights frontend README file](https://github.com/backstage/backstage/tree/master/plugins/tech-insights)
-* [Tech Insights JSON rules engine implementation README file](https://github.com/backstage/backstage/tree/master/plugins/tech-insights-backend-module-jsonfc)
+* [Tech Insights backend README file](https://github.com/backstage/community-plugins/blob/main/workspaces/tech-insights/plugins/tech-insights-backend/README.md)
+* [Tech Insights frontend README file](https://github.com/backstage/community-plugins/blob/main/workspaces/tech-insights/plugins/tech-insights/README.md)
+* [Tech Insights JSON rules engine implementation README file](https://github.com/backstage/community-plugins/blob/main/workspaces/tech-insights/plugins/tech-insights-backend-module-jsonfc/README.md)

content/docs/catalog/location-management/index.md

@@ -6,45 +6,42 @@ description: How to configure locations autodiscovery
 
 ## Introduction
 
-The Backstage catalog uses location entities to point to external sources which define entities. Roadie will update your 
-entities in Backstage whenever one of the repositories defined in a location is updated. 
+The Backstage catalog uses location entities to point to external sources which define entities. Roadie will update your
+entities in Backstage whenever one of the repositories defined in a location is updated.
 
 Autodiscovery is the mechanism to define patterns pointing to filenames in URLs that should be queried for entity files.
 
 For more information about locations and troubleshooting Catalog ingestion issues you can take a look at the [catalog troubleshooting documentation](/docs/details/troubleshooting-the-catalog)
 
-
 ## Setting up autodiscovery
 
 Roadie supports autodiscovery for integrations configured in the application. The configuration of an autodiscovery entry can be done at the same time as integration is configured to start automatic polling of entities. You can navigate to `https://<your-tenant>.roadie.so/administration/settings/` to find configuration options for each supported autodiscovery target
 
 ### GitHub Autodiscovery and Organization Autodiscovery
 
-GitHub integration for Roadie provides two autodiscovery targets, entities and teams/groups. 
+GitHub integration for Roadie provides two autodiscovery targets, entities and teams/groups.
 
 ![GitHub Autodiscovery of Catalog Files](./gh_autodiscovery.webp)
 
-The GitHub *autodiscovery* integration can be configured to automatically discover catalog entities from a provided configured path pointing to GitHub. 
+The GitHub _autodiscovery_ integration can be configured to automatically discover catalog entities from a provided configured path pointing to GitHub.
 
 More information about possible patterns and examples of URLs can be found from the [Backstage GitHub Discovery documentation.](https://backstage.io/docs/integrations/github/discovery#configuration)
 
 ![GitHub organization autodiscovery](gh_org_ingestion.webp)
 
-The GitHub *organization* integration provides the possibility to automatically import GitHub users and teams/groups from an organization. You can configure this discovery type by providing the name of the GitHub organization. Note that the GitHub app needs to be installed for that organization and needs to have permissions to access user info.
+The GitHub _organization_ integration provides the possibility to automatically import GitHub users and teams/groups from an organization. You can configure this discovery type by providing the name of the GitHub organization. Note that the GitHub app needs to be installed for that organization and needs to have permissions to access user info.
 
 ### AWS S3 Autodiscovery
 
-
 ![AWS S3 autodiscovery target](./s3_entry.webp)
 
 AWS S3 autodiscovery can be configured to download catalog files from an S3 bucket. For this to be functionality the [integration configuration for AWS S3](/docs/integrations/aws-s3) must be done. S3 autodiscovery does not support wildcard path, it must point to a specific prefix of an S3 bucket.
 
 ### Azure DevOps
 
-
 ![Azure DevOps autodiscovery target](./azure-autodiscovery.webp)
 
-Azure DevOps autodiscovery can be configured to download catalog files from Azure DevOps SCM. For this to be functionality the [integration configuration for Azure Devops](/docs/integrations/azure-devops-provider) must be done. 
+Azure DevOps autodiscovery can be configured to download catalog files from Azure DevOps SCM. For this to be functionality the [integration configuration for Azure Devops](/docs/integrations/azure-devops-provider) must be done.
 
 ### Bitbucket Autodiscovery
 
@@ -75,17 +72,17 @@ describes the url format for Bitbucket Cloud (reproduced from Backstage.io):
   [See here for the specification](https://developer.atlassian.com/bitbucket/api/2/reference/meta/filtering)
   for the query argument (will be passed as the `q` query parameter).
 - (Optional) The `search=true` query argument to activate the mode utilizing code search.
-    - Is mutually exclusive to the `q` query argument.
-    - Allows providing values at `catalogPath` for finding catalog files as allowed by the `path` filter/modifier
-      [at Bitbucket Cloud's code search](https://confluence.atlassian.com/bitbucket/code-search-in-bitbucket-873876782.html#Search-Pathmodifier).
-        - `catalogPath=/catalog-info.yaml`
-        - `catalogPath=catalog-info.yaml` (anywhere in the repository)
-        - `catalogPath=/path/catalog-info.yaml`
-        - `catalogPath=path/catalog-info.yaml`
-        - `catalogPath=/path/*/catalog-info.yaml`
-        - `catalogPath=path/*/catalog-info.yaml`
-    - Supports multiple catalog files per repository depending on the `catalogPath` value.
-    - Registers `Location` entities for existing files only vs all matching repositories.
+  - Is mutually exclusive to the `q` query argument.
+  - Allows providing values at `catalogPath` for finding catalog files as allowed by the `path` filter/modifier
+    [at Bitbucket Cloud's code search](https://confluence.atlassian.com/bitbucket/code-search-in-bitbucket-873876782.html#Search-Pathmodifier).
+    - `catalogPath=/catalog-info.yaml`
+    - `catalogPath=catalog-info.yaml` (anywhere in the repository)
+    - `catalogPath=/path/catalog-info.yaml`
+    - `catalogPath=path/catalog-info.yaml`
+    - `catalogPath=/path/*/catalog-info.yaml`
+    - `catalogPath=path/*/catalog-info.yaml`
+  - Supports multiple catalog files per repository depending on the `catalogPath` value.
+  - Registers `Location` entities for existing files only vs all matching repositories.
 
 Examples:
 
@@ -136,13 +133,31 @@ The format is slightly different for Bitbucket server. The url is composed of fo
   will result in:
   `https://bitbucket.mycompany.com/projects/my-project/repos/service-a/catalog-info.yaml`.
 
+### GitHub Enterprise Server Autodiscovery
+
+The GitHub autodiscovery integration can be configured to automatically discover catalog entities from a provided configured path pointing to GitHub.
+
+#### GHES Broker Autodiscovery
+
+You can also connect to your GitHub Enterprise server via the broker connection. 
+![GHES broker configuration](./broker-ghes-configuration.webp)
+
+To enable autodiscovery of entities via the broker, you can add entries to the autodiscovery section of the settings page.
+Click the + sign next to the `Configure GHES via the Broker` to open the input dialog to configure the GHES target URL via the broker.
+Within the opened dialog you can add the URL of your GitHub organization or repository directly, as it is referenced in the main configuration section. If the broker connection is configured, these URLs will be automatically translated to use the broker protocol. Note that this configuration only affects the GHES when it is configured via a broker and won't affect discovery if broker configuration is not present.
+
+Once you have added the information about your GHES instance and organization, you can see your existing configured target URLs in the list below
+![GHES broker autodiscovery](./broker-ghes-discovery.webp). 
+
+The autodiscovery kicks in shortly after the save action and automatically refreshes discovered entities periodically
+
 ## Managing Locations
 
-A list of all configured locations is located in URL `https://<your-tenant>.roadie.so/administration/locations/management`. 
+A list of all configured locations is located in URL `https://<your-tenant>.roadie.so/administration/locations/management`.
 
 ![Location management table](./location_mgmt.webp)
 
-The list contains an entry for all locations added as an autodiscovery configuration within each integration, as well as locations imported using the Catalog Import functionality within  `https://<your-tenant>.roadie.so/import/entity`. 
+The list contains an entry for all locations added as an autodiscovery configuration within each integration, as well as locations imported using the Catalog Import functionality within `https://<your-tenant>.roadie.so/import/entity`.
 
 Note that deleting a location via the administration UI (either at the location management page or at the individual integration page) does not automatically remove individual entities that have been found from that location. If the desired effect is to remove all items from a particular location, it is better to find that location via the catalog and[ unregister it from there.](/docs/details/unregister-components)
 

content/docs/custom-plugins/available-apis/index.md

@@ -37,7 +37,7 @@ The code above would produce a view like this:
 `discoveryApi` provides connectivity to the Roadie backend APIs. The API can be used to identify the correct endpoints to call when, for example, integrating with third party services via the Roadie proxy.
 
 ```tsx
-import React, { useCallback } from "react";
+import React, { useCallback, useState } from "react";
 import { useEntity } from "@backstage/plugin-catalog-react";
 import { discoveryApiRef, useApi } from "@backstage/core-plugin-api";
 import { StructuredMetadataTable } from "@backstage/core-components";
@@ -67,7 +67,7 @@ export const MyComponent = () => {
 `identifyApi` provides information about the currently logged in user. This API can be used to target individuals or decorate requests with relevant user information.
 
 ```tsx
-import React from "react";
+import React, {useState} from "react";
 import useAsync from "react-use/lib/useAsync";
 import { BackstageUserIdentity, ProfileInfo, identityApiRef, useApi } from "@backstage/core-plugin-api";
 import { StructuredMetadataTable } from "@backstage/core-components";
@@ -166,4 +166,4 @@ export const MyComponent = () => {
    return <div><Button onClick={btnClicked}>Click me!</Button></div>
 };
 
-```
+```

content/docs/custom-plugins/getting-started/index.md

@@ -62,7 +62,7 @@ When we have navigated the available files and are happy with how they look, we
 
 First we need to install needed dependencies. We will run `npm i` from the root of the monorepo. This may take some time depending on your internet connection.
 
-After needed dependencies are installed we can spin up a development server in watch mode `npm run develop:watch --workspace=docs-plugin`
+After needed dependencies are installed we can spin up a development server in watch mode `npm run develop:watch --workspace=<your-plugin-name>`
 
 ![monorepo_developing.gif](monorepo_developing.gif)
 

content/docs/details/create-proxy/examples/fragments/index.md

@@ -110,6 +110,6 @@ Click the "Authorization" field and type "Bearer ${CUSTOMER_TOKEN_3}"
 <div role="alert">
   <div class="docs-cta__info_title">What's Next?</div>
   <div  class="docs-cta__info_message">
-    <p>Check out <a href="/docs/tech-insights/track-fragments/">Create Data Source for Entity Fragments</a> to start using your newly created proxy.</p>
+    <p>Check out <a href="/docs/tech-insights/track-fragments/">Track Fragments</a> to start using your newly created proxy.</p>
   </div>
 </div> 

content/docs/details/how-roadie-connects/index.md

@@ -124,19 +124,21 @@ For this, we use the broker to securely send Tech Insights requests into custome
 
 This way, customers get all of the reporting and automation power of Tech Insights, without exposing APIs externally.
 
-### Option 3 (coming soon): Push to the API
+### Option 3: Push to the API
 
 Of course, sometimes you want to collect or compute data internally, before sending it to Roadie’s scorecarding product for display.
 
 For example, you may wish to compute whether or not SLOs are being met by each service. That would require calculating based your own definition of what it means to meet an SLO. This type of computation is better done under the full control of the customer.
 
-To support this, we will soon add an API endpoint which customers can use to push data into Tech Insights.
+To support this, the "Push based data source" provides you with an API endpoint you can use to push data into Tech Insights.
+
+![configuration for the push based data source](./push-based-ds.webp)
 
 # Bonus: How your tools connect to Roadie
 
 Of course, getting data into Roadie is only half the battle. Once Roadie has a catalog of your software, it can be useful to send this data into other tools, like deployment or reporting tools.
 
-To support this, we provide all Growth Plan customers with API access.
+To support this, we provide all Growth Plan customers with [API access](/docs/api/authorization/).
 
 # The bottom line
 

content/docs/details/managing-policies/index.md

@@ -0,0 +1,42 @@
+---
+title: Managing Policies
+publishedDate: '2024-11-05T21:00:00.0Z'
+description: How to configure and manage policies in Roadie for access control.
+---
+
+## Introduction
+
+**This feature is currently in the process of being rolled out. If you want access, please contact our support or sales teams.**
+
+In Roadie, **policies** are integral components of the permissions framework, governing access control within the platform. They define the rules and conditions under which users can perform specific actions on various resources, such as services, components, or documentation.
+
+**Key aspects of policies:**
+
+- **Authorization Decisions:** Policies determine whether a user is permitted to execute a particular action. For instance, a policy might allow only the owner of a service to delete it from the catalog. 
+- **Conditional Logic:** Policies can incorporate complex conditions, such as verifying if a user belongs to a specific group or possesses certain attributes, to make nuanced authorization decisions. 
+- **Customization:** Administrators have the flexibility to craft custom policies tailored to their organization's unique requirements, ensuring that access controls align with internal processes and security standards. 
+
+By implementing policies, Roadie ensures that access to resources is managed effectively, enhancing security and maintaining the integrity of the development environment.
+
+To configure this in Roadie we provide a UI for **Policies Management** and you can access it at: `https://<tenant name>.roadie.so/administration/settings/policies`.
+
+Currently, a set of permissions is available from the upstream Backstage project, with the option to create and validate new permissions.
+
+- Built-in policies cannot be modified or removed, but they can be added to or removed from roles.
+- Each policy can be configured with an effect to either **ALLOW** or **DENY** the specified permissions and the conditions set for the policy.
+
+### Conditions for Configurable Permissions
+
+Some permissions allow configuration with a set of conditions, particularly those starting with `catalog.entity.`. These conditions enable access customization based on defined rules. Currently, these are the available rules:
+
+| Rule Name             | Parameters            | Description                                                                 |
+| --------------------- | --------------------- | --------------------------------------------------------------------------- |
+| isEntityOwner         | None                  | Checks if the user is the owner of the entity.                              |
+| isUserEntity          | None                  | Checks if the entity represents the current user.                           |
+| hasOwnEntityName      | None                  | Validates that the entity has its own unique name.                          |
+| hasOwnEntityNamespace | None                  | Confirms that the entity has its own designated namespace.                  |
+| hasEntityKind         | `kinds`               | Checks if the entity is of a specific kind (e.g., Component, API).          |
+| hasSpec               | `key`, `value`        | Verifies the entity’s specification includes a specific key-value pair.     |
+| hasMetadata           | `key`, `value`        | Ensures the entity metadata contains a specific key-value pair.             |
+| hasLabel              | `label`               | Checks if the entity includes a specific label in its metadata.             |
+| hasAnnotation         | `annotation`, `value` | Validates the presence of a particular annotation in the entity’s metadata. |