Skip to content

Commit

Permalink
Update docs to mention http via integration data source (#1116)
Browse files Browse the repository at this point in the history
  • Loading branch information
iain-b authored Sep 8, 2023
1 parent b3c5006 commit 31766b5
Show file tree
Hide file tree
Showing 5 changed files with 11 additions and 18 deletions.
12 changes: 7 additions & 5 deletions content/docs/tech-insights/define-custom-data-sources/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,18 +19,20 @@ To set up a Data Source, you will, firstly, need to enter general information su
![Add Data Provider](./data-provider-step.png)

1 - You must specify a type for that new Data Source. Roadie provides few different types of data provider configurations:
1. The _HTTP_ type lets you connect to an external API to pull in data
2. _Component repository file_ type lets you extract data from a file path in the corresponding repository of a given Component in your Catalog
3. _Component repository directory_ type allows you to extract a list of files from the repository
1. The _HTTP_ type lets you connect to an external API via the Backstage proxy to pull in data
2. The _HTTP via Integration_ type les you connect directly to external APIs where there's an integration configured with Roadie. For example, you can use the GitHub app to authenticate requests to the GitHub API.
3. _Component repository file_ type lets you extract data from a file path in the corresponding repository of a given Component in your Catalog
4. _Component repository directory_ type allows you to extract a list of files from the repository

2 - Set additional configuration options depending on the type of the data provider
1. For _HTTP_ type
1. _proxy:_ Select a proxy from the provided dropdown
2. _path extension:_ The path to append to the proxy URL to which the HTTP call should be made. There is basic support for templating entity values into the path. E.g. `etc/{{ metadata.name }}` would insert the name of the entity. The path extension should be input without the preceding slash.
3. _HTTP Method:_ The HTTP method to use for the request. Mostly this will be `GET` but `POST` is also supported for graphQL and other endpoints which take query params through the request body.
4. _Body:_ For POST requests you can also send a body. Templating is also supported in the request body in the same way as above.
2. For _Component repository file_ configure the path to the file you want to extract data from in repositories, starting from the root. This can be anything from JSON files to YAML files.
3. For _Component repository_ configure the root folder where you want to list files from. To identify the repository root, you can use `.`.
2. For _HTTP via Integration_ type you only need to set the _path extension_. The path to append to the base URL of the ingeration to which the HTTP call should be made. There is basic support for templating entity values into the path. E.g. `etc/{{ metadata.name }}` would insert the name of the entity. The path extension should be input without the preceding slash.
3. For _Component repository file_ configure the path to the file you want to extract data from in repositories, starting from the root. This can be anything from JSON files to YAML files.
4. For _Component repository_ configure the root folder where you want to list files from. To identify the repository root, you can use `.`.

3 - Try out what would be the response when testing specific entity from the location you have provided. If you were to get the `package.json` from a `sample-service` component, the Data Source would get something like this:

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 2 additions & 6 deletions content/docs/tech-insights/enforce-branch-protection/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,7 @@ As we go through this process, you’ll learn how to create Data Sources that in

## Prerequisites

1. You must have a Personal Access Token (PAT) for GitHub set in Administration → Settings → Secrets → GITHUB_TOKEN. This PAT must have the “repo” scope enabled.

We recommend creating the PAT on an account which has admin permissions in GitHub. Tokens associated with regular user accounts will not be able to see the branch protection settings on all repositories. [Learn how to create a PAT in the GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).

![pat permissions](./pat-permissions.png)
1. You must have [intalled the Roadie GitHub App](../../getting-started/install-github-app/).

## Create a branch protection Data Source

Expand All @@ -31,7 +27,7 @@ As we go through this process, you’ll learn how to create Data Sources that in

![about.png](./about.png)

3. In the Data Provider section, select the built-in “/github/api” proxy and enter the Path Extension
3. In the Data Provider section, select the **"HTTP via Integration"** type and enter the Path Extension

```
repos/{{ metadata.annotations["github.com/project-slug"] }}/branches/main/protection
Expand Down
9 changes: 2 additions & 7 deletions content/docs/tech-insights/track-codeowners-usage/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,7 @@ In this tutorial, we’re going to create a Tech Insights check that tracks adop

## Prerequisites

1. You must have a Personal Access Token (PAT) for GitHub set in Administration → Settings → Secrets → GITHUB_TOKEN. This PAT must have the “repo” scope enabled.

We recommend creating the PAT on an account which has admin permissions in GitHub. Tokens associated with regular user accounts will not be able to see the branch protection settings on all repositories. [Learn how to create a PAT in the GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).

![pat permissions](../enforce-branch-protection/pat-permissions.png)

1. You must have [intalled the Roadie GitHub App](../../getting-started/install-github-app/).

## Create a branch protection Data Source

Expand All @@ -29,7 +24,7 @@ In this tutorial, we’re going to create a Tech Insights check that tracks adop

![about.png](./about.png)

3. In the Data Provider section, select the built-in “/github/api” proxy and enter the Path Extension
3. In the Data Provider section, select the **"HTTP via Integration"** type and enter the Path Extension

```
repos/{{ metadata.annotations["github.com/project-slug"] }}/codeowners/errors
Expand Down
Binary file modified content/docs/tech-insights/track-codeowners-usage/response.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 31766b5

Please sign in to comment.