# 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. > \[!NOTE] 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](https://www.port.io/) 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](https://docs.port.io/guides/all/sync-port-properties-to-github-external-custom-properties/) 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](/fr/rest/orgs/custom-properties#register-an-app-installation-for-external-custom-properties). ## 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](/fr/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). ### 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](/fr/rest/authentication/permissions-required-for-github-apps#organization-permissions-for-external-custom-properties-for-repositories) ». ### 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](/fr/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-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 > \[!TIP] Pour obtenir un exemple d’implémentation, consultez le référentiel [external-custom-properties-sample](https://github.com/github/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](/fr/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation) ». 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. * [Inscrire une installation d’application pour les propriétés personnalisées externes](/fr/rest/orgs/custom-properties#register-an-app-installation-for-external-custom-properties) (l’application doit inscrire son nom complet avant de pouvoir mettre à jour les propriétés, sauf si un administrateur d’organisation est censé effectuer cette opération) * [Récupérer les installations d’application enregistrées pour les propriétés personnalisées externes](/fr/rest/orgs/custom-properties#get-registered-app-installations-for-external-custom-properties) * [Obtenir toutes les propriétés personnalisées externes d’une GitHub App installation dans une organisation](/fr/rest/orgs/custom-properties#get-all-external-custom-properties-for-a-github-app-installation-in-an-organization) * [Créer ou mettre à jour des valeurs de propriétés personnalisées externes pour les référentiels d’organisation](/fr/rest/orgs/custom-properties#create-or-update-external-custom-property-values-for-organization-repositories) * [Créer ou mettre à jour des valeurs de propriétés personnalisées externes pour une propriété entre les référentiels d’organisation](/fr/rest/orgs/custom-properties#create-or-update-external-custom-property-values-for-a-property-across-organization-repositories) * [Supprimer toutes les valeurs de propriété personnalisées externes pour une propriété dans tous les référentiels d’organisation](/fr/rest/orgs/custom-properties#remove-all-external-custom-property-values-for-a-property-across-all-organization-repositories) ## 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](/fr/apps/using-github-apps/installing-your-own-github-app) ». É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](/fr/rest/orgs/custom-properties#register-an-app-installation-for-external-custom-properties). ## 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](/fr/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#viewing-values-for-repositories-in-your-organization) ». 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](/fr/rest/repos/custom-properties#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.