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

  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 par jeton automatique ». Pour plus d’informations sur les secrets, consultez « Utilisation de secrets dans GitHub Actions ».

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 GitHub » dans la documentation de l’API REST. Pour plus d’informations sur les secrets, consultez « Utilisation de secrets dans GitHub Actions ».

  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 « Gestion des clés privées pour les applications GitHub ».

  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 :

    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
    

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

    Vous pouvez aussi stocker votre jeton sous forme de secret Codespaces et exécuter votre script dans Codespaces. Pour plus d’informations, consultez « Gestion des secrets chiffrés pour vos codespaces ».

    Si ces options ne sont pas possibles, envisagez d’utiliser un autre service CLI 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 « 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 « Utilisation de secrets dans GitHub Actions ».

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@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 }}

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 GitHub ». Pour plus d’informations sur les secrets, consultez « Utilisation de secrets dans GitHub Actions ».

  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 « Gestion des clés privées pour les applications GitHub ».

  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 :

    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 }}
    
    

Bien démarrer avec curl

Utilisation de curl dans la ligne de commande

  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 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 aussi le stocker sous forme de secret Codespaces et utiliser la ligne de commande dans Codespaces. Pour plus d’informations, consultez « Gestion des secrets chiffrés pour vos codespaces ».

    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 CLI 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 par jeton automatique ». Pour plus d’informations sur les secrets, consultez « Utilisation de secrets dans GitHub Actions ».

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 GitHub ». Pour plus d’informations sur les secrets, consultez « Utilisation de secrets dans GitHub Actions ».

  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 « Gestion des clés privées pour les applications GitHub ».

  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 :

    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"
    
    

Étapes suivantes

Pour obtenir un guide plus détaillé, consultez Bien démarrer avec l’API REST ».