Este artigo descreve como começar rapidamente com a API REST do GitHub usando GitHub CLI, JavaScript ou curl
. Para ver um guia mais detalhado, confira "Introdução à API REST".
Introdução ao uso da GitHub CLI
Como usar a GitHub CLI na linha de comando
A GitHub CLI é a maneira mais fácil de usar a API REST do GitHub por meio da linha de comando.
Observação: o exemplo a seguir é direcionado ao GitHub.com. Se preferir experimentar o exemplo usando o GitHub Enterprise Server, substitua octocat/Spoon-Knife
por um repositório na sua instância. Como alternativa, execute novamente o comando gh auth login
para se autenticar no GitHub.com em vez de sua instância.
-
Instale a GitHub CLI caso ainda não o tenha feito. Para obter instruções de instalação, confira o repositório da GitHub CLI.
-
Use o subcomando
auth login
para se autenticar na GitHub CLI. Para obter mais informações, confira a documentaçãoauth login
da GitHub CLI.gh auth login
-
Use o subcomando
api
para fazer sua solicitação de API. Para obter mais informações, confira a documentaçãoapi
da GitHub CLI.gh api repos/octocat/Spoon-Knife/issues
Como usar a GitHub CLI em GitHub Actions
Você também pode usar a GitHub CLI em seus fluxos de trabalho de GitHub Actions. Para obter mais informações, confira "Usar o GitHub CLI em fluxos de trabalho".
Em vez de usar o comando gh auth login
, passe um token de acesso como uma variável de ambiente chamada GH_TOKEN
. 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 "Segredos criptografados".
Observação: os fluxos de trabalho de exemplo a seguir são direcionados ao GitHub.com. Se preferir experimentar os exemplos usando o GitHub Enterprise Server, substitua octocat/Spoon-Knife
por um repositório no 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
Se estiver se autenticando com um GitHub App, você poderá criar um token de acesso de instalação no fluxo de trabalho:
-
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 aplicativo na página de configurações do aplicativo ou por meio da API. Para obter mais informações, confira "Aplicativos GitHub" na documentação da API REST. Para obter mais informações sobre segredos, confira "Segredos criptografados". -
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, substituaAPP_PEM
pelo nome do segredo. Para obter mais informações, confira "Como gerenciar chaves privadas para Aplicativos GitHub". -
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:# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub. # São fornecidas por terceiros e regidas por # termos de serviço, política de privacidade e suporte separados # online. 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
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
Observação: o exemplo a seguir é direcionado ao GitHub.com. Se preferir experimentar o exemplo usando o GitHub Enterprise Server, substitua octocat/Spoon-Knife
por um repositório na sua instância. Como alternativa, você pode criar uma instância Octokit
sem especificar baseURL
.
-
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".
Se essas opções não forem possíveis, considere usar outro serviço, como a CLI do 1Password, para armazenar seu token com segurança.
-
Instale o
octokit
. Por exemplo,npm install octokit
. Para outras maneiras de instalar ou carregaroctokit
, confira o LEIA-ME do Octokit.js. -
Importe
octokit
em seu script. Por exemplo,import { Octokit } from "octokit";
. Para outras maneiras de importaroctokit
, confira o LEIA-ME do Octokit.js. -
Crie uma instância de
Octokit
com seu token. SubstituaYOUR-TOKEN
pelo seu token.const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
-
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ãoowner: "octocat"
erepo: "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 "Segredos criptografados".
Observação: o exemplo a seguir é direcionado ao GitHub.com. Se preferir experimentar o exemplo usando o GitHub Enterprise Server, substitua octocat/Spoon-Knife
por um repositório na sua instância. Como alternativa, você pode criar uma instância Octokit
sem especificar baseURL
.
O seguinte exemplo de fluxo de trabalho:
- Verifica o conteúdo do repositório
- Configura o Node.js
- Instala
octokit
- Armazena o valor de
GITHUB_TOKEN
como uma variável de ambiente chamada deTOKEN
e executa.github/actions-scripts/use-the-api.mjs
, que pode acessar essa variável de ambiente comoprocess.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@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 }}
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:
-
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 "Segredos criptografados". -
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, substituaAPP_PEM
pelo nome do segredo. Para obter mais informações, confira "Como gerenciar chaves privadas para Aplicativos GitHub". -
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:# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub. # São fornecidas por terceiros e regidas por # termos de serviço, política de privacidade e suporte separados # online. 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 }}
Introdução ao uso de curl
Como usar curl
na linha de comando
Observações:
- O exemplo a seguir é direcionado ao GitHub.com. Se preferir experimentar o exemplo usando o GitHub Enterprise Server, substitua
https://api.github.com
porhttp(s)://HOSTNAME/api/v3
e substituaHOSTNAME
pelo nome do host do sua instância do GitHub Enterprise Server. Você também precisa substituiroctocat/Spoon-Knife
por um repositório no GitHub Enterprise Server. - Se você quiser fazer solicitações de API usando a linha de comando, o GitHub recomenda o uso da GitHub CLI, o que simplifica a autenticação e as solicitações. Para obter mais informações sobre como começar a usar a API REST usando a GitHub CLI, confira a versão da GitHub CLI deste artigo.
-
Instale o
curl
caso ainda não o tenha feito em seu computador. Para verificar se ocurl
está instalado, executecurl --version
na linha de comando. Se a saída for correspondente às informações sobre a versão docurl
, ele será instalado. Se você receber uma mensagem semelhante acommand not found: curl
, será necessário baixar e instalar ocurl
. Para obter mais informações, confira a página de download do projeto curl. -
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.
Você também pode usar a GitHub CLI em vez do
curl
. A GitHub CLI cuidará da autenticação para você. Para obter mais informações, confira a versão da GitHub CLI desta página.Se essas opções não forem possíveis, considere usar outro serviço, como a CLI do 1Password, para armazenar seu token com segurança.
-
Use o comando
curl
para fazer sua solicitação. Passe o token em um cabeçalhoAuthorization
. SubstituaYOUR-TOKEN
pelo seu token.curl --request GET \ --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN"
Observação: Na maioria dos casos, você pode usar
Authorization: Bearer
ouAuthorization: token
a fim de passar um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usarAuthorization: Bearer
.
Como usar os comandos curl
em GitHub Actions
Você também pode usar os comandos curl
em seus fluxo de trabalho de 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 "Segredos criptografados".
Observação: os fluxos de trabalho de exemplo a seguir são direcionados ao GitHub.com. Se preferir experimentar os exemplos usando o GitHub Enterprise Server, observe as diferenças a seguir.
- Você precisa substituir
https://api.github.com
porhttp(s)://HOSTNAME/api/v3
e substituirHOSTNAME
pelo nome do host do sua instância do GitHub Enterprise Server. - Você precisa substituir
octocat/Spoon-Knife
por um repositório no 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"
Se estiver se autenticando com um GitHub App, você poderá criar um token de acesso de instalação no fluxo de trabalho:
-
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 "Segredos criptografados". -
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, substituaAPP_PEM
pelo nome do segredo. Para obter mais informações, confira "Como gerenciar chaves privadas para Aplicativos GitHub". -
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:# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub. # São fornecidas por terceiros e regidas por # termos de serviço, política de privacidade e suporte separados # online. 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"
Próximas etapas
Para obter um guia mais detalhado, confira "Introdução à API REST".