Intégration de propriétés personnalisées à un système externe

Utilisez un GitHub App pour écrire des métadonnées externes dans des propriétés personnalisées dans les référentiels d’une organisation.

Dans cet article

Remarque

Les propriétés personnalisées externes sont dans préversion publique et sujettes à modification.

Vous pouvez écrire automatiquement des métadonnées à partir d’un système externe, tel qu’un catalogue de logiciels ou un portail de développement interne, pour référentielr des propriétés personnalisées sur GitHub. Cela rend le système externe la source de vérité pour ces propriétés et vous aide à conserver le contexte métier, tel que la propriété, le niveau de service ou l’état de conformité à jour dans vos référentiels. Les propriétés externes peuvent être utilisées dans les mêmes emplacements que les propriétés personnalisées qui sont gérées sur GitHub.

Pour configurer cette automatisation, vous allez installer un GitHub App qui appelle les points de terminaison de l’API de GitHub pour les propriétés externes à l’aide de données provenant du système externe.

  • Notre partenaire d’intégration Port a développé une intégration pour les propriétés personnalisées externes. Pour connaître toutes les étapes requises pour synchroniser les métadonnées depuis Port, consultez Synchroniser les propriétés de Port vers GitHub des propriétés personnalisées externes dans la documentation de Port. GitHub travaillera à ajouter d’autres fournisseurs à l’avenir.
  • Si votre organisation utilise un autre système externe ou si vous êtes un représentant d’un système externe qui souhaite créer une intégration avec GitHub, vous devez créer votre propre GitHub App système et votre automatisation. Poursuivez la lecture de ce guide.

Prerequisites

Ce processus peut nécessiter plusieurs personnes différentes. Vous aurez besoin des éléments suivants :

  • Une personne chargée de configurer le GitHub App, sous son compte personnel ou sous le compte d’une organisation ou d’une entreprise dont elle est propriétaire
  • Un ou plusieurs propriétaires d’organisation sur GitHub, pour installer l’application dans chaque organisation où elle est nécessaire, et éventuellement enregistrer un nom d’affichage pour l’application

En dehors de l’étendue de ce guide, vous aurez également besoin d’une personne qui peut créer et exécuter l’automatisation, avec un accès approprié au système externe et au serveur sur lequel l’automatisation s’exécutera.

1. Choisir un nom d’affichage

Chaque clé de propriété personnalisée externe de votre organisation sera précédée d’un nom d’affichage. Par exemple : port.environment. Cela agit en tant qu’espace de noms et permet d’éviter les conflits avec les propriétés personnalisées gérées sur GitHub ou d’autres fournisseurs externes.

Chaque nom d’affichage est associé à une seule installation GitHub App dans l’organisation. Avant qu’une application puisse écrire des propriétés personnalisées dans GitHub, vous devez enregistrer l’installation de l’application avec un nom d’affichage. Il s’agit d’un processus unique qui peut être effectué par l’application elle-même ou par un administrateur d’organisation. Une installation d’application ne peut être enregistrée qu’une seule fois et son nom d’affichage ne peut pas être modifié ultérieurement.

Choisissez un nom qui évitera les conflits et aidera les utilisateurs à identifier les propriétés personnalisées à partir du système externe. Si vous publiez une application pour le compte d’un système tiers, vous pouvez répondre aux conflits ou autoriser les utilisateurs à choisir leur propre nom complet dans le cadre du flux d’installation sur votre système.

Le nom d’affichage doit comporter entre 1 et 15 caractères et contenir uniquement des lettres et des chiffres. Pour tous les prérequis, consultez le point de terminaison de l’API REST Enregistrer une installation d’application pour des propriétés externes.

2. Inscrire un GitHub App

Le GitHub App est l’identité qui appellera les API pour gérer les propriétés personnalisées externes. Il peut également écouter les webhooks pour les événements sur GitHub.

Si vous créez une application pour un processus interne, nous vous recommandons de créer l’application sous un compte d’entreprise ou d’organisation. Ensuite, vous serez en mesure d’installer l’application dans autant d’organisations que nécessaire. Si vous êtes un représentant d’un système tiers, vous publierez probablement l’application pour GitHub Marketplace que d’autres entreprises puissent l’installer.

Pour les instructions, consultez Inscription d’une application GitHub.

Sélection des autorisations

Sous Autorisations de l’organisation, activez les propriétés personnalisées externes pour l’autorisation de référentiels afin que l’application puisse écrire des données dans l’API de propriétés externes. Le niveau d’accès requis dépend de ce que l’application doit faire :

  • Choisissez l’accès Admin si l’application enregistrera son propre nom d’affichage à l’aide de son jeton d’accès à l’installation. Il s’agit d’un bon modèle pour une application libre-service qui sera installée sur de nombreuses organisations.
  • Choisissez l’accès en lecture et en écriture si l’application doit uniquement écrire des propriétés personnalisées dans GitHub. Un administrateur de l’organisation devra enregistrer le nom d’affichage de son installation.

L’accès en lecture seule n’est pas une option pour cette tâche. Une application avec ce niveau d’accès ne pourra lire que ses propres définitions de propriétés personnalisées externes.

Si vous souhaitez vous abonner à des événements de webhook, vous devrez peut-être activer des autorisations supplémentaires.

Pour plus d’informations, consultez « Autorisations requises pour les applications GitHub ».

Sélection des webhooks

Vous pouvez activer les webhooks pour vous abonner à des événements sur GitHub qui doivent déclencher le transfert de données depuis votre système externe.

Par exemple:

  • Lorsqu’une application est installée sur une organisation (l’événement installation avec l’action created ), elle peut déclencher la première synchronisation à partir du système externe vers les dépôts de l’organisation. Cet événement est envoyé à tous GitHub Apps par défaut.
  • Lorsqu’un nouveau référentiel est créé dans l’organisation (l’événement repository avec l’action created ), le référentiel peut automatiquement être rempli avec des métadonnées. Cet événement nécessite un accès en lecture à l’autorisation du référentiel de métadonnées .

Les webhooks ne sont pas obligatoires si vous préférez que l’automatisation s’exécute simplement selon une planification.

Pour plus d’informations, consultez « Utilisation de webhooks avec GitHub Apps ».

Sélection de l’étendue d’installation

Sous Où cette application GitHub peut-elle être installée ?, vérifiez que votre application peut être installée sur toutes les organisations où elle est requise.

3. Créer l’automatisation

Conseil

Pour obtenir un exemple d’implémentation, consultez le référentiel external-custom-properties-sample .

L’automatisation peut s’exécuter selon une planification ou écouter des événements. Le webhook que vous avez sélectionné pour l’application détermine les GitHub événements qui sont transférés à votre URL de webhook. Vous pouvez également répondre aux événements sur le système tiers, tels que les modifications apportées aux valeurs de métadonnées.

Dans l’automatisation, le GitHub App doit obtenir un jeton d’accès à l’installation et l’utiliser pour envoyer des données depuis le système externe vers les points de terminaison de l’API des propriétés externes de GitHub. Consultez « Installation de l’authentification en tant qu’application GitHub ».

Consultez les points de terminaison suivants de l’API REST. Vous trouverez des informations sur les limites de taille des demandes et les codes d’erreur pour lesquels votre automatisation doit tenir compte.

4. Installer l’application

Installez GitHub App sur les organisations où cela est nécessaire, en lui accordant les autorisations nécessaires. Consultez « Installation de votre propre application GitHub ».

Étant donné que l’autorisation des propriétés personnalisées externes est limitée à l’organisation, l’application est installée avec accès à tous les référentiels par défaut. Vous ne verrez pas d’option permettant de sélectionner des référentiels individuels, sauf si l’application dispose également d’autorisations au niveau du référentiel.

Si l’application n’enregistre pas automatiquement un nom d’affichage ou si vous ne pouvez pas autoriser l’accès Admin, un administrateur de l’organisation doit enregistrer le nom d’affichage pour l’installation. Il peut s’agir d’un propriétaire d’organisation ou d’une personne disposant de l’autorisation organization_external_properties_for_repos:admin affinée. Consultez Enregistrer une installation d’application pour des propriétés personnalisées externes.

5. Valider le transfert de données

Une fois l’automatisation exécutée, vérifiez que les propriétés externes sont synchronisées avec les dépôts de l’organisation. Vous devriez être en mesure de les voir dans les paramètres de propriété personnalisés de votre organisation ou de ses dépôts. Les clés de propriété sont précédées du nom d’affichage externe, et les valeurs sont indiquées avec une icône. Consultez « Gestion des propriétés personnalisées pour les référentiels de votre organisation ».

Les valeurs de propriété externe sont également renvoyées avec les propriétés personnalisées traditionnelles dans le point de terminaison de l’API REST Get all custom property values for a repository. Toutefois, /schema les points de terminaison pour les propriétés personnalisées, tels que « Obtenir toutes les propriétés personnalisées d’une organisation », ne retournent pas de propriétés externes.

Les utilisateurs ne pourront pas modifier ces propriétés, GitHubmais ils pourront les utiliser partout où ils utilisent des propriétés personnalisées traditionnelles.

6. Maintenir l’intégration

Conservez l’automatisation en cours d’exécution et l’application installée pour conserver la synchronisation des données à partir du système externe. Si vous désinstallez GitHub App d’une organisation, le nom d’installation et le nom d’affichage seront désenregistrés, et toutes les propriétés externes créées par l’application seront supprimées.

Faites attention au nombre de propriétés définies dans l’organisation. Chaque organisation peut avoir jusqu’à 100 définitions de propriétés. Les propriétés personnalisées externes et les propriétés personnalisées standard sont prises en compte dans cette limite.