Informationen zu URL-Parametern zum Registrieren von GitHub Apps
Du kannst URL-Parameter verwenden, um die Konfigurationseinstellungen für eine neue GitHub App-Registrierung vorab auszuwählen und einen benutzerdefinierten Link mit anderen Personen zu teilen. Über diesen Link gelangen diese Personen zu einer GitHub App-Registrierungsseite, auf der die App-Einstellungen basierend auf den von dir in der URL angegebenen URL-Parametern vorausgefüllt sind.
Dieser Ansatz ist nützlich für Integratorinnen, die möchten, dass Kundinnen in ihrem persönlichen Konto oder in ihrer Organisation eine App mit bestimmten Spezifikationen einrichten, oder für Kund*innen, die GitHub Enterprise Server verwenden und keine Apps über den GitHub Marketplace installieren können.
Alternativ kannst du ein GitHub App-Manifest erstellen. Weitere Informationen findest du unter Registrieren einer GitHub-App über ein Manifest.
Erstellen einer benutzerdefinierten Konfigurations-URL mit Abfrageparametern
Wenn du eine benutzerdefinierte Konfigurations-URL für eine GitHub App in einem persönlichen Konto oder Organisationskonto erstellen möchtest, füge Abfrageparameter an die folgenden Basis-URLs an.
- Wenn eine App in einem persönlichen Konto registriert werden soll, füge URL-Parameter an die folgende URL an:
http(s)://HOSTNAME/settings/apps/new. - Wenn eine App in einem Organisationskonto registriert werden soll, füge URL-Parameter an die folgende URL an:
http(s)://HOSTNAME/organizations/ORGANIZATION/settings/apps/new. Ersetze dabeiORGANIZATIONdurch 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:
http(s)://HOSTNAME/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
Du kannst 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 | Type | BESCHREIBUNG |
|---|---|---|
name | string | Der Name der GitHub App. Gib deiner App einen klaren und kurzen Namen. Ihre App darf nicht denselben Namen wie ein bestehender GitHub Benutzer haben, außer es 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 der GitHub App. |
url | string | Die vollständige URL der Startseite der Website deiner GitHub App. |
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 findest du 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 zum Umleiten nach der Installation der GitHub App, wenn die App nach der Installation ein zusätzliches Setup erfordert. Weitere Informationen findest du 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 | Lege diesen Parameter auf true fest, wenn deine GitHub App öffentlich verfügbar sein soll, oder auf false, wenn nur der Besitzer der App darauf zugreifen darf. 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 Webhook-Ereignisnutzdaten senden möchtest. |
events | array of strings | Webhook-Ereignisse. Einige Webhook-Ereignisse erfordern read- oder write-Berechtigungen für eine Ressource, bevor du das Ereignis auswählen kannst, wenn du eine neue GitHub App registrierst. Weitere Informationen findest du im Abschnitt GitHub App-Webhookereignisse. 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 du die single_file-Berechtigung auf read oder write festlegst, stellt dieses Feld den Pfad zur einzelnen Datei bereit, die deine GitHub App verwaltet. 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 du die single_file-Berechtigung auf read oder write festlegst, kann dieses Array die Pfade für bis zu zehn Dateien speichern, die deine GitHub App verwaltet. 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
Du kannst 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. Wenn in der Benutzeroberfläche für checks kein Zugriff gewährt werden soll, enthält deine Abfragezeichenfolge die Berechtigung checks nicht.
Weitere Informationen zu Berechtigungen und GitHub Apps findest du unter Auswählen von Berechtigungen für eine GitHub-App.
GitHub App-Webhook-Ereignisse
Du kannst Abfrageparameter verwenden, um den GitHub App-Webhook zu aktivieren, eine Webhook-URL festzulegen und den Empfang von Webhook-Nutzdaten zu bestimmten Ereignissen für die App zu abonnieren.
Wenn du den GitHub App-Webhook aktivieren möchtest, verwende in deiner Abfragezeichenfolge die Angabe webhook_active=true. Verwende webhook_url in deiner Abfragezeichenfolge, um eine vollständige URL anzugeben, an die Ereignisnutzdaten zu dem Webhook gesendet werden sollen. Wenn bestimmte Ereignisnutzdaten zu dem Webhook für die App abonniert werden sollen, verwende events[] als Abfrageparameternamen, und lege den Abfragewert auf den Namen des Webhookereignisses fest. Weitere Informationen zu den möglichen Webhookereignissen und den GitHub App-Berechtigungen, die zum Abonnieren der einzelnen Ereignisse erforderlich sind, findest du unter Webhook-Ereignisse und -Nutzlasten.
Wenn du beispielsweise für eine GitHub App den Empfang von Webhook-Nutzdaten zu Aktivitäten in Zusammenhang mit Commitkommentaren abonnieren möchtest, enthält deine Abfragezeichenfolge die Angabe &webhook_active=true&webhook_url=https://example.com&events[]=commit_comment. Achtung: Für das Webhookereignis commit_comment benötigt die GitHub App mindestens schreibgeschützten Zugriff auf die Repositoryberechtigung „Contents“. Daher sollte deine Abfragezeichenfolge auch einen Parameter enthalten, mit dem die Berechtigung contents auf read oder write festgelegt wird. Weitere Informationen findest du unter GitHub-App-Berechtigungen.
Abfrageparameter können nicht verwendet werden, um den Wert eines Webhookgeheimnisses festzulegen. Wenn eine App ein Geheimnis für den Schutz ihres Webhooks benötigt, muss der Wert des Geheimnisses über die GitHub-Benutzeroberfläche von der Person festgelegt werden, die die App registriert.
Weitere Informationen zu Webhooks und GitHub Apps findest du unter Verwenden von Webhooks mit GitHub-Apps.