Démarrage rapide pour 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 http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues

Utilisation d’Octokit.js

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.

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. Vous utiliserez ce jeton pour authentifier votre demande. Vous devez donc lui accorder toutes les étendues ou autorisations requises pour accéder à ce point de terminaison. Pour plus d’informations, consultez Authentification auprès de l’API REST ou Identifier et autoriser les utilisateurs pour GitHub Apps.

   Avertissement

   Considérez le 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 CLI pour stocker votre jeton en toute sécurité.

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

3. Importez octokit dans votre script. Par exemple : import { Octokit } from "octokit";. Pour d'autres moyens d'importer octokit, consultez le README d'Octokit.js.

4. créer une instance de Octokit à l’aide de votre jeton. Remplacez HOSTNAME par le nom de votre instance GitHub Enterprise Server. Remplacez YOUR-TOKEN par votre jeton.

   JavaScript

   const octokit = new Octokit({ 
     baseUrl: "http(s)://HOSTNAME/api/v3",
     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. Pour plus d’informations sur les paramètres, consultez Prise en main de l’API REST.

   Par exemple, dans la demande suivante, la méthode HTTP est GET, le chemin d’accès est /repos/{owner}/{repo}/issues, et les paramètres sont owner: "REPO-OWNER" et repo: "REPO-NAME". Remplacez REPO-OWNER par le nom du compte propriétaire du référentiel et REPO-NAME par le nom du référentiel.

   JavaScript

   await octokit.request("GET /repos/{owner}/{repo}/issues", {
     owner: "REPO-OWNER",
     repo: "REPO-NAME",
   });
   

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 flux de travail pour GitHub Actions ».

S’authentifier avec un jeton d’accès

GitHub vous recommande d’utiliser l’utilitaire intégré GITHUB_TOKEN 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 Utiliser GITHUB_TOKEN pour l’authentification dans les flux de travail. Pour plus d’informations sur les secrets, consultez « Utilisation de secrets dans GitHub Actions ».

L'exemple de flux de travail suivant :

1. Consulte 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.

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - name: Check out repo content
        uses: actions/checkout@v5

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

Voici un exemple de script JavaScript avec le chemin d’accès de fichier .github/actions-scripts/use-the-api.mjs. Remplacez HOSTNAME par le nom de votre instance GitHub Enterprise Server. Remplacez REPO-OWNER par le nom du compte propriétaire du référentiel. Remplacez REPO-NAME par le nom du référentiel.

import { Octokit } from "octokit"

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: process.env.TOKEN
});

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
      owner: "REPO-OWNER",
      repo: "REPO-NAME",
    });

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

Authentification avec l'GitHub App

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 variable de configuration. Dans l’exemple suivant, remplacez APP_ID par le nom de la variable de configuration. 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 « Points de terminaison d’API REST pour GitHub Apps ». Pour plus d’informations concernant les variables de configuration, consultez Stocker des informations dans des variables.

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

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@v5
   
         - 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@v2
           with:
             app-id: ${{ vars.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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_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 "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"