Skip to main content

Démarrage rapide de l’API REST GitHub

Découvrez comment bien démarrer avec l’API REST GitHub.

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 Bien démarrer avec 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.

  1. Installez GitHub CLI si vous ne l’avez pas encore fait. Pour obtenir des instructions d’installation, consultez le dépôt GitHub CLI.

  2. 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 CLI auth login.

    gh auth login
  3. Utilisez la sous-commande api pour effectuer votre requête d’API. Pour plus d’informations, consultez la documentation sur la sous-commande GitHub CLI api.

    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 automatique par jeton ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».

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 :

  1. 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 » dans la documentation de l’API REST. Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».
  2. 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, remplacez APP_PEM par le nom du secret. Pour plus d’informations, consultez « Authentification avec des GitHub Apps ».
  3. 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@36464acb844fc53b9b8b2401da68844f6b05ebb0
        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

  1. Créez un jeton d’accès. Par exemple, créez un personal access token ou un jeton d’accès utilisateur-à-serveur 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.

  2. Installez octokit. Par exemple : npm install octokit. Pour découvrir d’autres manières d’installer ou charger octokit, consultez le fichier Lisez-moi d’Octokit.js.

  3. Importez octokit dans votre script. Par exemple : import { Octokit } from "octokit";. Pour découvrir d’autres manières d’importer octokit, consultez le fichier Lisez-moi d’Octokit.js.

  4. Créez une instance de Octokit avec votre jeton. Remplacez YOUR-TOKEN par votre jeton.

    const octokit = new Octokit({
      auth: 'YOUR-TOKEN'
    });
    
  5. 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 est GET, le chemin est /repos/{owner}/{repo}/issues et les paramètres sont owner: "octocat" et repo: "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 « Syntaxe de workflow pour 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 automatique par jeton ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».

L’exemple de workflow suivant effectue ceci :

  1. Il extrait le contenu du dépôt.
  2. Il configure Node.js.
  3. Il installe octokit.
  4. Il stocke la valeur de GITHUB_TOKEN sous forme de variable d’environnement appelée TOKEN et exécute .github/actions-scripts/use-the-api.mjs, qui peut accéder à cette variable d’environnement en tant que process.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 :

  1. 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. » Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».
  2. 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, remplacez APP_PEM par le nom du secret. Pour plus d’informations, consultez « Authentification avec des GitHub Apps ».
  3. 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@36464acb844fc53b9b8b2401da68844f6b05ebb0
        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

Note : Si vous voulez effectuer 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.

  1. Installez curl s’il n’est pas déjà installé sur votre ordinateur. Pour vérifier si curl est installé, exécutez curl --version dans la ligne de commande. Si la sortie correspond à des informations sur la version de curl, cela signifie qu’il est installé. Si vous recevez un message comme command not found: curl, vous avez besoin de télécharger et d’installer curl. Pour plus d’informations, consultez la page de téléchargement du projet .

  2. Créez un jeton d’accès. Par exemple, créez un personal access token ou un jeton d’accès utilisateur-à-serveur 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.

  3. Utilisez la commande curl pour effectuer votre requête. Passez votre jeton dans un en-tête Authorization. Remplacez YOUR-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 ou Authorization: token pour passer un jeton. Toutefois, si vous passez un jeton web JSON (JWT), vous devez utiliser Authorization: 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 automatique par jeton ». Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».

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 :

  1. 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. » Pour plus d’informations sur les secrets, consultez « Secrets chiffrés ».
  2. 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, remplacez APP_PEM par le nom du secret. Pour plus d’informations, consultez « Authentification avec des GitHub Apps ».
  3. 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@36464acb844fc53b9b8b2401da68844f6b05ebb0
        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 ».