Informationen zu URL-Parametern für die Registrierung 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 finden Sie unter AUTOTITLE.
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: .
- Wenn eine App in einem Organisationskonto registriert werden soll, füge URL-Parameter an die folgende URL an: . Ersetze dabei 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 ) 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 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 ausgewählt, Webhooks mithilfe des Parameters aktiviert, die Webhookereignisse und 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
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 .
| Parametername | Typ | 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 Webseite Ihrer 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: . Weitere Informationen finden Sie unter AUTOTITLE. |
request_oauth_on_install | boolean | Wenn deine App Benutzer mit dem OAuth-Flow autorisiert, kannst du diese Option auf festlegen, damit Personen die App während der Installation autorisieren können, was einen Schritt einspart. Wenn du diese Option auswählst, ist die nicht mehr verfügbar, und Benutzer werden nach der Installation der App an deine weitergeleitet. |
setup_url | string | Die vollständige URL zur Weiterleitung nach der Installation der GitHub App, wenn die App nach der Installation ein zusätzliches Setup erfordert. Weitere Informationen finden Sie unter AUTOTITLE. |
setup_on_update | boolean | Lege diesen Parameter auf 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 fest, wenn deine GitHub App öffentlich verfügbar sein soll, oder auf , 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 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 - oder -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: . |
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 -Berechtigung auf oder festlegst, stellt dieses Feld den Pfad zur einzelnen Datei bereit, die deine GitHub App verwaltet. Wenn Sie mehrere Dateien verwalten müssen, siehe 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 -Berechtigung auf oder 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 festgelegt ist, und verfügen nicht über separate individuelle Berechtigungen. Wenn zwei oder mehr Dateien konfiguriert sind, gibt die API zurück, andernfalls . |
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 auswählen möchtest, enthält deine Abfragezeichenfolge die Angabe . Damit nur Leseberechtigungen in der Benutzeroberfläche für gewährt werden, muss deine Abfragezeichenfolge die Angabe enthalten. Wenn auf der Benutzeroberfläche für kein Zugriff gewährt werden soll, enthält deine Abfragezeichenfolge die Berechtigung nicht.
Weitere Informationen zu Berechtigungen und GitHub Apps findest du unter AUTOTITLE. Eine Liste der verfügbaren Berechtigungen und deren parametrisierte Namen findest du unter AUTOTITLE.
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.
Um den GitHub App-Webhook zu aktivieren, verwende die Angabe in deiner Abfragezeichenfolge. Verwende 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 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 AUTOTITLE.
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 . Achtung: Für das Webhookereignis 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 auf oder festgelegt wird. Weitere Informationen findest du unter Berechtigungen für GitHub-Apps.
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 AUTOTITLE.