Démarrage rapide de l’API REST GitHub

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

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

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

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"