Add GitHub Apps documentation

Co-authored-by: blam <ben@blam.sh>
2021-01-14 13:47:47 +01:00
parent 58cb92f91e
commit 4e623b7bf2
1 changed files with 78 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Using GithubApps for backend authentication
+
+Backstage can be configured to use GitHub Apps for backend authentication. This
+come 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
+
+- It's not possible to have multiple backstage GitHub Apps installed in the same
+  Github organization be managed by Backstage. We currently don't check through
+  all the registered GitHub Apps to see which ones are installed for a
+  particular repository. We just 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
+- 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 `backstage-cli create-github-app` 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 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.
+
+You can read more about the `backstage-cli create-github-app` method
+[here](../cli/commands.md#create-github-app)
+
+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 to
+[here](#including-in-integrations-config) if you've got to this part.
+
+### 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 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: 1
+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.
+
+```yaml
+integrations:
+  github:
+    - host: github.com
+    apps:
+        - $include: example-backstage-app-credentials.yaml
+```