Registrieren einer GitHub App mit URL-Parametern

Informationen zu URL-Parametern für die Registrierung GitHub Apps

Mithilfe von URL-Parametern können Sie die Konfigurationseinstellungen einer neuen GitHub App Registrierung vorwählen und einen benutzerdefinierten Link für andere Personen freigeben. Der Link führt Personen zu einer GitHub App Registrierungsseite, auf der die App-Einstellungen entsprechend den URL-Parametern, die Sie in die URL aufgenommen haben, vorab ausgefüllt werden.

Dieser Ansatz ist nützlich für Integratoren, bei denen Kunden eine App mit bestimmten Vorgaben in ihrem persönlichen Konto oder in ihrer Organisation einrichten sollen, oder für Kunden, die GitHub Enterprise Server verwenden und keine Apps aus dem GitHub Marketplace installieren können.

Alternativ können Sie ein GitHub App Manifest erstellen. Weitere Informationen finden Sie unter Registrieren einer GitHub App aus einem Manifest.

Erstellen einer benutzerdefinierten Konfigurations-URL mit Abfrageparametern

Um eine benutzerdefinierte Konfigurations-URL für ein GitHub App in einem persönlichen Konto oder Organisationskonto zu erstellen, fügen Sie Abfrageparameter nach den folgenden Basis-URLs hinzu.

• Wenn eine App in einem persönlichen Konto registriert werden soll, füge URL-Parameter an die folgende URL an: https://github.com/settings/apps/new.
• Wenn eine App in einem Organisationskonto registriert werden soll, füge URL-Parameter an die folgende URL an: https://github.com/organizations/ORGANIZATION/settings/apps/new. Ersetze dabei ORGANIZATION durch den Namen der Organisation, in der der Kunde bzw. die Kundin die App registrieren soll.

Auf der App-Registrierungsseite kann die Person, die die App registriert, die vorab ausgewählten Werte bearbeiten, bevor sie die App übermittelt. Wenn du für erforderliche Werte (wie name) keine Parameter in der URL-Abfragezeichenfolge angibst, muss die Person, die die App registriert, einen Wert eingeben, damit sie die App registrieren kann.

Mit der folgenden URL wird beispielsweise eine neue öffentliche App mit dem Namen octocat-github-app in einem persönlichen Konto registriert. Mithilfe von Abfrageparametern werden über die URL eine Beschreibung und eine Rückruf-URL vorkonfiguriert. Außerdem werden Lese- und Schreibberechtigungen für checks ausgewählt, Webhooks mithilfe des Parameters webhook_active aktiviert, die Webhookereignisse check_run und check_suite abonniert und die Option zum Anfordern der Benutzerautorisierung (Open Authorization, OAuth) während der Installation ausgewählt:

https://github.com/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&webhook_active=true&events[]=check_run&events[]=check_suite

GitHub App Konfigurationsparameter

Sie können die folgenden Abfrageparameter verwenden, um eine bestimmte Konfiguration für die GitHub App Registrierung auszuwählen. Wenn du beispielsweise die App „octocat-github-app“ nennen möchtest, enthält deine Abfragezeichenfolge die Angabe name=octocat-github-app.

Parametername	Typ	BESCHREIBUNG
name	string	Der Name des GitHub App. Gib deiner App einen klaren und kurzen Namen. Ihre App kann nicht denselben Namen wie ein vorhandener GitHub Benutzer haben, es sei denn, sie ist Ihr eigener Benutzer- oder Organisationsname. Eine Slugversion des Namens deiner App wird in der Benutzeroberfläche angezeigt, wenn deine Integration eine Aktion ausführt.
description	string	Eine Beschreibung des GitHub App.
url	string	Die vollständige URL Ihrer GitHub AppWebsite-Homepage.
callback_urls	array of strings	Vollständige URL, an die Benutzer*innen nach der Autorisierung einer Installation umgeleitet werden. Du kannst bis zu zehn Rückruf-URLs bereitstellen. Diese URLs werden verwendet, wenn deine App ein Benutzerzugriffstoken generieren muss. Beispiel: callback_urls[]=https://example.com&callback_urls[]=https://example-2.com. Weitere Informationen finden Sie unter Informationen zur Rückruf-URL für die Benutzerautorisierung.
request_oauth_on_install	boolean	Wenn deine App Benutzer mit dem OAuth-Flow autorisiert, kannst du diese Option auf true festlegen, damit Personen die App während der Installation autorisieren können, was einen Schritt einspart. Wenn du diese Option auswählst, ist die setup_url nicht mehr verfügbar, und Benutzer werden nach der Installation der App an deine callback_url weitergeleitet.
setup_url	string	Die vollständige URL, zu der umgeleitet werden soll, nachdem jemand die GitHub App App installiert hat, wenn nach der Installation zusätzliches Setup erforderlich ist. Weitere Informationen finden Sie unter Informationen zur Setup-URL.
setup_on_update	boolean	Lege diesen Parameter auf true fest, um Personen an die Setup-URL umzuleiten, wenn Installationen aktualisiert wurden, z. B. nach dem Hinzufügen oder Entfernen von Repositorys.
public	boolean	Legen Sie fest, true wann Ihre GitHub App App für die Öffentlichkeit verfügbar ist oder false wenn sie nur für den Besitzer der App zugänglich ist. Dieser Parameter gilt nicht für Apps im Besitz von Unternehmen.
webhook_active	boolean	Lege den Wert für diesen Parameter auf true fest, um den Webhook zu aktivieren. Der Webhook ist standardmäßig deaktiviert.
webhook_url	string	Die vollständige URL, an die du die Nutzdaten von Webhook-Ereignissen senden möchtest.
events	array of strings	Webhook-Ereignisse. Einige Webhook-Ereignisse erfordern read oder write Berechtigungen für eine Ressource, bevor Sie das Ereignis beim Registrieren eines neuen GitHub AppEreignisses auswählen können. Weitere Informationen finden Sie im GitHub App Abschnitt "Webhook-Ereignisse ". Du kannst mehrere Ereignisse in einer Abfragezeichenfolge auswählen. Beispiel: events[]=public&events[]=label.
single_file_name	string	Dies ist eine stark begrenzte Berechtigung, mit der die App auf eine einzelne Datei in einem beliebigen Repository zugreifen kann. Wenn Sie die single_file Berechtigung auf read oder writefestlegen, stellt dieses Feld den Pfad zu der einzelnen Datei bereit, die Sie GitHub App verwalten möchten. Wenn Sie mehrere Dateien verwalten müssen, siehe single_file_paths weiter unten.
single_file_paths	array of strings	Dadurch kann die App auf bis zu zehn angegebene Dateien in einem Repository zugreifen. Wenn Sie die single_file Berechtigung auf read oder writefestlegen, kann dieses Array die Pfade für bis zu zehn Dateien speichern, die Von Ihnen GitHub App verwaltet werden. Diese Dateien erhalten alle die gleiche Berechtigung, die von single_file festgelegt ist, und verfügen nicht über separate individuelle Berechtigungen. Wenn zwei oder mehr Dateien konfiguriert sind, gibt die API multiple_single_files=true zurück, andernfalls multiple_single_files=false.

GitHub App Berechtigungen

Sie können Abfrageparameter verwenden, um die Berechtigungen für die GitHub App Registrierung auszuwählen. Verwende für den URL-Abfrageparameter den Berechtigungsnamen als Abfrageparameternamen, und lege den Abfragewert auf einen der möglichen Werte für die Berechtigung fest.

Wenn du beispielsweise Lese- und Schreibberechtigungen in der Benutzeroberfläche für contents auswählen möchtest, enthält deine Abfragezeichenfolge die Angabe contents=write. Damit nur Leseberechtigungen in der Benutzeroberfläche für blocking gewährt werden, muss deine Abfragezeichenfolge die Angabe blocking=read enthalten. Um in der Benutzeroberfläche für checks „Kein Zugriff“ auszuwählen, würde Ihre Abfragezeichenfolge die checks-Berechtigung nicht enthalten.

Weitere Informationen zu Berechtigungen und GitHub Apps finden Sie unter Auswählen von Berechtigungen für eine GitHub App. Eine Liste der verfügbaren Berechtigungen und deren parametrisierte Namen findest du unter Verwalten deiner persönlichen Zugriffstoken.

GitHub App Webhook-Ereignisse

Sie können Abfrageparameter verwenden, um den GitHub App Webhook zu aktivieren, eine Webhook-URL festzulegen und die App zu abonnieren, um Webhook-Nutzlasten für bestimmte Ereignisse zu empfangen.

Verwenden Sie zum Aktivieren des GitHub App Webhooks webhook_active=true in Ihrer Abfragezeichenfolge. Verwende webhook_url in deiner Abfragezeichenfolge, um eine vollständige URL anzugeben, an die Ereignisnutzdaten zu dem Webhook gesendet werden sollen. Um die App für bestimmte Webhook-Ereignisse zu abonnieren, verwende events[] als Abfrageparameternamen und setze den Abfragewert auf den Namen des Webhook-Ereignisses. Weitere Informationen zu den möglichen Webhook-Ereignissen und den GitHub App zum Abonnieren der einzelnen Ereignisse erforderlichen Berechtigungen finden Sie unter Webhook-Ereignisse und Webhook-Nutzlasten.

Um z. B. ein GitHub App zu abonnieren, um Webhook-Payloads für Aktivitäten im Zusammenhang mit Commit-Kommentaren zu empfangen, würde die Abfragezeichenfolge &webhook_active=true&webhook_url=https://example.com&events[]=commit_comment enthalten. Beachten Sie, dass GitHub App für das commit_comment-Webhook-Ereignis mindestens Lesezugriff auf die Repository-Berechtigung „Contents“ haben muss. Daher sollte deine Abfragezeichenfolge auch einen Parameter enthalten, mit dem die Berechtigung contents auf read oder write festgelegt wird. Weitere Informationen finden Sie unter GitHub App-Berechtigungen.

Abfrageparameter können nicht verwendet werden, um den Wert eines Webhookgeheimnisses festzulegen. Wenn eine App einen geheimen Schlüssel zum Sichern des Webhooks benötigt, muss der Wert des geheimen Schlüssels von der Person, die die App registriert, in der GitHub Benutzeroberfläche festgelegt werden.

Weitere Informationen zu Webhooks und GitHub Apps finden Sie in Verwenden von Webhooks mit GitHub Apps.