Integrieren benutzerdefinierter Eigenschaften in ein externes System

Verwenden Sie eine GitHub App, um externe Metadaten als benutzerdefinierte Eigenschaften in die Repositorys einer Organisation zu schreiben.

In diesem Artikel

Hinweis

Externe benutzerdefinierte Eigenschaften sind in Öffentliche Vorschau und können geändert werden.

Sie können Metadaten aus einem externen System, etwa einem Softwarekatalog oder einem internen Entwicklerportal, automatisch in benutzerdefinierte Repository-Eigenschaften auf GitHub schreiben. Dies macht das externe System zur Quelle der Wahrheit für diese Eigenschaften und hilft Ihnen, den Geschäftskontext wie Besitz, Dienstebene oder Compliancestatus in Ihren Repositorys auf dem neuesten Stand zu halten. Externe Eigenschaften können an denselben Stellen wie benutzerdefinierte Eigenschaften verwendet werden, die auf GitHub verwaltet werden.

Um diese Automatisierung einzurichten, installieren Sie ein GitHub App, das die API-Endpunkte von GitHub für externe Eigenschaften mit Daten aus dem externen System aufruft.

  • Unser Integrationspartner Port hat eine Integration für externe benutzerdefinierte Eigenschaften entwickelt. Alle erforderlichen Schritte zum Synchronisieren von Metadaten vom Port finden Sie in der Portdokumentation unter Synchronisieren von Porteigenschaften mit GitHub externen benutzerdefinierten Eigenschaften . GitHub wird in Zukunft daran arbeiten, weitere Anbieter hinzuzufügen.
  • Wenn Ihre Organisation ein anderes externes System verwendet, oder wenn Sie Vertreter eines externen Systems sind, das eine Integration mit GitHub erstellen möchte, benötigen Sie Ihre eigene GitHub App und Automatisierung. Lesen Sie diesen Leitfaden weiter.

Prerequisites

Dieser Vorgang erfordert möglicherweise mehrere verschiedene Personen. Sie benötigen Folgendes:

  • Jemand, der das GitHub App entweder mit seinem persönlichen Konto oder mit einem Organisations- oder Unternehmenskonto konfiguriert, dessen Inhaber er ist
  • Ein oder mehrere Organisationsbesitzer auf GitHub müssen die App in jeder Organisation installieren, in der dies erforderlich ist, und gegebenenfalls einen Anzeigenamen für die App registrieren.

Außerhalb des Umfangs dieses Handbuchs benötigen Sie auch jemanden, der die Automatisierung erstellen und ausführen kann, mit entsprechendem Zugriff auf das externe System und den Server, auf dem die Automatisierung ausgeführt wird.

1. Auswählen eines Anzeigenamens

Jedem externen benutzerdefinierten Eigenschaftenschlüssel in Ihrer Organisation wird ein Anzeigename vorangestellt. Beispiel: port.environment. Dies dient als Namespace und hilft dabei, Konflikte mit benutzerdefinierten Eigenschaften zu vermeiden, die auf GitHub oder anderen externen Anbietern verwaltet werden.

Jeder Anzeigename ist auf eine einzelne GitHub App-Installation in der Organisation beschränkt. Bevor eine App benutzerdefinierte Eigenschaften in GitHub schreiben kann, müssen Sie die App-Installation mit einem Anzeigenamen registrieren. Dies ist ein einmaliger Prozess, der von der App selbst oder von einem Organisationsadministrator ausgeführt werden kann. Eine App-Installation kann nur einmal registriert werden, und der Anzeigename kann später nicht mehr geändert werden.

Wählen Sie einen Namen aus, der Konflikte vermeidet und Benutzern hilft, benutzerdefinierte Eigenschaften aus dem externen System zu identifizieren. Wenn Sie eine App im Auftrag eines Drittanbietersystems veröffentlichen, können Sie auf Konflikte reagieren oder Benutzern erlauben, ihren eigenen Anzeigenamen als Teil des Setupablaufs in Ihrem System auszuwählen.

Der Anzeigename muss zwischen 1 und 15 Zeichen bestehen und nur Buchstaben und Zahlen enthalten. Alle Anforderungen finden Sie im Endpunkt Registrierung einer App-Installation für externe Eigenschaften der REST-API.

2. Registrieren eines GitHub App

Dies GitHub App ist die Identität, die die APIs aufruft, um externe benutzerdefinierte Eigenschaften zu verwalten. Es kann auch Webhooks für Ereignisse auf GitHub empfangen.

Wenn Sie eine App für einen internen Prozess erstellen, empfehlen wir, die App unter einem Organisations- oder Unternehmenskonto zu erstellen. Anschließend können Sie die App in beliebig vielen Organisationen installieren. Wenn Sie ein Vertreter eines Drittsystems sind, werden Sie die App wahrscheinlich auf GitHub Marketplace veröffentlichen, damit andere Unternehmen sie installieren können.

Anweisungen findest du unter Registrieren einer GitHub-App.

Auswählen von Berechtigungen

Aktivieren Sie unter "Organisationsberechtigungen" die Berechtigung "Externe benutzerdefinierte Eigenschaften" für Repositorys , sodass die App Daten in die API für externe Eigenschaften schreiben kann. Die erforderliche Zugriffsstufe hängt davon ab, was die App tun muss:

  • Wählen Sie den Administratorzugriff aus, wenn die App ihren eigenen Anzeigenamen mithilfe des Installationszugriffstokens registriert. Dies ist ein gutes Modell für eine Self-Service-App, die in vielen Organisationen installiert wird.
  • Wählen Sie Lese- und Schreibzugriff aus, wenn die App nur benutzerdefinierte Eigenschaften in GitHub schreiben muss. Ein Organisationsadministrator muss den Anzeigenamen für seine Installation registrieren.

Nur-Lesezugriff ist keine Option für diese Aufgabe. Eine App mit dieser Zugriffsebene kann nur eigene definitionen für benutzerdefinierte Eigenschaften lesen.

Wenn Sie Webhook-Ereignisse abonnieren möchten, müssen Sie möglicherweise zusätzliche Berechtigungen aktivieren.

Weitere Informationen findest du unter Erforderliche Berechtigungen für GitHub Apps.

Auswählen von Webhooks

Sie können Webhooks aktivieren, um Ereignisse auf GitHub zu abonnieren, die eine Datenübertragung aus Ihrem externen System auslösen.

Beispiel:

  • Wenn eine App in einer Organisation installiert ist (das installation Ereignis mit der created Aktion), kann dies die erste Synchronisierung vom externen System mit den Repositorys der Organisation auslösen. Dieses Ereignis wird standardmäßig an alle GitHub Apps gesendet.
  • Wenn ein neues Repository in der Organisation erstellt wird (das repository Ereignis mit der created Aktion), kann das Repository automatisch mit Metadaten aufgefüllt werden. Dieses Ereignis erfordert Lesezugriff auf die Repository-Berechtigung Metadaten.

Webhooks sind nicht erforderlich, wenn Sie es vorziehen, die Automatisierung einfach nach Zeitplan auszuführen.

Weitere Informationen findest du unter Verwenden von Webhooks mit GitHub Apps.

Auswählen des Installationsumfangs

Vergewissern Sie sich unter Wo kann diese GitHub-App installiert werden?, dass Ihre App in allen Organisationen installiert werden kann, in denen sie benötigt wird.

3. Erstellen der Automatisierung

Tipp

Eine Beispielimplementierung finden Sie im Repository für externe benutzerdefinierte Eigenschaften .

Die Automatisierung kann nach einem Zeitplan ausgeführt werden oder auf Ereignisse warten. Der für die App ausgewählte Webhook bestimmt, welche GitHub Ereignisse an Ihre Webhook-URL weitergeleitet werden. Möglicherweise möchten Sie auch auf Ereignisse im Drittanbietersystem reagieren, z. B. Änderungen an Metadatenwerten.

In der Automatisierung muss GitHub App ein Installationszugriffstoken abrufen und das Token verwenden, um Daten aus dem externen System an die API-Endpunkte für externe Eigenschaften von GitHub zu senden. Siehe Authentifizieren als GitHub App-Installation.

Siehe die folgenden Endpunkte der REST-API. Sie finden Informationen zu Grenzwerten für die Anforderungsgröße und zu Fehlercodes, die Ihre Automatisierung berücksichtigen sollte.

4. Installieren der App

Installieren Sie GitHub App in den Organisationen, in denen sie erforderlich ist, und autorisieren Sie die erforderlichen Berechtigungen. Siehe Installieren Ihrer eigenen GitHub App.

Da die Berechtigung für externe benutzerdefinierte Eigenschaften organisationsweit gilt, wird die App standardmäßig mit Zugriff auf alle Repositorys installiert. Es wird keine Option zum Auswählen einzelner Repositorys angezeigt, es sei denn, die App verfügt auch über Berechtigungen auf Repositoryebene.

Wenn die App keinen Anzeigenamen automatisch registriert oder Sie den Administratorzugriff nicht autorisieren können, muss ein Organisationsadministrator den Anzeigenamen für die Installation registrieren. Dies kann ein Organisationsbesitzer oder eine Person mit der organization_external_properties_for_repos:admin feinkörnigen Berechtigung sein. Siehe Registrieren einer App-Installation für externe benutzerdefinierte Eigenschaften.

5. Überprüfen der Datenübertragung

Nachdem die Automatisierung ausgeführt wurde, überprüfen Sie, ob externe Eigenschaften mit den Repositorys der Organisation synchronisiert werden. Sie sollten diese in den benutzerdefinierten Eigenschafteneinstellungen für Ihre Organisation oder deren Repositorys anzeigen können. Die Eigenschaftenschlüssel werden dem externen Anzeigenamen vorangestellt, und die Werte werden mit einem Symbol gekennzeichnet. Siehe Verwalten von benutzerdefinierten Eigenschaften für Repositorys in Ihrer Organisation.

Externe Eigenschaftswerte werden auch zusammen mit herkömmlichen benutzerdefinierten Eigenschaften im Get all custom property values for a repository REST API endpoint zurückgegeben. /schema Endpunkte für benutzerdefinierte Eigenschaften, z. B. "Abrufen aller benutzerdefinierten Eigenschaften für eine Organisation", geben jedoch keine externen Eigenschaften zurück.

Benutzer können diese Eigenschaften GitHubnicht bearbeiten, aber sie können sie überall verwenden, wo sie herkömmliche benutzerdefinierte Eigenschaften verwenden.

6. Beibehalten der Integration

Halten Sie die Automatisierung und die App installiert, um die Synchronisierung von Daten aus dem externen System beizubehalten. Wenn Sie GitHub App aus einer Organisation deinstallieren, werden der Installations- und der Anzeigename deregistriert, und alle externen Eigenschaften, die die App erstellt hat, werden entfernt.

Achten Sie auf die Anzahl der in der Organisation definierten Eigenschaften. Jede Organisation kann bis zu 100 Eigenschaftsdefinitionen aufweisen. Sowohl externe als auch standardmäßige benutzerdefinierte Eigenschaften zählen zu diesem Grenzwert.