Skip to main content

Schnellstart für die GitHub-REST-API

Erfahre mehr über die ersten Schritte mit der GitHub-REST-API.

Dieser Artikel enthält Informationen zum schnellen Einstieg in die GitHub-REST-API mithilfe von GitHub CLI, JavaScript oder curl. Einen ausführlicheren Leitfaden findest du unter Erste Schritte mit der REST-API.

Erste Schritte mit der GitHub CLI

Verwenden der GitHub CLI in der Befehlszeile

Die GitHub CLI ist der einfachste Weg, um die GitHub-REST-API über die Befehlszeile zu nutzen.

  1. Installiere die GitHub CLI, sofern nicht bereits geschehen. Anweisungen zur Installation findest du im GitHub CLI-Repository.

  2. Verwende den Unterbefehl auth login, um dich bei der GitHub CLI zu authentifizieren. Weitere Informationen findest du in der Dokumentation zu GitHub CLI auth login.

    gh auth login
    
  3. Verwende den Unterbefehl api, um deine API-Anforderung auszuführen. Weitere Informationen findest du in der Dokumentation zu GitHub CLI api.

    gh api repos/octocat/Spoon-Knife/issues
    

Verwenden der GitHub CLI in GitHub Actions

Du kannst die GitHub CLI auch in deinen GitHub Actions-Workflows verwenden. Weitere Informationen findest du unter Verwenden der GitHub CLI in Workflows.

Anstatt den Befehl gh auth login zu verwenden, übergibst du ein Zugriffstoken als Umgebungsvariable namens GH_TOKEN. GitHub empfiehlt, dass du das integrierte GITHUB_TOKEN verwendest, anstatt ein Token zu erstellen. Wenn das nicht möglich ist, speichere dein Token als Geheimnis, und ersetze GITHUB_TOKEN im folgenden Beispiel durch den Namen deines Geheimnisses. Weitere Informationen zu GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu Geheimnissen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api repos/octocat/Spoon-Knife/issues

Wenn du dich mit einer GitHub App authentifizierst, kannst du innerhalb deines Workflows ein Zugriffstoken für die Installation erstellen:

  1. Speichere die ID deiner GitHub App als Geheimnis. Ersetze im folgenden Beispiel APP_ID durch den Namen des Geheimnisses. Du findest die App-ID auf der Einstellungsseite deiner App oder über die API. Weitere Informationen findest du in der REST-API-Dokumentation unter GitHub Apps. Weitere Informationen zu Geheimnissen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

  2. Generiere einen privaten Schlüssel für deine App. Speichere den Inhalt der resultierenden Datei als Geheimnis. (Speichere den gesamten Inhalt der Datei, einschließlich -----BEGIN RSA PRIVATE KEY----- und -----END RSA PRIVATE KEY-----.) Ersetze im folgenden Beispiel APP_PEM durch den Namen des Geheimnisses. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.

  3. Füge einen Schritt zum Generieren eines Tokens hinzu, und verwende diesen Token anstelle von GITHUB_TOKEN. Beachte, dass dieses Token nach 60 Minuten abläuft. Beispiel:

    on:
      workflow_dispatch:
    jobs:
      track_pr:
        runs-on: ubuntu-latest
        steps:
          - name: Generate token
            id: generate_token
            uses: actions/create-github-app-token@v1
            with:
              app_id: ${{ secrets.APP_ID }}
              private_key: ${{ secrets.APP_PEM }}
          - name: Use API
            env:
              GH_TOKEN: ${{ steps.generate_token.outputs.token }}
            run: |
              gh api repos/octocat/Spoon-Knife/issues
    

Erste Schritte mit JavaScript

Du kannst „Octokit.js“ verwenden, um in deinen JavaScript-Skripts mit der GitHub-REST-API zu interagieren. Weitere Informationen findest du unter Skripterstellung mit der REST-API und JavaScript.

Verwenden von „Octokit.js“

  1. Erstelle ein Zugriffstoken. Erstelle zum Beispiel ein personal access token oder ein GitHub App-Benutzerzugriffstoken. Weitere Informationen findest du unter Erstellen eines personal access token oder Identifizieren und Autorisieren von Benutzern für GitHub-Apps.

    Warnung: Behandle dein Zugriffstoken wie ein Kennwort.

    Um dein Token zu schützen, kannst du es als Geheimnis speichern und dein Skript über GitHub Actions ausführen. Weitere Informationen findest du im Abschnitt Verwenden von „Octokit.js“ in GitHub Actions.

    Du kannst dein Token auch als Codespaces-Geheimnis speichern und dein Skript in Codespaces ausführen. Weitere Informationen findest du unter Verwalten verschlüsselter Geheimnisse für deine Codespaces.

    Wenn diese Optionen nicht verfügbar sind, solltest du einen anderen CLI-Dienst nutzen, um dein Token sicher zu speichern.

  2. Installieren von octokit. Beispiel: npm install octokit. Informationen über andere Möglichkeiten zum Installieren oder Laden von octokit findest du in der Octokit.js-Infodatei.

  3. Importiere octokit in dein Skript. Beispiel: import { Octokit } from "octokit";. Informationen über andere Möglichkeiten zum Importieren von octokit findest du in der Octokit.js-Infodatei.

  4. Erstelle eine Instanz von Octokit mit deinem Token. Ersetze YOUR-TOKEN durch dein Token.

    const octokit = new Octokit({
      auth: 'YOUR-TOKEN'
    });
    
  5. Verwende octokit.request, um deine Anforderung auszuführen. Übergib die HTTP-Methode und den Pfad als erstes Argument. Gib alle Pfad-, Abfrage- und Textparameter als zweites Argument in einem Objekt an. In der folgenden Anforderung lautet die HTTP-Methode zum Beispiel GET, der Pfad /repos/{owner}/{repo}/issues und die Parameter owner: "octocat" und repo: "Spoon-Knife".

    await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "octocat",
      repo: "Spoon-Knife",
    });
    

Verwenden von „Octokit.js“ in GitHub Actions

Du kannst auch deine JavaScript-Skripts in deinen GitHub Actions-Workflows ausführen. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

GitHub empfiehlt, dass du das integrierte GITHUB_TOKEN verwendest, anstatt ein Token zu erstellen. Wenn das nicht möglich ist, speichere dein Token als Geheimnis, und ersetze GITHUB_TOKEN im folgenden Beispiel durch den Namen deines Geheimnisses. Weitere Informationen zu GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu Geheimnissen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

Der nachstehende Beispielworkflow übernimmt folgende Aufgaben:

  1. Überprüfen des Repositoryinhalts
  2. Einrichten von Node.js
  3. Installieren von octokit
  4. Speichern des Werts von GITHUB_TOKEN als Umgebungsvariable namens TOKEN und Ausführen des Skripts .github/actions-scripts/use-the-api.mjs, das auf diese Umgebungsvariable als process.env.TOKEN zugreifen kann

Beispielworkflow:

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - name: Check out repo content
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Run script
        run: |
          node .github/actions-scripts/use-the-api.mjs
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}

JavaScript-Beispielskript mit dem Dateipfad .github/actions-scripts/use-the-api.mjs:

import { Octokit } from "octokit"

const octokit = new Octokit({
  auth: process.env.TOKEN
});

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "octocat",
      repo: "Spoon-Knife",
    });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

Wenn du dich mit einer GitHub App authentifizierst, kannst du innerhalb deines Workflows ein Zugriffstoken für die Installation erstellen:

  1. Speichere die ID deiner GitHub App als Geheimnis. Ersetze im folgenden Beispiel APP_ID durch den Namen des Geheimnisses. Du kannst die App-ID auf der Einstellungsseite deiner App oder durch die App-API finden. Weitere Informationen findest du unter GitHub Apps. Weitere Informationen zu Geheimnissen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

  2. Generiere einen privaten Schlüssel für deine App. Speichere den Inhalt der resultierenden Datei als Geheimnis. (Speichere den gesamten Inhalt der Datei, einschließlich -----BEGIN RSA PRIVATE KEY----- und -----END RSA PRIVATE KEY-----.) Ersetze im folgenden Beispiel APP_PEM durch den Namen des Geheimnisses. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.

  3. Füge einen Schritt zum Generieren eines Tokens hinzu, und verwende diesen Token anstelle von GITHUB_TOKEN. Beachte, dass dieses Token nach 60 Minuten abläuft. Beispiel:

    on:
      workflow_dispatch:
    jobs:
      use_api_via_script:
        runs-on: ubuntu-latest
        steps:
          - name: Check out repo content
            uses: actions/checkout@v4
    
          - name: Setup Node
            uses: actions/setup-node@v4
            with:
              node-version: '16.17.0'
              cache: npm
    
          - name: Install dependencies
            run: npm install octokit
    
          - name: Generate token
            id: generate_token
            uses: actions/create-github-app-token@v1
            with:
              app_id: ${{ secrets.APP_ID }}
              private_key: ${{ secrets.APP_PEM }}
    
          - name: Run script
            run: |
              node .github/actions-scripts/use-the-api.mjs
            env:
              TOKEN: ${{ steps.generate_token.outputs.token }}
    
    

Erste Schritte mit curl

Verwenden von curl in der Befehlszeile

  1. Installiere curl auf deinem Computer, sofern nicht bereits geschehen. Um festzustellen, ob curl bereits installiert ist, führe an der Befehlszeile curl --version aus. Wenn die Ausgabe Informationen über die curl-Version enthält, ist curl bereits installiert. Wenn du eine Meldung der Art command not found: curl erhältst, musst du curl herunterladen und installieren. Weitere Informationen findest du auf der Downloadseite für das curl-Projekt.

  2. Erstelle ein Zugriffstoken. Erstelle zum Beispiel ein personal access token oder ein GitHub App-Benutzerzugriffstoken. Weitere Informationen findest du unter Erstellen eines personal access token oder Identifizieren und Autorisieren von Benutzern für GitHub-Apps.

    Warnung: Behandle dein Zugriffstoken wie ein Kennwort.

    Um dein Token zu schützen, kannst du es als Codespaces-Geheimnis speichern und die Befehlszeile über Codespaces verwenden. Weitere Informationen findest du unter Verwalten verschlüsselter Geheimnisse für deine Codespaces.

    Du kannst anstelle von curl auch die GitHub CLI verwenden. Die GitHub CLI übernimmt die Authentifizierung für dich. Weitere Informationen findest du in der GitHub CLI-Version dieser Seite.

    Wenn diese Optionen nicht verfügbar sind, solltest du einen anderen CLI-Dienst nutzen, um dein Token sicher zu speichern.

  3. Verwende den Befehl curl, um deine Anforderung auszuführen. Übergib dein Token in einem Authorization-Header. Ersetze YOUR-TOKEN durch dein Token.

    curl --request GET \
    --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
    --header "Accept: application/vnd.github+json" \
    --header "Authorization: Bearer YOUR-TOKEN"
    

    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.

Verwenden von curl in GitHub Actions

Du kannst curl-Befehle auch in deinen GitHub Actions-Workflows verwenden.

GitHub empfiehlt, dass du das integrierte GITHUB_TOKEN verwendest, anstatt ein Token zu erstellen. Wenn das nicht möglich ist, speichere dein Token als Geheimnis, und ersetze GITHUB_TOKEN im folgenden Beispiel durch den Namen deines Geheimnisses. Weitere Informationen zu GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu Geheimnissen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"

Wenn du dich mit einer GitHub App authentifizierst, kannst du innerhalb deines Workflows ein Zugriffstoken für die Installation erstellen:

  1. Speichere die ID deiner GitHub App als Geheimnis. Ersetze im folgenden Beispiel APP_ID durch den Namen des Geheimnisses. Du kannst die App-ID auf der Einstellungsseite deiner App oder durch die App-API finden. Weitere Informationen findest du unter GitHub Apps. Weitere Informationen zu Geheimnissen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

  2. Generiere einen privaten Schlüssel für deine App. Speichere den Inhalt der resultierenden Datei als Geheimnis. (Speichere den gesamten Inhalt der Datei, einschließlich -----BEGIN RSA PRIVATE KEY----- und -----END RSA PRIVATE KEY-----.) Ersetze im folgenden Beispiel APP_PEM durch den Namen des Geheimnisses. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.

  3. Füge einen Schritt zum Generieren eines Tokens hinzu, und verwende diesen Token anstelle von GITHUB_TOKEN. Beachte, dass dieses Token nach 60 Minuten abläuft. Beispiel:

    on:
      workflow_dispatch:
    jobs:
      use_api:
        runs-on: ubuntu-latest
        steps:
          - name: Generate token
            id: generate_token
            uses: actions/create-github-app-token@v1
            with:
              app_id: ${{ secrets.APP_ID }}
              private_key: ${{ secrets.APP_PEM }}
    
          - name: Use API
            env:
              GH_TOKEN: ${{ steps.generate_token.outputs.token }}
            run: |
              curl --request GET \
              --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
              --header "Accept: application/vnd.github+json" \
              --header "Authorization: Bearer $GH_TOKEN"
    
    

Nächste Schritte

Einen ausführlicheren Leitfaden findest du unter Erste Schritte mit der REST-API.