Skip to main content
Nous publions des mises à jour fréquentes de notre documentation, et la traduction de cette page peut encore être en cours. Pour obtenir les informations les plus actuelles, consultez la documentation anglaise.

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.

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.

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

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

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

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

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

  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 GitHub ». 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 « 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 :

    # 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 par http(s)://HOSTNAME/api/v3 et remplacer HOSTNAME par le nom d’hôte pour votre instance GitHub Enterprise Server. Vous devez également remplacer octocat/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.
  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.

    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 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 par http(s)://HOSTNAME/api/v3 et HOSTNAME 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 :

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

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