Интеграция пользовательских свойств с внешней системой

GitHub App Используйте для записи внешних метаданных в настраиваемые свойства в репозиториях организации.

В этой статье

Примечание.

Внешние настраиваемые свойства находятся и подвергаются Публичный предварительный просмотр изменению.

Вы можете автоматически записывать метаданные из внешней системы, например каталог программного обеспечения или внутренний портал разработчика, в репозиторий пользовательских свойств.GitHub Это делает внешнюю систему источником истины для этих свойств и помогает поддерживать бизнес-контекст, например владение, уровень служб или состояние соответствия требованиям в репозиториях. Внешние свойства можно использовать в том же месте, что и пользовательские свойства, управляемые GitHubв .

Чтобы настроить эту автоматизацию, необходимо установить конечную GitHub AppGitHubточку API для внешних свойств с данными из внешней системы.

  • Порт партнера по интеграции разработал интеграцию для внешних настраиваемых свойств. Все необходимые действия для синхронизации метаданных из порта см. в разделе "Свойства порта синхронизации" с 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 для управления внешними пользовательскими свойствами. Он также может прослушивать веб-перехватчики для событий GitHub.

Если вы создаете приложение для внутреннего процесса, рекомендуется создать приложение в организации или корпоративной учетной записи. Затем вы сможете установить приложение в столько организаций, сколько вам нужно. Если вы являетесь представителем из сторонней системы, скорее всего, опубликуете приложение GitHub Marketplace , чтобы другие компании могли установить его.

Инструкции см. в разделе Регистрация приложения GitHub.

Выбор разрешений

В разделе "Разрешения организации" включите внешние настраиваемые свойства для разрешений репозиториев , чтобы приложение может записывать данные в API внешних свойств. Уровень доступа зависит от того, что нужно сделать приложению:

  • Выберите доступ администратора , если приложение зарегистрирует собственное отображаемое имя с помощью маркера доступа к установке. Это хорошая модель для самостоятельного приложения, которое будет установлено во многих организациях.
  • Выберите доступ на чтение и запись , если приложению требуется только запись пользовательских свойств GitHub. Администратор организации должен зарегистрировать отображаемое имя для их установки.

Доступ только для чтения не является вариантом для этой задачи. Приложение с таким уровнем доступа сможет только читать собственные определения внешних настраиваемых свойств.

Если вы хотите подписаться на события веб-перехватчика, может потребоваться включить дополнительные разрешения.

Дополнительные сведения см. в разделе Для приложений GitHub требуются права.

Выбор веб-перехватчиков

Вы можете включить веб-перехватчики для подписки на события GitHub , которые должны активировать передачу данных из внешней системы.

Рассмотрим пример.

  • Если приложение установлено в организации ( installation событие с created действием), это может активировать первую синхронизацию из внешней системы с репозиториями организации. Это событие отправляется всем GitHub Apps по умолчанию.
  • При создании нового репозитория в организации ( repository событие с created действием) репозиторий может автоматически заполняться метаданными. Для этого события требуется доступ на чтение к разрешению репозитория метаданных .

Веб-перехватчики не требуются, если вы предпочитаете автоматизацию просто запускать по расписанию.

Дополнительные сведения см. в разделе Использование вебхуков с приложениями GitHub.

Выбор области установки

В разделе "Где можно установить приложение GitHub?", убедитесь, что ваше приложение можно установить во всех организациях, где это необходимо.

3. Создание автоматизации

Совет

Пример реализации см. в репозитории external-custom-properties-sample .

Автоматизация может выполняться по расписанию или прослушивать события. Веб-перехватчик, выбранный для приложения, определяет, какие GitHub события перенаправляются в URL-адрес веб-перехватчика. Также может потребоваться ответить на события в сторонней системе, например изменения значений метаданных.

В службе автоматизации GitHub App необходимо получить маркер доступа к установке и использовать маркер для отправки данных из внешней системы в GitHubконечные точки API внешних свойств. См . раздел AUTOTITLE.

Ознакомьтесь со следующими конечными точками REST API. Вы найдете сведения об ограничениях размера запроса и кодах ошибок, которые должна учитывать служба автоматизации.

4. Установка приложения

GitHub App Установите его в организациях, где это необходимо, авторизации необходимых разрешений. См . раздел AUTOTITLE.

Так как разрешение на внешние пользовательские свойства является областью действия организации, приложение будет установлено с доступом ко всем репозиториям по умолчанию. Вы не увидите возможность выбора отдельных репозиториев, если приложение также не имеет разрешений на уровне репозитория.

Если приложение не регистрирует отображаемое имя или не удается авторизовать доступ администратора , администратор организации должен зарегистрировать отображаемое имя для установки. Это может быть владелец организации или кто-то с organization_external_properties_for_repos:admin точным разрешением. См . раздел "Регистрация установки приложения" для внешних настраиваемых свойств.

5. Проверка передачи данных

После запуска службы автоматизации убедитесь, что внешние свойства синхронизируются с репозиториями организации. Их можно увидеть в параметрах пользовательского свойства для вашей организации или его репозиториев. Ключи свойств будут префиксированы внешним отображаемым именем, а значения будут указаны значком . См . раздел AUTOTITLE.

Значения внешних свойств также возвращаются вместе с традиционными настраиваемыми свойствами в get all custom property values for a репозиторий REST API endpoint. Однако конечные точки для пользовательских свойств, например "Получить все настраиваемые свойства для организации", /schemaне возвращают внешние свойства.

Пользователи не смогут изменять эти свойства GitHub, но они смогут использовать их в любом месте, где они используют традиционные настраиваемые свойства.

6. Обслуживание интеграции

Продолжайте работу службы автоматизации и устанавливайте приложение, чтобы сохранить синхронизацию данных из внешней системы. При удалении GitHub App организации будет удалена регистрация установки и отображаемого имени, а все внешние свойства, созданные приложением, будут удалены.

Обратите внимание на количество свойств, определенных в организации. Каждая организация может содержать до 100 определений свойств. Как внешние, так и стандартные настраиваемые свойства учитываются в этом пределе.