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