# 将自定义属性与外部系统集成 使用 a GitHub App 将外部元数据写入组织的存储库中的自定义属性。 > \[!NOTE] 外部自定义属性位于 公开预览 外部，可能会更改。 您可以将来自外部系统（如软件目录或内部开发者门户）的元数据自动写入 GitHub 上的仓库自定义属性。 这使得外部系统成为这些属性的真相来源，并有助于将业务上下文（如所有权、服务层级或符合性状态）保持到存储库中的最新状态。 外部属性可用于与在 GitHub 上管理的自定义属性相同的位置。 若要设置此自动化，您需要安装一个 GitHub App，它会使用来自外部系统的数据调用 GitHub 的外部属性 API 端点。 * 我们的集成合作伙伴 [Port](https://www.port.io/) 已开发外部自定义属性的集成。 有关从端口同步元数据的所有必需步骤，请参阅端口文档中的 [同步端口属性到 GitHub 外部自定义属性](https://docs.port.io/guides/all/sync-port-properties-to-github-external-custom-properties/) 。 GitHub 将来将努力添加更多提供程序。 * 如果你的组织使用**另一个外部系统**，或者你是希望与 GitHub 创建集成的外部系统代表，则需要自行创建 GitHub App 和自动化。 继续阅读本指南。 ## 先决条件 此过程可能需要多个不同的人员。 您将需要： * 由某人在其个人账户下，或在其拥有所有者权限的组织或企业账户下配置 GitHub App * 在 GitHub 上，一个或多个组织所有者需要在每个需要该应用的组织中安装该应用，并且可能还需要为该应用注册一个显示名称 在本指南之外，还需要一个可以创建和运行自动化的人员，并具有对外部系统和运行自动化的服务器的适当访问权限。 ## 1.选择显示名称 组织中的每个外部自定义属性密钥都将以显示名称为前缀。 例如： `port.environment`。 这可用作命名空间，并有助于避免与在 GitHub 或其他外部提供程序上管理的自定义属性发生冲突。 每个显示名称的范围限定为组织中的单个 GitHub App 安装。 在应用向 GitHub 写入自定义属性之前，必须先为该应用安装注册一个显示名称。 这是一次性过程，可由应用本身或组织管理员执行。 应用安装只能注册一次，并且以后无法更改其显示名称。 选择一个名称，以避免冲突，并帮助用户识别外部系统中的自定义属性。 如果要代表第三方系统发布应用，可能需要响应冲突，或者允许用户选择自己的显示名称作为系统上设置流的一部分。 显示名称必须介于 1 到 15 个字符之间，并且仅包含字母和数字。 有关所有要求，请参阅 REST API 的[为外部属性注册应用安装](/zh/rest/orgs/custom-properties#register-an-app-installation-for-external-custom-properties)端点。 ## 2. 注册 GitHub App 标识 GitHub App 将调用 API 来管理外部自定义属性。 它还可以侦听 Webhook GitHub上的事件。 如果要为内部流程创建应用，建议在组织或企业帐户下创建应用。 然后，你将能够根据需要在任意数量的组织中安装应用。 如果你是第三方系统的代表，通常会将该应用发布到 GitHub Marketplace，以便其他公司安装该应用。 有关说明，请参阅“[注册GitHub应用](/zh/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)”。 ### 选择权限 在 **“组织”权限**下， **为存储库权限启用外部自定义属性** ，以便应用可以将数据写入外部属性 API。 所需的访问级别取决于应用需要执行的操作： * 如果应用将使用其安装访问令牌注册自己的显示名称，请选择 **“管理员** ”访问权限。 对于将安装在许多组织上的自助服务应用，这是一个很好的模型。 * 如果应用只需要将自定义属性写入到 GitHub，请选择 **“读取和写入**”访问权限。 组织管理员需要为其安装注册显示名称。 此任务不支持**只读**访问权限。 具有此访问权限级别的应用只能读取其自己的外部自定义属性定义。 如果要订阅 Webhook 事件，可能需要启用其他权限。 有关详细信息，请参阅“[GitHub应用所需的权限](/zh/rest/authentication/permissions-required-for-github-apps#organization-permissions-for-external-custom-properties-for-repositories)”。 ### 选择 Webhook 您可以启用 Webhook，以订阅 GitHub 上会触发从您的外部系统传输数据的事件。 例如： * 当应用安装到组织时（带有 `created` 操作的 `installation` 事件），这可能会触发从外部系统到该组织仓库的首次同步。 默认情况下，此事件会发送给所有 GitHub Apps。 * 在组织中创建新存储库（ `repository` 包含 `created` 操作的事件）时，存储库可以自动填充元数据。 此事件需要具有对 **元数据** 存储库的读取权限。 如果希望自动化只是按计划运行，则不需要 Webhook。 有关详细信息，请参阅“[将 Webhook 与 GitHub 应用配合使用](/zh/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps)”。 ### 选择安装范围 在 **“何处可以安装此GitHub应用”下**，确保应用可以安装在需要应用的所有组织上。 ## 3.创建自动化 > \[!TIP] 有关示例实现，请参阅 [external-custom-properties-sample](https://github.com/github/external-custom-properties-sample) 存储库。 自动化可以按计划运行或侦听事件。 你为应用选择的 Webhook 决定了哪些 GitHub 事件会被转发到你的 Webhook URL。 你可能还想要响应第三方系统上的事件，例如对元数据值的更改。 在自动化中， GitHub App 必须获取安装访问令牌，并使用令牌将数据从外部系统发送到 GitHub外部属性 API 终结点。 请参阅“[验证为 GitHub 应用程序安装](/zh/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)”。 典型的流程是： 1. 在更新属性之前，请使用显示名称**注册该应用安装**，除非组织管理员将注册它。 请参阅 [注册外部自定义属性的应用安装](/zh/rest/orgs/custom-properties#register-an-app-installation-for-external-custom-properties)。 2. **为一个或多个存储库创建或更新属性值**。 See: * [为组织存储库创建或更新外部自定义属性值](/zh/rest/orgs/custom-properties#create-or-update-external-custom-property-values-for-organization-repositories) * [跨组织存储库为属性创建或更新外部自定义属性值](/zh/rest/orgs/custom-properties#create-or-update-external-custom-property-values-for-a-property-across-organization-repositories) 可能还需要： * **删除所有组织存储库中一个属性的所有值**。 请参阅 [删除所有组织存储库中某个属性的所有外部自定义属性值](/zh/rest/orgs/custom-properties#remove-all-external-custom-property-values-for-a-property-across-all-organization-repositories)。 * **获取应用安装的外部自定义属性** 以验证属性定义。 请参阅[获取组织中某个安装的所有外部自定义属性GitHub App](/zh/rest/orgs/custom-properties#get-all-external-custom-properties-for-a-github-app-installation-in-an-organization)。 * **获取已注册的应用安装实例** 以验证注册详细信息。 请参阅 [获取外部自定义属性的已注册应用安装](/zh/rest/orgs/custom-properties#get-registered-app-installations-for-external-custom-properties)。 检查链接的 REST API 参考，了解自动化需要处理的请求大小限制和错误代码。 ## 4.安装应用 在需要它的组织中安装 GitHub App，并授予其所需的权限。 请参阅“[安装自己的GitHub应用](/zh/apps/using-github-apps/installing-your-own-github-app)”。 由于外部自定义属性权限是组织范围的，因此默认情况下，应用将随所有存储库的访问权限一起安装。 除非应用还具有存储库级权限，否则不会看到选择单个存储库的选项。 如果应用未自动注册显示名称或无法授予 **管理员** 访问权限，则组织管理员必须注册安装显示名称。 这可以是组织所有者，也可以是具有 `organization_external_properties_for_repos:admin` 细化权限的人员。 请参阅 [注册外部自定义属性的应用安装](/zh/rest/orgs/custom-properties#register-an-app-installation-for-external-custom-properties)。 ## 5.验证数据传输 自动化运行后，验证外部属性是否与组织的存储库同步。 你应该能够在组织的自定义属性设置或其存储库中看到这些设置。 属性键将以外部显示名称为前缀，属性值将用 图标标示。 请参阅“[管理组织中存储库的自定义属性](/zh/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#viewing-values-for-repositories-in-your-organization)”。 在 [获取仓库的所有自定义属性值](/zh/rest/repos/custom-properties#get-all-custom-property-values-for-a-repository) REST API 端点中，**外部属性值** 也会与传统自定义属性一同返回。 但是， `/schema` 自定义属性的终结点（如“获取组织的所有自定义属性”） **不会** 返回外部属性。 用户将无法编辑这些属性 GitHub，但他们可以在使用传统自定义属性的任何位置使用它们。 ## 6. 维护集成 让自动化持续运行，并保持应用处于已安装状态，以持续从外部系统同步数据。 如果从组织中卸载 GitHub App，其安装名称和显示名称将被取消注册，并且该应用创建的所有外部属性都将被**删除**。 请注意组织中定义的属性数。 每个组织最多可以有 100 个属性定义。 外部和标准自定义属性都计入此限制。