GitHub 应用程序

可以将 Backstage 配置为使用 GitHub 应用程序进行后端身份验证，这样做的好处是速率限制更高，而且 Backstage 可以作为应用程序而不是用户或机器人账户使用。

与 OAuth 应用程序及其各自的范围相比，它还提供了一个更清晰、更好的授权模型。

注意事项

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.

使用该 cli 创建的 GitHub 应用程序默认具有读取权限。如果需要，您必须手动更新 GitHub 中的 GitHub 应用程序设置，为应用程序授予更多权限。

使用 CLI(仅限 GitHub 公版)

您可以使用backstage-cli这样我们就能自动完成创建 GitHub 应用程序所需的部分工作。

yarn backstage-cli create-github-app <github org>

您可以阅读更多关于backstage-cli create-github-app指挥。

执行 CLI 命令后，会在项目根目录下生成一个 YAML 文件，然后将其用作include在你的app-config.yaml你可以继续跳过如果您已经有了一个应用程序。

请注意，创建的应用程序将有一个默认为禁用的网络钩子，并指向smee.io目前，Backstage 中也没有使用 webhook 的部分。

GitHub 企业版

您必须使用以下命令手动创建 GitHub 应用程序说明因为 GitHub 企业版不支持从清单创建应用程序。

创建应用程序后，您必须为应用程序生成私钥，并将其放入 YAML 文件中。

YAML 文件必须包含以下信息。请注意，YAML 文件中的privateKey是必需的。

appId: app id
clientId: client id
clientSecret: client secret
webhookSecret: webhook secret
privateKey: |
  -----BEGIN RSA PRIVATE KEY-----
  ...Key content...
  -----END RSA PRIVATE KEY-----

包括在集成配置中

一旦证书存储在由create-github-app或手动按照GitHub 企业版指令，可将它们纳入app-config.yaml根据integrations节。

请注意，凭据文件具有高度敏感性，不应将其放入任何类型的版本控制中。请使用您喜欢的安全方法来分发Secret。

integrations:
  github:
    - host: github.com
      apps:
        - $include: example-backstage-app-credentials.yaml

限制安装 GitHub 应用程序

如果要限制Backstage可见的 GitHub 应用程序安装，可以选择在程序中加入allowedInstallationOwners如果您配置了多个应用程序，指定该选项会带来一些性能上的小优势，因为Backstage可以更轻松地选择哪个应用程序用于 URL。

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-----

这将导致Backstage阻止使用任何不在允许列表内的安装。

应用程序权限

创建 GitHub 应用程序时，必须选择权限，以定义应用程序的访问级别。所需权限因集成用途而异：

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) - Commit statuses: Read-only - Variables: Read & write (if templates include GitHub Action Repository Variables) - Secrets: Read & write (if templates include GitHub Action Repository Secrets) - Environments: Read & write (if templates include GitHub Environments)

故障排除

HttpError: This endpoint requires you to be authenticated.

该信息往往会包裹一个NotFoundError: No app installation found即使是通过backstage-cli作为组织的成员和应用程序管理器，应用程序不会自动安装。您必须拥有Owner在组织中的作用，以了解Install菜单，然后手动按下Install批准申请。

注意事项​

使用 CLI(仅限 GitHub 公版)​

GitHub 企业版​

包括在集成配置中​

限制安装 GitHub 应用程序​

应用程序权限​

故障排除​