Início Rápido para a API REST do 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

Introdução ao uso do JavaScript

Você pode usar Octokit.js para interagir com a API REST do GitHub em seus scripts do JavaScript. Para obter mais informações, confira "Scripts com a API REST e o JavaScript".

Como usar Octokit.js

1. Crie um token de acesso. Por exemplo, crie um personal access token ou um token de acesso de usuário do GitHub App. Para obter mais informações, confira "Como criar um personal access token" ou "Como identificar e autorizar usuários para Aplicativos GitHub".

   Aviso: trate seu token de acesso como uma senha.

   Para manter seu token seguro, você pode armazená-lo como um segredo e executar seu script por meio de GitHub Actions. Para obter mais informações, confira a seção "Como usar o Octokit.js em GitHub Actions".

   Você também pode armazenar seu token como um segredo do Codespaces e executar seu script no Codespaces. Para obter mais informações, confira "Como gerenciar os segredos criptografados dos seus codespaces".

   Se essas opções não forem possíveis, considere usar outro serviço do CLI para armazenar seu token com segurança.

2. Instale o octokit. Por exemplo, npm install octokit. Para outras maneiras de instalar ou carregar octokit, confira o LEIA-ME do Octokit.js.

3. Importe octokit em seu script. Por exemplo, import { Octokit } from "octokit";. Para outras maneiras de importar octokit, confira o LEIA-ME do Octokit.js.

4. Crie uma instância de Octokit com seu token. Substitua YOUR-TOKEN pelo seu token.

   const octokit = new Octokit({
     auth: 'YOUR-TOKEN'
   });
   

5. Use octokit.request para executar sua solicitação. Envie o método HTTP e o caminho como o primeiro argumento. Especifique quaisquer parâmetros de caminho, consulta e corpo em um objeto como o segundo argumento. Por exemplo, na solicitação a seguir, o método HTTP é GET, o caminho é /repos/{owner}/{repo}/issues e os parâmetros são owner: "octocat" e repo: "Spoon-Knife".

   await octokit.request("GET /repos/{owner}/{repo}/issues", {
     owner: "octocat",
     repo: "Spoon-Knife",
   });
   

Como usar o Octokit.js em GitHub Actions

Você também pode executar seus scripts do JavaScript nos fluxos de trabalho de GitHub Actions. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

O GitHub recomenda que você use o GITHUB_TOKEN interno em vez de criar um token. Se isso não for possível, armazene o token como um segredo e substitua GITHUB_TOKEN no exemplo abaixo pelo nome do seu segredo. Para obter mais informações sobre GITHUB_TOKEN, confira "Autenticação automática de token". Para obter mais informações sobre segredos, confira "Usar segredos em ações do GitHub".

O seguinte exemplo de fluxo de trabalho:

1. Verifica o conteúdo do repositório
2. Configura o Node.js
3. Instala octokit
4. Armazena o valor de GITHUB_TOKEN como uma variável de ambiente chamada de TOKEN e executa .github/actions-scripts/use-the-api.mjs, que pode acessar essa variável de ambiente como process.env.TOKEN

Fluxo de trabalho de exemplo:

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

Exemplo de script do JavaScript, com o caminho do arquivo .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}`)
}

Se estiver se autenticando com um GitHub App, você poderá criar um token de acesso de instalação no fluxo de trabalho:

1. Armazene a ID do seu GitHub App como um segredo. No exemplo a seguir, substitua APP_ID pelo nome do segredo. Você pode encontrar o ID do seu aplicativo na página de configurações do seu aplicativo ou por meio da API do aplicativo. Para obter mais informações, confira "Aplicativos GitHub". Para obter mais informações sobre segredos, confira "Usar segredos em ações do GitHub".

2. Gerar uma chave privada para o seu aplicativo. Armazene o conteúdo do arquivo resultante como um segredo. (Armazene todo o conteúdo do arquivo, incluindo -----BEGIN RSA PRIVATE KEY----- e -----END RSA PRIVATE KEY-----). No exemplo a seguir, substitua APP_PEM pelo nome do segredo. Para obter mais informações, confira "Como gerenciar chaves privadas para Aplicativos GitHub".

3. Adicione uma etapa para gerar um token e use esse token em vez de GITHUB_TOKEN. Observe que esse token vai expirar após 60 minutos. Por exemplo:

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

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"