Informationen zur Authentifizierung als GitHub App-Installation
Sobald deine GitHub App in einem Konto installiert ist, kannst du sie als App-Installation für API-Anforderungen authentifizieren lassen. Dadurch kann die App auf Ressourcen zugreifen, die sich im Besitz dieser Installation befinden, solange der App der erforderliche Repositoryzugriff und die erforderlichen Berechtigungen gewährt werden. Von einer App-Installation vorgenommene API-Anforderungen werden der App zugeordnet. Weitere Informationen zum Installieren von GitHub-Apps findest du unter Installieren von GitHub-Apps.
Wenn du beispielsweise möchtest, dass deine App das Status
-Feld eines Issues für ein Projekt ändert, das einer Organisation namens „octo-org“ gehört, dann würdest du dich als octo-org-Installation deiner App authentifizieren. Auf der Zeitachse des Issues wird angezeigt, dass deine App den Status aktualisiert hat.
Um eine API-Anforderung als Installation zu erstellen, musst du zunächst ein Installationszugriffstoken generieren. Anschließend sendest du das Installationszugriffstoken im Authorization
-Header deiner nachfolgenden API-Anforderungen. Du kannst auch die Octokit-SDKs von GitHub verwenden, die ein Installationszugriffstoken für dich generieren können.
Manche REST-API-Endpunkte akzeptieren keine Installationszugriffstoken, und bei den meisten REST-API-Endpunkten muss eine App bestimmte Berechtigungen für die Verwendung eines Endpunkts haben. Informationen dazu, ob ein REST-API-Endpunkt Installationszugriffstoken akzeptiert und welche Berechtigungen erforderlich sind, sind in der Dokumentation für den Endpunkt zu finden.
App-Installationen können auch die GraphQL-API verwenden. Ähnlich wie die REST-API muss die App über bestimmte Berechtigungen für den Zugriff auf Objekte in der GraphQL-API verfügen. Bei GraphQL-Anforderungen solltest du teste, ob deine App über die erforderlichen Berechtigungen für die GraphQL-Abfragen und -Mutationen verfügt, die du vornehmen möchtest.
Du kannst auch ein Installationszugriffstoken verwenden, um dich für den HTTP-basierten Git-Zugriff zu authentifizieren. Deine App muss über die Repositoryberechtigung für Inhalte verfügen. Anschließend kannst du das Installationszugriffstoken als HTTP-Kennwort verwenden. Ersetze TOKEN
durch das Installationszugriffstoken: git clone https://x-access-token:TOKEN@github.com/owner/repo.git
.
Anforderungen, die mit einem Installationszugriffstoken gestellt werden, werden manchmal als Server-zu-Server-Anforderungen bezeichnet.
Weitere Informationen zur Authentifizierung als App im Namen eines Benutzers und nicht als App-Installation findest du unter „Authentifizieren mit einer GitHub-App im Namen von Benutzer*innen“.
Verwenden eines Installationszugriffstokens zur Authentifizierung als App-Installation
Verwende zur Authentifizierung als Installation mit einem Installationszugriffstoken zunächst die REST-API, um ein Installationszugriffstoken zu generieren. Verwende dieses Installationszugriffstoken dann im Authorization
-Header einer REST-API- oder GraphQL-API-Anforderung. Das Installationszugriffstoken läuft nach 1 Stunde ab.
Generieren eines Installationszugriffstokens:
-
Generiere ein JSON-Webtoken (JWT) für deine App. Weitere Informationen findest du unter Generieren eines JSON Web Token (JWT) für eine GitHub-App.
-
Ruf die ID der Installation ab, als die du dich authentifizieren möchtest.
Wenn du auf ein Webhookereignis reagierst, enthält die Webhooknutzlast die Installations-ID.
Du kannst auch die REST-API verwenden, um die ID für eine Installation deiner App zu ermitteln. Eine Installations-ID kannst du z. B. mit den Endpunkten
GET /users/{username}/installation
,GET /repos/{owner}/{repo}/installation
,GET /orgs/{org}/installation
oderGET /app/installations
abrufen. Weitere Informationen findest du unter REST-API-Endpunkte für GitHub Apps.Sie finden die App-ID auch auf der Einstellungsseite Ihrer App. Die App-ID unterscheidet sich von der Client-ID. Weitere Informationen zum Aufrufen der Einstellungsseite für Ihre GitHub App finden Sie unter „Ändern einer GitHub-App-Registrierung“.
-
Sende eine REST-API-
POST
-Anforderung an/app/installations/INSTALLATION_ID/access_tokens
. Fügen dein JSON-Webtoken in denAuthorization
-Header deiner Anforderung ein. ErsetzeINSTALLATION_ID
durch die ID der Installation, als die du dich authentifizieren möchtest.Sende beispielsweise diese cURL-Anforderung. Ersetze
INSTALLATION_ID
durch die ID der Installation undJWT
durch dein JSON-Webtoken:curl --request POST \ --url "https://api.github.com/app/installations/INSTALLATION_ID/access_tokens" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer JWT" \ --header "X-GitHub-Api-Version: 2022-11-28"
Optional kannst du den Textparameter
repositories
oderrepository_ids
verwenden, um einzelne Repositorys anzugeben, auf die das Installationszugriffstoken zugreifen kann. Wenn du nichtrepositories
oderrepository_ids
verwendest, um Zugriff auf bestimmte Repositorys zu gewähren, hat das Installationszugriffstoken Zugriff auf alle Repositorys, auf die der Installation Zugriff gewährt wurde. Dem Installationszugriffstoken kann kein Zugriff auf Repositorys gewährt werden, auf die die Installation keinen Zugriff gewährt wurde. Sie können bis zu 500 Repositorys auflisten.Verwende optional den Textparameter
permissions
, um die Berechtigungen anzugeben, die das Installationszugriffstoken haben soll. Wennpermissions
nicht angegeben ist, verfügt das Installationszugriffstoken über alle Berechtigungen, die der App gewährt wurden. Dem Installationszugriffstoken können keine Berechtigungen gewährt werden, die der App nicht erteilt wurden.Wenn Sie die
permissions
-Parameter verwenden, um den Zugriff auf das Token zu verringern, wird die Komplexität des Tokens aufgrund der Anzahl der Berechtigungen in der Anforderung erhöht, und die Anzahl der Repositorys, auf die das Token zugreifen kann. Wenn die Komplexität zu groß ist, erhalten Sie eine Fehlermeldung, die die maximale Anzahl von Repositorys angibt, die unterstützt werden können. In diesem Fall sollten Sie weniger Berechtigungen mit dempermissions
-Parameter anfordern, denrepositories
- oderrepository_ids
-Parameter verwenden, um weniger Repositorys anzufordern oder die App inall
-Repositorys in Ihrer Organisation installieren.Die Antwort enthält ein Installationszugriffstoken, den Zeitpunkt, zu dem das Token abläuft, die Berechtigungen des Tokens und die Repositorys, auf die das Token zugreifen kann. Das Installationszugriffstoken läuft nach 1 Stunde ab.
Weitere Informationen zu diesem Endpunkt findest du unter REST-API-Endpunkte für GitHub Apps.
Hinweis: In den meisten Fällen kannst du
Authorization: Bearer
oderAuthorization: token
verwenden, um ein Token zu übergeben. Wenn du jedoch ein JWT (JSON Web Token) übergibst, musst duAuthorization: Bearer
verwenden.
Authentifizieren mit einem Installationszugriffstoken
Zur Authentifizierung mit einem Installationszugriffstoken füge es in den Authorization
-Header einer API-Anforderung ein. Das Zugriffstoken funktioniert sowohl mit der GraphQL-API als auch der REST-API.
Deine App muss über die erforderlichen Berechtigungen für die Verwendung des Endpunkts verfügen. Weitere Informationen findest du unter Auswählen von Berechtigungen für eine GitHub-App.
Ersetze INSTALLATION_ACCESS_TOKEN
im folgenden Beispiel durch ein Installationszugriffstoken:
curl --request GET \
--url "https://api.github.com/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"
Verwenden des Octokit.js-SDK zur Authentifizierung als App-Installation
Du kannst das Octokit.js-SDK von GitHub zur Authentifizierung als App-Installation verwenden. Ein Vorteil der Authentifizierung über das SDK besteht darin, dass du das JSON-Webtoken (JWT) nicht selbst generieren musst. Darüber hinaus kümmert sich das SDK darum, ein Installationszugriffstoken für dich neu zu generieren, damit du dir keine Gedanken über den einstündigen Ablauf machen musst.
Du musst octokit
installieren und importieren, um die Octokit.js-Bibliothek nutzen zu können. Im folgenden Beispiel werden Importanweisungen gemäß ES6 verwendet. Weitere Informationen zu verschiedenen Installations- und Importmethoden findest du im Abschnitt „Verwendung“ der Octokit.js-Infodatei.
Verwenden von Octokit.js zur Authentifizierung mit einer Installations-ID
-
Rufe die ID deiner GitHub App ab. Du findest die App-ID auf der Seite mit den Einstellungen für deine GitHub App. Weitere Informationen zum Aufrufen der Einstellungsseite für deine GitHub App findest du unter Ändern einer GitHub-App-Registrierung.
-
Erstellen eines privaten Schlüssels. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.
-
Ruf die ID der Installation ab, als die du dich authentifizieren möchtest.
Wenn du auf ein Webhookereignis reagierst, enthält die Webhooknutzlast die Installations-ID.
Du kannst auch die REST-API verwenden, um die ID für eine Installation deiner App zu ermitteln. Eine Installations-ID kannst du z. B. mit den Endpunkten
GET /users/{username}/installation
,GET /repos/{owner}/{repo}/installation
,GET /orgs/{org}/installation
oderGET /app/installations
abrufen. Weitere Informationen findest du unter REST-API-Endpunkte für GitHub Apps. -
Importiere
App
ausoctokit
. Erstelle eine neueApp
-Instanz. ErsetzeAPP_ID
im folgenden Beispiel durch einen Verweis auf die ID deiner App. ErsetzePRIVATE_KEY
durch einen Verweis auf den privaten Schlüssel deiner App.JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
-
Verwenden die
getInstallationOctokit
-Methode, um eine authentifizierteoctokit
-Instanz zu erstellen. Ersetze im folgenden BeispielINSTALLATION_ID
durch die ID der Installation der App, für die du dich authentifizieren möchtest.JavaScript const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
-
Verwende eine
octokit
-Methode, um eine Anforderung an die API zu senden.Deine App muss über die erforderlichen Berechtigungen für die Verwendung des Endpunkts verfügen. Weitere Informationen findest du unter Auswählen von Berechtigungen für eine GitHub-App.
Stelle beispielsweise so eine Anforderung an die GraphQL-API:
JavaScript await octokit.graphql(` query { viewer { login } } `)
await octokit.graphql(` query { viewer { login } } `)
Stelle beispielsweise so eine Anforderung an die REST-API:
JavaScript await octokit.request("GET /meta")
await octokit.request("GET /meta")
Verwenden von „Octokit.js“ zur Authentifizierung als Reaktion auf ein Webhookereignis
Das Octokit.js-SDK übergibt auch eine vorab authentifizierte octokit
-Instanz an Webhookereignishandler.
-
Rufe die ID deiner GitHub App ab. Du findest die App-ID auf der Seite mit den Einstellungen für deine GitHub App. Weitere Informationen zum Aufrufen der Einstellungsseite für deine GitHub App findest du unter Ändern einer GitHub-App-Registrierung.
-
Erstellen eines privaten Schlüssels. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.
-
Rufe das Webhookgeheimnis ab, das du in den Einstellungen deiner App angegeben hast. Weitere Informationen zu Webhookgeheimnissen findest du unter Verwenden von Webhooks mit GitHub-Apps.
-
Importiere
App
ausoctokit
. Erstelle eine neueApp
-Instanz. ErsetzeAPP_ID
im folgenden Beispiel durch einen Verweis auf die ID deiner App. ErsetzePRIVATE_KEY
durch einen Verweis auf den privaten Schlüssel deiner App. ErsetzeWEBHOOK_SECRET
durch das Webhookgeheimnis deiner App.JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
-
Verwende eine
app.webhooks.*
-Methode, um Webhookereignisse zu behandeln. Weitere Informationen findest du im Abschnitt zu Webhooks der Octokit.js-Infodatei. So erstellst du beispielsweise einen Kommentar zu einem Issue, wenn das Issue geöffnet wird:app.webhooks.on("issues.opened", ({ octokit, payload }) => { await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", { owner: payload.repository.owner.login, repo: payload.repository.name, issue_number: payload.issue.number, body: `This is a bot post in response to this issue being opened.`, headers: { "x-github-api-version": "2022-11-28", }, } ) });