Introdução
Este artigo descreve como começar rapidamente com a API REST do GitHub usando a GitHub CLI, curl
ou JavaScript. Para ver um guia mais detalhado, confira "Introdução à API REST".
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.
-
Instale a GitHub CLI no macOS, no Windows ou no Linux. Para obter instruções de instalação, confira Instalação no repositório do GitHub CLI.
-
Autentique-se com GitHub executando este comando em seu terminal. Substitua
HOSTNAME
pelo nome de sua instância do GitHub Enterprise Server. Por exemplo,octo-inc.ghe.com
.gh auth login --hostname HOSTNAME
-
Siga os prompts na tela.
O GitHub CLI armazena automaticamente suas credenciais do Git quando você escolhe HTTPS como protocolo preferencial para operações Git e responde "sim" ao prompt que pergunta se deseja efetuar a autenticação no Git com suas credenciais do GitHub. Isso pode ser útil porque permite que você use comandos Git como
git push
egit pull
sem a necessidade de configurar um gerenciador de credenciais separado ou usar SSH. -
Faça uma solicitação usando o subcomando GitHub CLI
api
, seguido pelo caminho. Use o sinalizador--method
ou-X
para especificar o método. Para obter mais informações, confira a documentaçãoapi
da GitHub CLI.Este exemplo faz uma solicitação para o ponto de extremidade "Obter Octocat", que usa o método
GET
e o caminho/octocat
. Para ver a documentação de referência completa desse ponto de extremidade, confira "Pontos de extremidade da API REST para metadados".Shell gh api /octocat --method GET
gh api /octocat --method GET
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".
Autenticação com um token de acesso
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 "Usar segredos em ações do GitHub".
O fluxo de trabalho de exemplo a seguir usa o ponto de extremidade "Listar issues do repositório" e solicita uma lista de issues em um repositório que você especificar. Substitua o HOSTNAME
pelo nome do sua instância do GitHub Enterprise Server. Substitua REPO-OWNER
pelo nome da conta proprietária do repositório. Substitua REPO-NAME
pelo nome do repositório.
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
Autenticação com um GitHub App
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 uma variável de configuração. No exemplo a seguir, substitua
APP_ID
pelo nome da variável de configuração. 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 "Pontos de extremidade da API REST para o GitHub Apps". Para saber mais sobre variáveis de configuração, confira "Armazenar informações em variáveis". -
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". Para obter mais informações sobre segredos, confira "Usar segredos em ações do 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. no exemplo a seguir, substituaHOSTNAME
pelo nome do sua instância do GitHub Enterprise Server. SubstituaREPO-OWNER
pelo nome da conta proprietária do repositório. SubstituaREPO-NAME
pelo nome do repositório.YAML on: workflow_dispatch: jobs: track_pr: runs-on: ubuntu-latest steps: - name: Generate token id: generate-token uses: actions/create-github-app-token@v1 with: app-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PEM }} - name: Use API env: GH_TOKEN: ${{ steps.generate-token.outputs.token }} run: | gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues
on: workflow_dispatch: jobs: track_pr: runs-on: ubuntu-latest steps: - name: Generate token id: generate-token uses: actions/create-github-app-token@v1 with: app-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PEM }} - name: Use API env: GH_TOKEN: ${{ steps.generate-token.outputs.token }} run: | gh api http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues
Como usar Octokit.js
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".
-
Crie um token de acesso. Por exemplo, crie um personal access token ou um token de acesso de usuário do GitHub App. Você usará esse token para autenticar sua solicitação, portanto, você deve conceder a ele todos os escopos ou permissões necessários para acessar esse ponto de extremidade. Para obter mais informações, consulte "Autenticação na API REST" ou "Como identificar e autorizar usuários para Aplicativos do 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 do CLI 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 do
Octokit
com o seu token. SubstituaHOSTNAME
pelo nome do sua instância do GitHub Enterprise Server. SubstituaYOUR-TOKEN
pelo seu token.JavaScript const octokit = new Octokit({ baseUrl: "http(s)://HOSTNAME/api/v3", auth: 'YOUR-TOKEN' });
const octokit = new Octokit({ baseUrl: "http(s)://HOSTNAME/api/v3", 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. Para obter mais informações sobre parâmetros, consulte "Introdução à API REST".Por exemplo, na solicitação a seguir, o método HTTP é
GET
, o caminho é/repos/{owner}/{repo}/issues
e os parâmetros sãoowner: "REPO-OWNER"
erepo: "REPO-NAME"
. SubstituaREPO-OWNER
pelo nome da conta proprietária do repositório eREPO-NAME
pelo nome do repositório.JavaScript await octokit.request("GET /repos/{owner}/{repo}/issues", { owner: "REPO-OWNER", repo: "REPO-NAME", });
await octokit.request("GET /repos/{owner}/{repo}/issues", { owner: "REPO-OWNER", repo: "REPO-NAME", });
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".
Autenticação com um token de acesso
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:
- 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
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 }}
Veja a seguir um exemplo de script do JavaScript com o caminho de arquivo .github/actions-scripts/use-the-api.mjs
. Substitua HOSTNAME
pelo nome de sua instância do GitHub Enterprise Server. Substitua REPO-OWNER
pelo nome da conta proprietária do repositório. Substitua REPO-NAME
pelo nome do repositório.
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}`)
}
Autenticação com um GitHub App
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 uma variável de configuração. No exemplo a seguir, substitua
APP_ID
pelo nome da variável de configuração. 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 "Pontos de extremidade da API REST para o GitHub Apps". Para saber mais sobre variáveis de configuração, confira "Armazenar informações em variáveis". -
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". Para obter mais informações sobre segredos, confira "Usar segredos em ações do 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: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: ${{ 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 }}
Como usar curl
na linha de comando
Observação: se você quiser fazer solicitações de API da linha de comando, o GitHub recomenda que você use 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 fornecer informações sobre a versão docurl
, isso significará que ocurl
está 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. Você usará esse token para autenticar sua solicitação, portanto, você deve conceder a ele todos os escopos ou permissões necessários para acessar o ponto de extremidade. Para obter mais informações, confira "Autenticação na API REST".
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 do CLI para armazenar seu token com segurança.
-
Use o comando
curl
para fazer sua solicitação. Passe o seu token em um cabeçalho deAuthorization
SubstituaHOSTNAME
pelo nome do sua instância do GitHub Enterprise Server. SubstituaREPO-OWNER
pelo nome da conta proprietária do repositório. SubstituaREPO-NAME
pelo nome do repositório. SubstituaYOUR-TOKEN
pelo seu token.Shell curl --request GET \ --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN"
curl --request GET \ --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/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.
Autenticação com um token de acesso
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".
No exemplo a seguir, substitua HOSTNAME
pelo nome do sua instância do GitHub Enterprise Server. Substitua REPO-OWNER
pelo nome da conta proprietária do repositório. Substitua REPO-NAME
pelo nome do repositório.
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"
Autenticação com um GitHub App
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 uma variável de configuração. No exemplo a seguir, substitua
APP_ID
pelo nome da variável de configuração. 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 "Pontos de extremidade da API REST para o GitHub Apps". Para saber mais sobre variáveis de configuração, confira "Armazenar informações em variáveis". -
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". Para saber mais sobre como armazenar segredos, confira "Usar segredos em ações do 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. no exemplo a seguir, substituaHOSTNAME
pelo nome do sua instância do GitHub Enterprise Server. SubstituaREPO-OWNER
pelo nome da conta proprietária do repositório. SubstituaREPO-NAME
pelo nome do repositório.YAML on: workflow_dispatch: jobs: use_api: runs-on: ubuntu-latest steps: - name: Generate token id: generate-token uses: actions/create-github-app-token@v1 with: app-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PEM }} - name: Use API env: GH_TOKEN: ${{ steps.generate-token.outputs.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 steps: - name: Generate token id: generate-token uses: actions/create-github-app-token@v1 with: app-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PEM }} - name: Use API env: GH_TOKEN: ${{ steps.generate-token.outputs.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"
Próximas etapas
Para obter um guia mais detalhado, confira "Introdução à API REST".