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.
Hinweis: Das folgende Beispiel ist für GitHub.com konzipiert. Wenn du die Verwendung von GitHub AE für das Beispiel bevorzugst, musst du octocat/Spoon-Knife
durch ein Repository für GitHub AE ersetzen. Führe alternativ dazu den gh auth login
-Befehl erneut aus, um dich bei GitHub.com statt bei GitHub AE zu authentifizieren.
-
Installiere die GitHub CLI, sofern nicht bereits geschehen. Anweisungen zur Installation findest du im GitHub CLI-Repository.
-
Verwende den Unterbefehl
auth login
, um dich bei der GitHub CLI zu authentifizieren. Weitere Informationen findest du in der Dokumentation zu GitHub CLIauth login
.gh auth login
-
Verwende den Unterbefehl
api
, um deine API-Anforderung auszuführen. Weitere Informationen findest du in der Dokumentation zu GitHub CLIapi
.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 Verschlüsselte Geheimnisse.
Hinweis: Die folgenden Beispielworkflows sind für GitHub.com konzipiert. Wenn du die Beispiele lieber mit GitHub AE ausprobieren möchtest, musst du octocat/Spoon-Knife
durch ein Repository auf GitHub AE ersetzen.
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:
-
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 Verschlüsselte Geheimnisse. -
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 BeispielAPP_PEM
durch den Namen des Geheimnisses. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps. -
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:# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind. # Sie werden von einem Drittanbieter bereitgestellt und unterliegen # separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support # Onlinedokumentation. on: workflow_dispatch: jobs: track_pr: runs-on: ubuntu-latest steps: - name: Generate token id: generate_token uses: tibdex/github-app-token@c2055a00597a80f713b78b1650e8d3418f4d9a65 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“
Hinweis: Das folgende Beispiel ist für GitHub.com konzipiert. Wenn du die Verwendung von GitHub AE für das Beispiel bevorzugst, musst du octocat/Spoon-Knife
durch ein Repository für GitHub AE ersetzen. Alternativ kannst du eine neue Octokit
-Instanz erstellen, ohne dabei baseURL
angeben zu müssen.
-
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.
Wenn diese Optionen nicht verfügbar sind, solltest du einen anderen Dienst wie zum Beispiel die 1Password CLI nutzen, um dein Token sicher zu speichern.
-
Installieren von
octokit
. Beispiel:npm install octokit
. Informationen über andere Möglichkeiten zum Installieren oder Laden vonoctokit
findest du in der Octokit.js-Infodatei. -
Importiere
octokit
in dein Skript. Beispiel:import { Octokit } from "octokit";
. Informationen über andere Möglichkeiten zum Importieren vonoctokit
findest du in der Octokit.js-Infodatei. -
Erstelle eine Instanz von
Octokit
mit deinem Token. ErsetzeYOUR-TOKEN
durch dein Token.const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
-
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 BeispielGET
, der Pfad/repos/{owner}/{repo}/issues
und die Parameterowner: "octocat"
undrepo: "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 Verschlüsselte Geheimnisse.
Hinweis: Das folgende Beispiel ist für GitHub.com konzipiert. Wenn du die Verwendung von GitHub AE für das Beispiel bevorzugst, musst du octocat/Spoon-Knife
durch ein Repository für GitHub AE ersetzen. Alternativ kannst du eine neue Octokit
-Instanz erstellen, ohne dabei baseURL
angeben zu müssen.
Der nachstehende Beispielworkflow übernimmt folgende Aufgaben:
- Überprüfen des Repositoryinhalts
- Einrichten von Node.js
- Installieren von
octokit
- Speichern des Werts von
GITHUB_TOKEN
als Umgebungsvariable namensTOKEN
und Ausführen des Skripts.github/actions-scripts/use-the-api.mjs
, das auf diese Umgebungsvariable alsprocess.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@v3
- name: Setup Node
uses: actions/setup-node@v3
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:
-
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 Verschlüsselte Geheimnisse. -
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 BeispielAPP_PEM
durch den Namen des Geheimnisses. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps. -
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:# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind. # Sie werden von einem Drittanbieter bereitgestellt und unterliegen # separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support # Onlinedokumentation. on: workflow_dispatch: jobs: use_api_via_script: runs-on: ubuntu-latest steps: - name: Check out repo content uses: actions/checkout@v3 - name: Setup Node uses: actions/setup-node@v3 with: node-version: '16.17.0' cache: npm - name: Install dependencies run: npm install octokit - name: Generate token id: generate_token uses: tibdex/github-app-token@c2055a00597a80f713b78b1650e8d3418f4d9a65 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
Hinweise:
- Das folgende Beispiel ist für GitHub.com konzipiert. Wenn du das Beispiel lieber mit GitHub AE ausprobieren möchtest, musst du
https://api.github.com
durchhttps://HOSTNAME/api/v3
sowieHOSTNAME
durch den Hostnamen für GitHub AE ersetzen. Außerdem mussoctocat/Spoon-Knife
durch ein Repository auf GitHub AE ersetzt werden. - Wenn du API-Anforderungen über die Befehlszeile ausführen möchtest, empfiehlt GitHub die Verwendung der GitHub CLI, da dies die Authentifizierung und das Ausführen von Anforderungen vereinfacht. Weitere Informationen zu den ersten Schritten mit der REST-API unter Verwendung der GitHub CLI findest du in der GitHub CLI-Version dieses Artikels.
-
Installiere
curl
auf deinem Computer, sofern nicht bereits geschehen. Um festzustellen, obcurl
bereits installiert ist, führe an der Befehlszeilecurl --version
aus. Wenn die Ausgabe Informationen über diecurl
-Version enthält, ist curl bereits installiert. Wenn du eine Meldung der Artcommand not found: curl
erhältst, musst ducurl
herunterladen und installieren. Weitere Informationen findest du auf der Downloadseite für das curl-Projekt. -
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.
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 Dienst wie zum Beispiel die 1Password CLI nutzen, um dein Token sicher zu speichern.
-
Verwende den Befehl
curl
, um deine Anforderung auszuführen. Übergib dein Token in einemAuthorization
-Header. ErsetzeYOUR-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
oderAuthorization: token
verwenden, um ein Token zu übergeben. Wenn du jedoch ein JWT (JSON Web Token) übergibst, musst duAuthorization: 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 Verschlüsselte Geheimnisse.
Hinweis: Die folgenden Beispielworkflows sind für GitHub.com konzipiert. Wenn du die Beispiele lieber mit GitHub AE ausprobieren möchtest, beachte die folgenden Unterschiede.
- Du musst
https://api.github.com
durchhttps://HOSTNAME/api/v3
sowieHOSTNAME
durch den Hostnamen für GitHub AE ersetzen. octocat/Spoon-Knife
muss durch ein Repository auf GitHub AE ersetzt werden.
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:
-
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 Verschlüsselte Geheimnisse. -
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 BeispielAPP_PEM
durch den Namen des Geheimnisses. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps. -
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:# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind. # Sie werden von einem Drittanbieter bereitgestellt und unterliegen # separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support # Onlinedokumentation. on: workflow_dispatch: jobs: use_api: runs-on: ubuntu-latest steps: - name: Generate token id: generate_token uses: tibdex/github-app-token@c2055a00597a80f713b78b1650e8d3418f4d9a65 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.