# 在企业组织中自动执行应用安装

通过在企业中创建一个 GitHub App 并以编程方式安装它，在各个组织之间以一致的方式将某个流程自动化。

## 介绍

若要安全地自动执行流程，可以创建 GitHub App 企业帐户拥有的应用，然后在将进行自动化的企业或组织中安装应用。

GitHub Apps 提供可用于在脚本和工作流中对 API 调用 GitHub 进行身份验证的令牌。 这些令牌适用于具有特定安全性和审核要求的企业，因为它们是：

* 临时
* 范围限定为特定帐户和权限
* 与应用的标识（而不是用户帐户）相关联

大型企业的一个常见需求是确保自动化流程在多个组织中保持一致并保持最新。 可以通过以编程方式安装应用来实现此目的。 例如，如果您需要为所有组织配置某些策略和设置，则可以在每个组织中安装一个 GitHub App 来完成此任务。

本指南将演示在某个组织中通过编程方式安装企业所有的 GitHub App 所需的步骤。 安装应用后，你将使用它创建新的存储库。

## 流程概述

在本指南中，你将使用 GitHub CLI 发出请求访问令牌以及在组织中安装应用所需的 API 调用。 实际上，此过程将成为根据公司需求定制的自定义脚本的一部分。

你将执行以下操作：

1. 创建两个由你的企业帐户所拥有的应用程序。
   * 某人将有权在组织中安装应用。
   * 另一个将有权自动执行组织中的流程（在本例中，创建存储库）。
2. 对第一个应用进行身份验证，以获取 **企业范围的** 访问令牌。
3. 使用企业级令牌调用 API 以在组织中安装自动化应用。
4. 对组织安装的应用进行身份验证，以获取 **组织范围的** 访问令牌。
5. 使用组织范围内的令牌调用 API，该 API 在组织中创建存储库。

在每个阶段，你将使用仅有权在特定帐户中执行特定动作的令牌。 从安全和审核的角度来看，此方法优于依赖拥有在企业内和各组织间执行权限的单一令牌。

## 先决条件

若要在自己的设备上遵循本指南，必须：

* 成为企业所有者。
* 成为由企业所有的组织的所有者，你将在该组织中执行自动化。
* 安装好 GitHub CLI 以进行 API 调用。 请参阅存储库中的GitHub CLI[安装](https://github.com/cli/cli?tab=readme-ov-file#installation)。
* 请安装 `openssl` 以生成 JSON Web 令牌（JWT）。 默认情况下，许多设备都安装了 OpenSSL。 可以通过运行 `openssl -v`来检查，这将返回版本号（如果已安装）。
* 使用 Unix shell，例如 Bash、ZSH 或 Git Bash。

## 1.准备生成 JWT

若要从应用请求访问令牌，需要从应用的客户端 ID 和私钥生成的 JSON Web 令牌（JWT）。 许多编程语言具有用于生成 JWT 的内置方法。 在本教程中，你将使用 Bash 脚本，通过命令行使用 `openssl` 生成一个 JWT。

1. 复制 Bash 脚本的内容，以便从 [为GitHub应用生成 JSON Web 令牌 （JWT）](/zh/enterprise-server@3.21/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app#example-using-bash-to-generate-a-jwt) 生成 JWT。
2. 将内容保存在主目录中的一个新文件中，命名为 `gen-jwt.sh`。
3. 使脚本可执行。

   ```shell copy
   chmod +x ~/gen-jwt.sh
   ```

## 2.创建两个企业应用

GitHub Apps 只能在你允许的细粒度权限和账户范围内生成令牌。 在此步骤中，你将创建两个企业拥有的应用：一个具有 **企业级** 安装应用的权限，另一个具有 **组织级** 权限来创建存储库。

### a。 创建安装程序应用

“安装程序应用”将安装在企业帐户上，并有权在组织中安装其他应用。

1. 在企业帐户下创建新应用。

   1. 转到企业帐户设置。
   2. 在左侧栏中，单击 **GitHub Apps**。
   3. 单击“ **新建 GitHub App**”。

2. 可以将大部分值保留为默认值，但以下情况除外：

   * 调用应用 `YOUR-HANDLE-installer-app`，将 `YOUR-HANDLE` 替换为您的 GitHub 用户名。
   * 将“主页 URL”设置为 `https://github.com`。
   * 取消勾选 **“过期用户授权令牌”**，然后在“Webhook”下取消勾选 **“启用”**。
   * 在“企业权限”下，为 **企业组织安装**提供应用读取和写入权限。

3. 创建应用后，复制**客户端 ID** 并将其另存为一个名为`INSTALLER_APP_CLIENT_ID`的变量。 例如，在命令行上：

   ```shell copy
   export INSTALLER_APP_CLIENT_ID='abcde12345'
   ```

4. 在应用页上，向下滚动并单击“ **生成私钥**”。 将下载私钥文件。

5. 记下文件路径，其形式大概会是 `~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem` 这样。

6. 在应用页面的左侧栏中，单击“ **安装应用**”，然后在企业帐户上安装新应用。 安装应用程序可授予应用在帐户中执行操作的权限。

7. 查看浏览器中的 URL，查找应用的安装 ID。 这是位于 URL 末尾的一串数字 `/enterprises/ENTERPRISE/settings/installations/ID`。 将此保存为 `INSTALLER_APP_INSTALL_ID` 变量。

   ```shell copy
   export INSTALLER_APP_INSTALL_ID='12345678'
   ```

8. 保存应用作为变量安装的企业的名称。

   ```shell copy
   export ENTERPRISE='octo-enterprise'
   ```

### b. 创建自动化应用

“自动化应用”将安装在组织中，并且有权在该组织中创建存储库。 实际上，你将向此应用提供在组织中自动执行流程所需的任何权限。

1. 在企业帐户下创建新应用。
   * 调用应用 `YOUR-HANDLE-automation-app`，将 `YOUR-HANDLE` 替换为你的 GitHub 用户名。
   * 将“主页 URL”设置为 `https://github.com`。
   * 取消勾选 **“过期用户授权令牌”**，然后在“Webhook”下取消勾选 **“启用”**。
   * 在“存储库权限”下，为应用授予 **管理**读取和写入权限。

2. 创建应用后，复制 **客户端 ID** 并将其另存为 `AUTOMATION_APP_CLIENT_ID` 变量。

   ```shell copy
   export AUTOMATION_APP_CLIENT_ID='abcde12345'
   ```

3. 向下滚动并单击“ **生成私钥**”。 将下载私钥文件。

4. 记下文件路径，其形式大概会是 `~/YOUR-HANDLE-automation-app.DOWNLOAD-DATE.private-key.pem` 这样。

5. 保存将应用安装为变量的组织的名称。

   ```shell copy
   export ORG='octo-org'
   ```

## 3.对安装程序应用进行身份验证

通过验证应用，可以获取令牌，其中包含注册应用时定义的作用域和权限。 在这种情况下，你将获取安装程序应用的令牌，这将授予你在组织中安装自动化应用的权限。

1. 使用保存的 Bash 脚本生成 JWT。 例如：

   ```shell copy
   ~/gen-jwt.sh $INSTALLER_APP_CLIENT_ID ~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem
   ```

2. 复制 JWT（之后 `JWT= `的长字符串），并将其另存为变量。

   ```shell copy
   export INSTALL_JWT='abcde12345'
   ```

3. 使用 JWT 对安装访问令牌的请求进行身份验证。 此步骤使用 [为应用 API 终结点创建安装访问令牌](/zh/enterprise-server@3.21/rest/apps/apps#create-an-installation-access-token-for-an-app) ，并且需要应用的安装 ID。

   ```shell copy
   gh api --method POST "/app/installations/$INSTALLER_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $INSTALL_JWT"
   ```

4. 应会看到包含属性的 `token` JSON 对象。 复制访问令牌（属性的值 `token` ，不含引号），并将其保存为 `INSTALLER_APP_INSTALL_TOKEN` 变量。

   ```shell copy
   export INSTALLER_APP_INSTALL_TOKEN='abcde12345'
   ```

## 4.安装自动化应用

刚收到的安装访问令牌授予调用 API 以在组织中安装应用的权限。 在这里，我们将使用该令牌在特定组织中安装自动化应用（你创建的第二个应用）。 实际上，可以多次调用此 API，以在多个组织中安装应用。

1. 运行以下命令。 我们正在使用[“在企业自有组织中安装 GitHub 应用”](/zh/enterprise-server@3.21/rest/enterprise-admin/organization-installations#install-a-github-app-on-an-enterprise-owned-organization)的 API 终结点，并通过您刚刚请求的安装令牌进行身份验证，同时传递我们想要安装的自动化应用的客户端 ID。

   ```shell copy
   gh api --method POST \
     "/enterprises/$ENTERPRISE/apps/organizations/$ORG/installations" \
     --header "Authorization: Bearer $INSTALLER_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "client_id=$AUTOMATION_APP_CLIENT_ID" \
     --field "repository_selection=all"
   ```

2. 如果成功，你应该会看到返回大量属性，从应用程序的安装 ID 开始。

   若要检查应用是否已成功安装，请转到 `https://github.com/organizations/ORG/settings/installations`，将 ORG 替换为组织名称。 应该会在页面上看到新安装的应用。

3. 查找新安装的安装 ID，并将其另存为 `AUTOMATION_APP_INSTALL_ID`。 若要查找 ID，可以复制 API 返回的第一个 ID 属性，或单击 UI 中的应用安装旁边的 **“配置** ”，并从 URL 复制 ID。

   ```shell copy
   export AUTOMATION_APP_INSTALL_ID='12345678'
   ```

## 5.对自动化应用进行身份验证

正如你对安装程序应用进行身份验证以获得企业范围的令牌一样，你现在需要对自动化应用执行相同的过程。 这将为你提供一个组织范围的访问令牌，用于创建存储库的权限。

1. 使用自动化应用的客户端 ID 和私钥生成 JWT。 例如：

   ```shell copy
   ~/gen-jwt.sh $AUTOMATION_APP_CLIENT_ID ~/octocat-automation-app.2025-10-08.private-key.pem
   ```

2. 复制 JWT（之后 `JWT= `的长字符串），并将其另存为变量。

   ```shell copy
   export AUTO_JWT='abcde12345'
   ```

3. 使用 JWT 对安装访问令牌的请求进行身份验证，这次会为新安装的自动化应用传递安装 ID 和 JWT。

   ```shell copy
   gh api --method POST "/app/installations/$AUTOMATION_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $AUTO_JWT"
   ```

4. 复制新的安装访问令牌并将其保存为 `AUTOMATION_APP_INSTALL_TOKEN` 变量。

   ```shell copy
   export AUTOMATION_APP_INSTALL_TOKEN='abcde12345'
   ```

## 6. 自动执行流程

刚收到的安装令牌允许你在安装了应用的组织中创建存储库。

1. 运行以下命令。 请注意，我们正在使用刚刚获取的安装令牌进行身份验证。

   ```shell copy
   gh api --method POST \
     "/orgs/$ORG/repos" \
     --header "Authorization: Bearer $AUTOMATION_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "name=automatic-repo" \
     --field "description=Repository created automatically using GitHub App automation" \
     --field "private=false" \
     --field "auto_init=true"
   ```

2. 若要检查存储库是否已成功创建，请转到 `https://github.com/orgs/ORG/repositories`，将 ORG 替换为组织的名称。

<div class="border rounded-2 p-3">

是否已成功创建存储库？

<a href="https://docs.github.io/success-test/yes.html" target="_blank" class="btn btn-outline mt-3 mr-3 no-underline">
<span>是</span></a><a href="https://docs.github.io/success-test/no.html" target="_blank" class="btn btn-outline mt-3 mr-3 no-underline"><span>否</span></a>

</div>

## 7. 卸载应用

出于安全性，请从企业和组织卸载应用。 这将撤销与应用关联的所有令牌。 有关说明，请参阅“[查看和修改已安装GitHub应用](/zh/enterprise-server@3.21/apps/using-github-apps/reviewing-and-modifying-installed-github-apps)”。

## 后续步骤

你已了解如何在组织中以编程方式安装应用并运行自动化。 现在，你应该准备好跨多个组织自动执行一个实际过程。 有关应用可以执行的功能详细信息，请参阅 [关于创建GitHub应用](/zh/enterprise-server@3.21/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)。

> \[!TIP] 在现实世界中，你可能将安装作为一次性过程执行。 组织级自动化将在由 Webhook 或 cron 作业触发的单独脚本中定义。 但是，安全意识的企业可能更喜欢在每次运行自动化时安装和卸载应用，以便在应用私钥公开时限制影响。