docs: Restructure Github apps documentation
Signed-off-by: Johan Haals <johan.haals@gmail.com>
This commit is contained in:
Johan Haals
@@ -112,11 +112,10 @@ const builder = await CatalogBuilder.create(env);
|
||||
builder.setProcessingIntervalSeconds(300);
|
||||
```
|
||||
|
||||
Alternatively, or additionally, you can configure [github-apps] authentication
|
||||
Alternatively, or additionally, you can configure [github-apps](github-apps.md) authentication
|
||||
which carries a much higher rate limit at GitHub.
|
||||
|
||||
This is true for any method of adding GitHub entities to the catalog, but
|
||||
especially easy to hit with automatic discovery.
|
||||
|
||||
[rate limits]: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
|
||||
[github-apps]: ../../plugins/github-apps.md
|
||||
|
||||
@@ -0,0 +1,135 @@
|
||||
---
|
||||
id: github-apps
|
||||
title: GitHub Apps for Backend Authentication
|
||||
description: Configure GitHub Apps for Backend Authentication
|
||||
---
|
||||
|
||||
Backstage can be configured to use GitHub Apps for backend authentication. This
|
||||
comes with advantages such as higher rate limits and that Backstage can act as
|
||||
an application instead of a user or bot account.
|
||||
|
||||
It also provides a much clearer and better authorization model as a opposed to
|
||||
the OAuth apps and their respective scopes.
|
||||
|
||||
## Caveats
|
||||
|
||||
- This authentication method is built for authenticating towards
|
||||
organization repositories and not towards personal repositories.
|
||||
- It's not possible to have multiple Backstage GitHub Apps installed in the same
|
||||
GitHub organization, to be handled by Backstage. We currently don't check
|
||||
through all the registered GitHub Apps to see which ones are installed for a
|
||||
particular repository. We only respect global Organization installs right now.
|
||||
- App permissions is not managed by Backstage. They're created with some simple
|
||||
default permissions which you are free to change as you need, but you will
|
||||
need to update them in the GitHub web console, not in Backstage right now. The
|
||||
permissions that are defaulted are `metadata:read` and `contents:read`.
|
||||
- The created GitHub App is private by default, this is most likely what you
|
||||
want for github.com but it's recommended to make your application public for
|
||||
GitHub Enterprise in order to share application across your GHE organizations.
|
||||
|
||||
A GitHub app created with the cli will have read
|
||||
access by default. You have to manually update the GitHub App settings in GitHub
|
||||
to grant the app more permissions if needed.
|
||||
|
||||
### Using the CLI (public GitHub only)
|
||||
|
||||
You can use the `backstage-cli` to create a GitHub App using a manifest file
|
||||
that we provide. This gives us a way to automate some of the work required to
|
||||
create a GitHub app.
|
||||
|
||||
```console
|
||||
yarn backstage-cli create-github-app <github org>
|
||||
```
|
||||
|
||||
You can read more about the
|
||||
[`backstage-cli create-github-app`](../../local-dev/cli-commands.md#create-github-app) command.
|
||||
|
||||
Once you've gone through the CLI command, it should produce a YAML file in the
|
||||
root of the project which you can then use as an `include` in your
|
||||
`app-config.yaml`. You can go ahead and
|
||||
[skip ahead](#including-in-integrations-config) if you've already got an app.
|
||||
|
||||
Note that the created app will have a webhook that is disabled by default and
|
||||
points to `smee.io`, which is intended for local development. There's also
|
||||
currently no part of Backstage that makes use of the webhook.
|
||||
|
||||
### GitHub Enterprise
|
||||
|
||||
You have to create the GitHub Application manually using these
|
||||
[instructions](https://docs.github.com/en/free-pro-team@latest/developers/apps/creating-a-github-app)
|
||||
as GitHub Enterprise does not support creation of apps from manifests.
|
||||
|
||||
Once the application is created you have to generate a private key for the
|
||||
application and place it in a YAML file.
|
||||
|
||||
The YAML file must include the following information. Please note that the
|
||||
indentation for the `privateKey` is required.
|
||||
|
||||
```yaml
|
||||
appId: app id
|
||||
clientId: client id
|
||||
clientSecret: client secret
|
||||
webhookSecret: webhook secret
|
||||
privateKey: |
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
...Key content...
|
||||
-----END RSA PRIVATE KEY-----
|
||||
```
|
||||
|
||||
### Including in Integrations Config
|
||||
|
||||
Once the credentials are stored in a YAML file generated by `create-github-app`,
|
||||
or manually by following the [GitHub Enterprise](#gitHub-enterprise)
|
||||
instructions, they can be included in the `app-config.yaml` under the
|
||||
`integrations` section.
|
||||
|
||||
Please note that the credentials file is highly sensitive and should NOT be
|
||||
checked into any kind of version control. Instead use your preferred secure
|
||||
method of distributing secrets.
|
||||
|
||||
```yaml
|
||||
integrations:
|
||||
github:
|
||||
- host: github.com
|
||||
apps:
|
||||
- $include: example-backstage-app-credentials.yaml
|
||||
```
|
||||
|
||||
### Limiting the GitHub App installations
|
||||
|
||||
If you want to limit the GitHub app installations visible to backstage you may
|
||||
optionally include the `allowedInstallationOwners` option.
|
||||
|
||||
```yaml
|
||||
appId: app id
|
||||
allowedInstallationOwners: ['GlobexCorp']
|
||||
clientId: client id
|
||||
clientSecret: client secret
|
||||
webhookSecret: webhook secret
|
||||
privateKey: |
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
...Key content...
|
||||
-----END RSA PRIVATE KEY-----
|
||||
```
|
||||
|
||||
This will result in backstage preventing the use of any installation that is not
|
||||
within the allow list.
|
||||
|
||||
### App permissions
|
||||
|
||||
When creating a GitHub App, you must select permissions to define the level of
|
||||
access for the app. The permissions required vary depending on your use of the
|
||||
integration:
|
||||
|
||||
- Reading software components:
|
||||
- `Contents`: `Read-only`
|
||||
- Reading organization data:
|
||||
- `Members`: `Read-only`
|
||||
- Publishing software templates:
|
||||
|
||||
- `Administration`: `Read & write` (for creating repositories)
|
||||
- `Contents`: `Read & write`
|
||||
- `Metadata`: `Read-only`
|
||||
- `Pull requests`: `Read & write`
|
||||
- `Issues`: `Read & write`
|
||||
- `Workflows`: `Read & write` (if templates include GitHub workflows)
|
||||
@@ -75,8 +75,6 @@ your use of the integration:
|
||||
|
||||
## Authentication with GitHub Apps
|
||||
|
||||
Alternatively, Backstage can use GitHub Apps for backend authentication. This
|
||||
has higher rate limits, and a clearer authorization model. See [github-apps] for
|
||||
Alternatively for GitHub organizations, Backstage can use GitHub Apps for backend authentication. This
|
||||
has higher rate limits, and a clearer authorization model. See [github-apps](github-apps.md) for
|
||||
how to set this up.
|
||||
|
||||
[github-apps]: ../../plugins/github-apps.md
|
||||
|
||||
Reference in New Issue
Block a user