Cet article explique comment rapidement bien démarrer avec l’API REST GitHub à l’aide de GitHub CLI, JavaScript ou curl
. Pour obtenir un guide plus détaillé, consultez « Prise en main de l’API REST ».
Bien démarrer avec GitHub CLI
Utilisation de GitHub CLI dans la ligne de commande
GitHub CLI constitue la manière la plus facile d’utiliser l’API REST GitHub à partir de la ligne de commande.
Remarque : L’exemple suivant est conçu pour GitHub.com. Si vous préférez essayer l’exemple avec GitHub Enterprise Server, vous devez remplacer octocat/Spoon-Knife
par un dépôt sur votre instance. Vous pouvez également réexécuter la commande gh auth login
pour vous authentifier auprès de GitHub.com au lieu de votre instance.
-
Installez GitHub CLI si vous ne l’avez pas encore fait. Pour obtenir des instructions d’installation, consultez le dépôt GitHub CLI.
-
Utilisez la sous-commande
auth login
pour vous authentifier auprès de GitHub CLI. Pour plus d’informations, consultez la documentation sur la sous-commande GitHub CLIauth login
.gh auth login
-
Utilisez la sous-commande
api
pour effectuer votre requête d’API. Pour plus d’informations, consultez la documentation sur la sous-commande GitHub CLIapi
.gh api repos/octocat/Spoon-Knife/issues
Utilisation de GitHub CLI dans GitHub Actions
Vous pouvez aussi utiliser GitHub CLI dans vos workflows GitHub Actions. Pour plus d’informations, consultez « Utilisation de l’interface CLI de GitHub dans des workflows ».
Au lieu d’utiliser la commande gh auth login
, passez un jeton d’accès en tant que variable d’environnement appelée GH_TOKEN
. GitHub vous recommande d’utiliser le jeton GITHUB_TOKEN
intégré au lieu de créer un jeton. Si ce n’est pas possible, stockez votre jeton sous forme de secret et remplacez GITHUB_TOKEN
dans l’exemple ci-dessous par le nom de votre secret. Pour plus d’informations sur GITHUB_TOKEN
, consultez « Authentification par jeton automatique ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».
Remarque : Les exemples de workflows suivants sont conçus pour GitHub.com. Si vous préférez essayer les exemples à l’aide de GitHub Enterprise Server, vous devez remplacer octocat/Spoon-Knife
par un dépôt sur GitHub Enterprise Server.
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
Si vous vous authentifiez avec une GitHub App, vous pouvez créer un jeton d’accès d’installation au sein de votre workflow :
-
Stockez l’ID de votre GitHub App sous forme de secret. Dans l’exemple suivant, remplacez
APP_ID
par le nom du secret. Vous pouvez trouver votre ID d’application dans la page Paramètres de votre application ou via l’API. Pour plus d’informations, consultez « Applications GitHub » dans la documentation de l’API REST. Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ». -
Générez une clé privée pour votre application. Stockez le contenu du fichier obtenu dans un secret. (Stockez l’intégralité du contenu du fichier, y compris
-----BEGIN RSA PRIVATE KEY-----
et-----END RSA PRIVATE KEY-----
.) Dans l’exemple suivant, remplacezAPP_PEM
par le nom du secret. Pour plus d’informations, consultez « Gestion des clés privées pour les applications GitHub ». -
Ajoutez une étape pour générer un jeton, puis utilisez ce jeton au lieu de
GITHUB_TOKEN
. Notez que ce jeton expire au bout de 60 minutes. Par exemple :# Ce workflow utilise des actions qui ne sont pas certifiées par GitHub. # Elles sont fournies par un tiers et régies par # des conditions d’utilisation du service, une politique de confidentialité et un support distincts. # documentation en ligne. 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
Bien démarrer avec JavaScript
Vous pouvez utiliser Octokit.js pour interagir avec l’API REST GitHub dans vos scripts JavaScript. Pour plus d’informations, consultez « Écriture de scripts avec l’API REST et JavaScript ».
Utilisation d’Octokit.js
Remarque : L’exemple suivant est conçu pour GitHub.com. Si vous préférez essayer l’exemple avec GitHub Enterprise Server, vous devez remplacer octocat/Spoon-Knife
par un dépôt sur votre instance. Vous pouvez également créer une instance Octokit
sans spécifier baseURL
.
-
Créez un jeton d’accès. Par exemple, créez un personal access token ou un jeton d’accès utilisateur GitHub App. Pour plus d’informations, consultez « Création d’un personal access token » ou « Identification et autorisation des utilisateurs pour les applications GitHub ».
Avertissement : Considérez votre jeton d’accès comme un mot de passe.
Pour sécuriser votre jeton, vous pouvez stocker votre jeton sous forme de secret et exécuter votre script par le biais de GitHub Actions. Pour plus d’informations, consultez la section « Utilisation d’Octokit.js dans GitHub Actions ».
Si ces options ne sont pas possibles, envisagez d’utiliser un autre service comme l’interface CLI 1Password pour stocker votre jeton de manière sécurisée.
-
Installez
octokit
. Par exemple :npm install octokit
. Pour découvrir d’autres manières d’installer ou chargeroctokit
, consultez le fichier Lisez-moi d’Octokit.js. -
Importez
octokit
dans votre script. Par exemple :import { Octokit } from "octokit";
. Pour découvrir d’autres manières d’importeroctokit
, consultez le fichier Lisez-moi d’Octokit.js. -
Créez une instance de
Octokit
avec votre jeton. RemplacezYOUR-TOKEN
par votre jeton.const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
-
Utilisez
octokit.request
pour exécuter votre requête. Envoyez la méthode HTTP et le chemin en tant que premier argument. Spécifiez tous les paramètres de chemin, de requête et de corps dans un objet en tant que deuxième argument. Par exemple, dans la requête suivante, la méthode HTTP estGET
, le chemin est/repos/{owner}/{repo}/issues
et les paramètres sontowner: "octocat"
etrepo: "Spoon-Knife"
.await octokit.request("GET /repos/{owner}/{repo}/issues", { owner: "octocat", repo: "Spoon-Knife", });
Utilisation d’Octokit.js dans GitHub Actions
Vous pouvez aussi exécuter vos scripts JavaScript dans vos workflows GitHub Actions. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».
GitHub vous recommande d’utiliser le jeton GITHUB_TOKEN
intégré au lieu de créer un jeton. Si ce n’est pas possible, stockez votre jeton sous forme de secret et remplacez GITHUB_TOKEN
dans l’exemple ci-dessous par le nom de votre secret. Pour plus d’informations sur GITHUB_TOKEN
, consultez « Authentification par jeton automatique ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».
Remarque : L’exemple suivant est conçu pour GitHub.com. Si vous préférez essayer l’exemple avec GitHub Enterprise Server, vous devez remplacer octocat/Spoon-Knife
par un dépôt sur votre instance. Vous pouvez également créer une instance Octokit
sans spécifier baseURL
.
L’exemple de workflow suivant effectue ceci :
- Il extrait le contenu du dépôt.
- Il configure Node.js.
- Il installe
octokit
. - Il stocke la valeur de
GITHUB_TOKEN
sous forme de variable d’environnement appeléeTOKEN
et exécute.github/actions-scripts/use-the-api.mjs
, qui peut accéder à cette variable d’environnement en tant queprocess.env.TOKEN
.
Exemple de workflow :
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 }}
Exemple de script JavaScript, avec le chemin de fichier .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}`)
}
Si vous vous authentifiez avec une GitHub App, vous pouvez créer un jeton d’accès d’installation au sein de votre workflow :
-
Stockez l’ID de votre GitHub App sous forme de secret. Dans l’exemple suivant, remplacez
APP_ID
par le nom du secret. Vous pouvez trouver votre ID d’application dans la page Paramètres de votre application ou via l’API d’application. Pour plus d’informations, consultez « Applications GitHub ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ». -
Générez une clé privée pour votre application. Stockez le contenu du fichier obtenu dans un secret. (Stockez l’intégralité du contenu du fichier, y compris
-----BEGIN RSA PRIVATE KEY-----
et-----END RSA PRIVATE KEY-----
.) Dans l’exemple suivant, remplacezAPP_PEM
par le nom du secret. Pour plus d’informations, consultez « Gestion des clés privées pour les applications GitHub ». -
Ajoutez une étape pour générer un jeton, puis utilisez ce jeton au lieu de
GITHUB_TOKEN
. Notez que ce jeton expire au bout de 60 minutes. Par exemple :# Ce workflow utilise des actions qui ne sont pas certifiées par GitHub. # Elles sont fournies par un tiers et régies par # des conditions d’utilisation du service, une politique de confidentialité et un support distincts. # documentation en ligne. 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 }}
Bien démarrer avec curl
Utilisation de curl
dans la ligne de commande
Remarques :
- L’exemple suivant est conçu pour GitHub.com. Si vous préférez essayer l’exemple avec GitHub Enterprise Server, vous devez remplacer
https://api.github.com
parhttp(s)://HOSTNAME/api/v3
et remplacerHOSTNAME
par le nom d’hôte pour votre instance GitHub Enterprise Server. Vous devez également remplaceroctocat/Spoon-Knife
par un dépôt sur GitHub Enterprise Server. - Si vous voulez créer des requêtes d’API à partir de la ligne de commande, GitHub vous recommande d’utiliser GitHub CLI, ce qui simplifie l’authentification et les requêtes. Pour plus d’informations sur la prise en main de l’API REST à l’aide de GitHub CLI, consultez la version GitHub CLI de cet article.
-
Installez
curl
s’il n’est pas déjà installé sur votre ordinateur. Pour vérifier sicurl
est installé, exécutezcurl --version
dans la ligne de commande. Si la sortie correspond à des informations sur la version decurl
, cela signifie qu’il est installé. Si vous recevez un message commecommand not found: curl
, vous avez besoin de télécharger et d’installercurl
. Pour plus d’informations, consultez la page de téléchargement du projet . -
Créez un jeton d’accès. Par exemple, créez un personal access token ou un jeton d’accès utilisateur GitHub App. Pour plus d’informations, consultez « Création d’un personal access token » ou « Identification et autorisation des utilisateurs pour les applications GitHub ».
Avertissement : Considérez votre jeton d’accès comme un mot de passe.
Vous pouvez aussi utiliser GitHub CLI au lieu de
curl
. GitHub CLI s’occupe de l’authentification pour vous. Pour plus d’informations, consultez la version GitHub CLI de cette page.Si ces options ne sont pas possibles, envisagez d’utiliser un autre service comme l’interface CLI 1Password pour stocker votre jeton de manière sécurisée.
-
Utilisez la commande
curl
pour effectuer votre requête. Passez votre jeton dans un en-têteAuthorization
. RemplacezYOUR-TOKEN
par votre jeton.curl --request GET \ --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN"
Remarque : Dans la plupart des cas, vous pouvez utiliser
Authorization: Bearer
ouAuthorization: token
pour passer un jeton. Toutefois, si vous passez un jeton web JSON (JWT), vous devez utiliserAuthorization: Bearer
.
Utilisation de commandes curl
dans GitHub Actions
Vous pouvez aussi utiliser des commandes curl
dans vos workflows GitHub Actions.
GitHub vous recommande d’utiliser le jeton GITHUB_TOKEN
intégré au lieu de créer un jeton. Si ce n’est pas possible, stockez votre jeton sous forme de secret et remplacez GITHUB_TOKEN
dans l’exemple ci-dessous par le nom de votre secret. Pour plus d’informations sur GITHUB_TOKEN
, consultez « Authentification par jeton automatique ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».
Remarque : Les exemples de workflows suivants sont conçus pour GitHub.com. Si vous préférez essayer les exemples avec GitHub Enterprise Server, notez les différences suivantes.
- Vous devez remplacer
https://api.github.com
parhttp(s)://HOSTNAME/api/v3
etHOSTNAME
par le nom d’hôte pour votre instance GitHub Enterprise Server. - Vous devez remplacer
octocat/Spoon-Knife
par un dépôt sur GitHub Enterprise Server.
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"
Si vous vous authentifiez avec une GitHub App, vous pouvez créer un jeton d’accès d’installation au sein de votre workflow :
-
Stockez l’ID de votre GitHub App sous forme de secret. Dans l’exemple suivant, remplacez
APP_ID
par le nom du secret. Vous pouvez trouver votre ID d’application dans la page Paramètres de votre application ou via l’API d’application. Pour plus d’informations, consultez « Applications GitHub ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ». -
Générez une clé privée pour votre application. Stockez le contenu du fichier obtenu dans un secret. (Stockez l’intégralité du contenu du fichier, y compris
-----BEGIN RSA PRIVATE KEY-----
et-----END RSA PRIVATE KEY-----
.) Dans l’exemple suivant, remplacezAPP_PEM
par le nom du secret. Pour plus d’informations, consultez « Gestion des clés privées pour les applications GitHub ». -
Ajoutez une étape pour générer un jeton, puis utilisez ce jeton au lieu de
GITHUB_TOKEN
. Notez que ce jeton expire au bout de 60 minutes. Par exemple :# Ce workflow utilise des actions qui ne sont pas certifiées par GitHub. # Elles sont fournies par un tiers et régies par # des conditions d’utilisation du service, une politique de confidentialité et un support distincts. # documentation en ligne. 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"
Étapes suivantes
Pour obtenir un guide plus détaillé, consultez Bien démarrer avec l’API REST ».