Authentifizierung als GitHub-App-Installation

Du kannst deine GitHub App als Installation authentifizieren lassen, um API-Anforderungen zu stellen, die sich auf Ressourcen im Besitz des Kontos auswirken, in dem die App installiert ist.

In diesem Artikel

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:

  1. 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.

  2. 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 oder GET /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“.

  3. Sende eine REST-API-POST-Anforderung an /app/installations/INSTALLATION_ID/access_tokens. Fügen dein JSON-Webtoken in den Authorization-Header deiner Anforderung ein. Ersetze INSTALLATION_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 und JWT durch dein JSON-Webtoken:

    curl --request POST \
--url "http(s)://HOSTNAME/api/v3/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 oder repository_ids verwenden, um einzelne Repositorys anzugeben, auf die das Installationszugriffstoken zugreifen kann. Wenn du nicht repositories oder repository_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.

    Verwende optional den Textparameter permissions, um die Berechtigungen anzugeben, die das Installationszugriffstoken haben soll. Wenn permissions 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.

    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 oder Authorization: token verwenden, um ein Token zu übergeben. Wenn du jedoch ein JWT (JSON Web Token) übergibst, musst du Authorization: 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 "http(s)://HOSTNAME/api/v3/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

  1. 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.

  2. Erstellen eines privaten Schlüssels. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.

  3. 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 oder GET /app/installations abrufen. Weitere Informationen findest du unter REST-API-Endpunkte für GitHub Apps.

  4. Importiere App aus octokit. Erstelle eine neue App-Instanz. Ersetze APP_ID im folgenden Beispiel durch einen Verweis auf die ID deiner App. Ersetze PRIVATE_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,
});

  5. Verwenden die getInstallationOctokit-Methode, um eine authentifizierte octokit-Instanz zu erstellen. Ersetze im folgenden Beispiel INSTALLATION_ID durch die ID der Installation der App, für die du dich authentifizieren möchtest.

    JavaScript
    const octokit = await app.getInstallationOctokit(INSTALLATION_ID);

  6. 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
    }
  }
  `)

    Stelle beispielsweise so eine Anforderung an die REST-API:

    JavaScript
    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.

  1. 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.

  2. Erstellen eines privaten Schlüssels. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.

  3. 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.

  4. Importiere App aus octokit. Erstelle eine neue App-Instanz. Ersetze APP_ID im folgenden Beispiel durch einen Verweis auf die ID deiner App. Ersetze PRIVATE_KEY durch einen Verweis auf den privaten Schlüssel deiner App. Ersetze WEBHOOK_SECRET durch das Webhookgeheimnis deiner App.

    JavaScript
    import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
  webhooks: { WEBHOOK_SECRET },
});

  5. 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",
      },
    }
  )
});