octokit.js
v4.0.2
O Github SDK incluído em todos os patrocinados para navegadores, Node.js e Deno.
O pacote octokit integra as três principais bibliotecas de outubro
Octokit API Clientoctokit.rest terminal Methodsoctokit.request()| Navegadores | Carregue octokit diretamente de Es.sh < script type =" module " >
import { Octokit , App } from "https://esm.sh/octokit" ;
</ script > |
|---|---|
| Deno | Carregue octokit diretamente de Es.sh import { Octokit , App } from "https://esm.sh/octokit?dts" ; |
| Nó | Instale com import { Octokit , App } from "octokit" ; |
Importante
À medida que usamos exportações condicionais, você precisará adaptar seu tsconfig.json definindo "moduleResolution": "node16", "module": "node16" .
Consulte os documentos datilografados no package.json "exportações".
Veja este guia útil sobre a transição para o ESM a partir de @sindresorhus
Octokit API Client OCTOKIT mínimo independente : @octokit/core .
O cliente Octokit pode ser usado para enviar solicitações para a API e consultas do GitHub para a API GraphQL do Github.
Exemplo : Obtenha o nome de usuário para o usuário autenticado.
// Create a personal access token at https://github.com/settings/tokens/new?scopes=repo
const octokit = new Octokit ( { auth : `personal-access-token123` } ) ;
// Compare: https://docs.github.com/en/rest/reference/users#get-the-authenticated-user
const {
data : { login } ,
} = await octokit . rest . users . getAuthenticated ( ) ;
console . log ( "Hello, %s" , login ) ;As opções mais usadas são
| nome | tipo | descrição |
|---|---|---|
userAgent | String | A definição de um agente do usuário é necessária para todas as solicitações enviadas para as APIs da plataforma do GitHub. O agente do usuário padrão é algo assim: const octokit = new Octokit ( {
userAgent : "my-app/v1.2.3" ,
} ) ; |
authStrategy | Function | Padrões para Veja a autenticação abaixo. |
auth | String ou Object | Defina como um token de acesso pessoal, a menos que você tenha alterado a opção Veja a autenticação abaixo. |
baseUrl | String | Ao usar com o GitHub Enterprise Server, defina const octokit = new Octokit ( {
baseUrl : "https://github.acme-inc.com/api/v3" ,
} ) ; |
Opções avançadas
| nome | tipo | descrição |
|---|---|---|
request | Object |
Nó apenas
A opção |
timeZone | String | Define o cabeçalho const octokit = new Octokit ( {
timeZone : "America/Los_Angeles" ,
} ) ;O cabeçalho do fuso horário determinará o fuso horário usado para gerar o registro de data e hora ao criar compromissos. Consulte a documentação dos fusos horários do Github. |
throttle | Object | Por padrão, as solicitações são tentadas uma vez e os avisos são registrados em caso de atingir uma taxa ou limite de taxa secundária. {
onRateLimit : ( retryAfter , options , octokit ) => {
octokit . log . warn (
`Request quota exhausted for request ${ options . method } ${ options . url } `
) ;
if ( options . request . retryCount === 0 ) {
// only retries once
octokit . log . info ( `Retrying after ${ retryAfter } seconds!` ) ;
return true ;
}
} ,
onSecondaryRateLimit : ( retryAfter , options , octokit ) => {
octokit . log . warn (
`SecondaryRateLimit detected for request ${ options . method } ${ options . url } `
) ;
if ( options . request . retryCount === 0 ) {
// only retries once
octokit . log . info ( `Retrying after ${ retryAfter } seconds!` ) ;
return true ;
}
} ,
} ;Para optar por não ter esse recurso: new Octokit ( { throttle : { enabled : false } } ) ; A estacas em um cluster é suportada usando um back -end do Redis. Veja o cluster |
retry | Object | Para optar por não ter esse recurso: new Octokit ( { retry : { enabled : false } } ) ; |
Por padrão, o cliente da Octokit API suporta autenticação usando um token estático.
Existem diferentes meios de autenticação suportados pelo GitHub, que são descritos em detalhes em Octokit/Authentication-Strategies.js. Você pode definir cada um deles como a opção authStrategy Constructor e aprovar as opções de estratégia como a opção auth Constructor.
Por exemplo, para se autenticar como uma instalação do aplicativo Github:
import { createAppAuth } from "@octokit/auth-app" ;
const octokit = new Octokit ( {
authStrategy : createAppAuth ,
auth : {
appId : 1 ,
privateKey : "-----BEGIN PRIVATE KEY-----n..." ,
installationId : 123 ,
} ,
} ) ;
// authenticates as app based on request URLs
const {
data : { slug } ,
} = await octokit . rest . apps . getAuthenticated ( ) ;
// creates an installation access token as needed
// assumes that installationId 123 belongs to @octocat, otherwise the request will fail
await octokit . rest . issues . create ( {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello world from " + slug ,
} ) ; Você pode usar o App ou OAuthApp SDKs que fornecem APIs e fiação interna para cobrir a maioria dos casos de uso.
Por exemplo, para implementar o acima usando App
const app = new App ( { appId , privateKey } ) ;
const { data : slug } = await app . octokit . rest . apps . getAuthenticated ( ) ;
const octokit = await app . getInstallationOctokit ( 123 ) ;
await octokit . rest . issues . create ( {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello world from " + slug ,
} ) ;Saiba mais sobre como as estratégias de autenticação funcionam ou como criar o seu próprio.
Por padrão, o cliente da Octokit API não utiliza as variáveis de ambiente de servidor proxy padrão. Para adicionar suporte para servidores proxy, você precisará fornecer um cliente HTTPS que os suporte, como undici.ProxyAgent() .
Por exemplo, isso usaria um ProxyAgent para fazer solicitações por meio de um servidor proxy:
import { fetch as undiciFetch , ProxyAgent } from 'undici' ;
const myFetch = ( url , options ) => {
return undiciFetch ( url , {
... options ,
dispatcher : new ProxyAgent ( < your_proxy_url > )
} )
}
const octokit = new Octokit ( {
request : {
fetch : myFetch
} ,
} ) ; Se você está escrevendo um módulo que usa Octokit e foi projetado para ser usado por outras pessoas, verifique se os consumidores podem fornecer um agente alternativo para o seu Octokit ou como um parâmetro para chamadas específicas, como:
import { fetch as undiciFetch , ProxyAgent } from 'undici' ;
const myFetch = ( url , options ) => {
return undiciFetch ( url , {
... options ,
dispatcher : new ProxyAgent ( < your_proxy_url > )
} )
}
octokit . rest . repos . get ( {
owner ,
repo ,
request : {
fetch : myFetch
} ,
} ) ; Se você receber o seguinte erro:
buscar não está definido. Por favor, passe uma implementação de busca como novo OCTOKIT ({request: {fetch}}).
Provavelmente significa que você está tentando executar o Octokit com uma versão não suportada do NodeJS. Octokit requer o nó 18 ou superior, que inclui uma API de busca nativa.
Para ignorar esse problema, você pode fornecer sua própria implementação fetch (ou uma versão interna como node-fetch ) como esta:
import fetch from "node-fetch" ;
const octokit = new Octokit ( {
request : {
fetch : fetch ,
} ,
} ) ; Existem duas maneiras de usar a API REST GitHub, o octokit.rest.* Métodos de endpoint e octokit.request . Ambos agem da mesma maneira, os métodos octokit.request octokit.rest.*
Por exemplo
await octokit . rest . issues . create ( {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ;É o mesmo que
await octokit . request ( "POST /repos/{owner}/{repo}/issues" , {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ; Em ambos os casos, uma determinada solicitação é autenticada, reconstruída e eliminada de forma transparente pela instância octokit , que também gerencia os cabeçalhos accept e user-agent , conforme necessário.
octokit.request pode ser usado para enviar solicitações para outros domínios, passando um URL completo e para enviar solicitações para pontos de extremidade que ainda não estão (ainda) documentados na documentação da API REST do Github.
octokit.rest terminal Methods Todo endpoint da API Rest GitHub possui um método de endpoint octokit.rest associado. Consulte @octokit/plugin-rest-endpoint-methods para obter detalhes completos.
Exemplo: Crie um problema
await octokit . rest . issues . create ( {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ; Os métodos de endpoint de octokit.rest são gerados automaticamente a partir da especificação OpenAPI do GitHub. Rastreamos as alterações do ID da operação e do nome do parâmetro para implementar avisos de depreciação e reduzir a frequência das mudanças de quebra.
Sob as capas, todo o método .endpoint() terminal é apenas octokit.request
octokit.request() Você pode ligar para a API REST GitHub diretamente usando octokit.request . A API request corresponde à documentação da API do GitHub 1: 1 para que qualquer coisa que você veja lá, você pode ligar usando request . Veja @octokit/request para todos os detalhes.
Exemplo: Crie um problema
A chamada da API octokit.request , correspondente a essa questão, a documentação da criação se parece com a seguinte:
// https://docs.github.com/en/rest/reference/issues#create-an-issue
await octokit . request ( "POST /repos/{owner}/{repo}/issues" , {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ;O primeiro argumento é a rota da API REST, conforme listado na documentação da API do Github. O segundo argumento é um objeto com todos os parâmetros, independentemente de serem usados no caminho, consulta ou corpo.
Todos os pontos de extremidade da API REST que paginam retornam os 30 primeiros itens por padrão. Se você deseja recuperar todos os itens, pode usar a API de paginação. A API da paginação espera a rota da API REST como primeiro argumento, mas você também pode passar em qualquer um dos métodos octokit.rest.*.list* Para conveniência e melhor legibilidade do código.
Exemplo: itera através de todas as questões em um repositório
const iterator = octokit . paginate . iterator ( octokit . rest . issues . listForRepo , {
owner : "octocat" ,
repo : "hello-world" ,
per_page : 100 ,
} ) ;
// iterate through each response
for await ( const { data : issues } of iterator ) {
for ( const issue of issues ) {
console . log ( "Issue #%d: %s" , issue . number , issue . title ) ;
}
}O uso do iterador assíncrono é a maneira mais eficiente da memória de iterar em todos os itens. Mas você também pode recuperar todos os itens em uma única chamada
const issues = await octokit . paginate ( octokit . rest . issues . listForRepo , {
owner : "octocat" ,
repo : "hello-world" ,
per_page : 100 ,
} ) ; Os formatos de tipo de mídia podem ser definidos usando mediaType: { format } em todas as solicitações.
Exemplo: recuperar o conteúdo bruto de um arquivo package.json
const { data } = await octokit . rest . repos . getContent ( {
mediaType : {
format : "raw" ,
} ,
owner : "octocat" ,
repo : "hello-world" ,
path : "package.json" ,
} ) ;
console . log ( "package name: %s" , JSON . parse ( data ) . name ) ;Saiba mais sobre os formatos de tipo de mídia.
Módulo independente: @octokit/request-error
Para solicitar manipulação de erros, importe RequestError e use a instrução try...catch .
import { RequestError } from "octokit" ; try {
// your code here that sends at least one Octokit request
await octokit . request ( "GET /" ) ;
} catch ( error ) {
// Octokit errors are instances of RequestError, so they always have an `error.status` property containing the HTTP response code.
if ( error instanceof RequestError ) {
// handle Octokit error
// error.message; // Oops
// error.status; // 500
// error.request; // { method, url, headers, body }
// error.response; // { url, status, headers, data }
} else {
// handle all other errors
throw error ;
}
} O Octokit também suporta diretamente a API do Github's GraphQL - você pode usar as mesmas consultas mostradas na documentação e disponível no GraphQL Explorer em suas chamadas com octokit.graphql .
Exemplo: Obtenha o login do usuário autenticado
const {
viewer : { login } ,
} = await octokit . graphql ( `{
viewer {
login
}
}` ) ;Variáveis podem ser passadas como segundo argumento
const { lastIssues } = await octokit . graphql (
`
query lastIssues($owner: String!, $repo: String!, $num: Int = 3) {
repository(owner: $owner, name: $repo) {
issues(last: $num) {
edges {
node {
title
}
}
}
}
}
` ,
{
owner : "octokit" ,
repo : "graphql.js" ,
} ,
) ; A API GraphQL do Github retorna no máximo 100 itens. Se você deseja recuperar todos os itens, pode usar a API de paginação.
Exemplo: obtenha todos os problemas
const { allIssues } = await octokit . graphql . paginate (
`
query allIssues($owner: String!, $repo: String!, $num: Int = 10, $cursor: String) {
repository(owner: $owner, name: $repo) {
issues(first: $num, after: $cursor) {
edges {
node {
title
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
` ,
{
owner : "octokit" ,
repo : "graphql.js" ,
} ,
) ;Saiba mais sobre o uso da paginação grafql do Github.
As visualizações podem ser ativadas usando a opção {mediaType: previews: [] } .
Exemplo: Crie um rótulo
await octokit . graphql (
`mutation createLabel($repositoryId:ID!,name:String!,color:String!) {
createLabel(input:{repositoryId:$repositoryId,name:$name}) {
label: {
id
}
}
}` ,
{
repositoryId : 1 ,
name : "important" ,
color : "cc0000" ,
mediaType : {
previews : [ "bane" ] ,
} ,
} ,
) ;Saiba mais sobre as visualizações de esquema do Github's GraphQL
O App Client combina recursos para aplicativos Github, Webhooks e OAuth
Módulo independente : @octokit/app
Para os integradores, os aplicativos do GitHub são um meio de autenticação e autorização. Um aplicativo Github pode ser registrado em uma conta do usuário ou organização do GitHub. Um registro de aplicativos do GitHub define um conjunto de permissões e eventos de webhooks que deseja receber e fornece um conjunto de credenciais em troca. Os usuários podem conceder acesso a repositórios instalando -os.
Alguns terminais da API exigem que o aplicativo GitHub se autentique como ele mesmo usando um token da Web JSON (JWT). Para solicitações que afetam uma instalação, um token de acesso à instalação deve ser criado usando as credenciais do aplicativo e o ID da instalação.
O cliente App cuida de tudo isso para você.
Exemplo: Despacha um evento de repositório em todos os repositórios em que o aplicativo é instalado em
import { App } from "octokit" ;
const app = new App ( { appId , privateKey } ) ;
for await ( const { octokit , repository } of app . eachRepository . iterator ( ) ) {
// https://docs.github.com/en/rest/reference/repos#create-a-repository-dispatch-event
await octokit . rest . repos . createDispatchEvent ( {
owner : repository . owner . login ,
repo : repository . name ,
event_type : "my_event" ,
client_payload : {
foo : "bar" ,
} ,
} ) ;
console . log ( "Event dispatched for %s" , repository . full_name ) ;
} Exemplo: Obtenha uma instância octokit autenticada como uma instalação
const octokit = await app . getInstallationOctokit ( 123 ) ;Saiba mais sobre aplicativos.
Módulo independente : @octokit/webhooks
Ao instalar um aplicativo, os eventos que as solicitações de registro de aplicativos serão enviados como solicitações para o URL do webhook definido no registro do aplicativo.
As solicitações de eventos do Webhook são assinadas usando o segredo do Webhook, que também faz parte do registro do aplicativo. Você deve verificar esse segredo antes de lidar com a carga útil da solicitação.
As APIs app.webhooks.* APIs fornecem métodos para receber, verificar e lidar com eventos da webhook.
Exemplo: Crie um comentário sobre novos problemas
import { createServer } from "node:http" ;
import { App , createNodeMiddleware } from "octokit" ;
const app = new App ( {
appId ,
privateKey ,
webhooks : { secret } ,
} ) ;
app . webhooks . on ( "issues.opened" , ( { octokit , payload } ) => {
return octokit . rest . issues . createComment ( {
owner : payload . repository . owner . login ,
repo : payload . repository . name ,
issue_number : payload . issue . number ,
body : "Hello, World!" ,
} ) ;
} ) ;
// Your app can now receive webhook events at `/api/github/webhooks`
createServer ( createNodeMiddleware ( app ) ) . listen ( 3000 ) ;Para ambientes sem servidor, você pode verificar explicitamente e receber um evento
await app . webhooks . verifyAndReceive ( {
id : request . headers [ "x-github-delivery" ] ,
name : request . headers [ "x-github-event" ] ,
signature : request . headers [ "x-hub-signature-256" ] ,
payload : request . body ,
} ) ;Saiba mais sobre o Github Webhooks.
Módulo independente: @octokit/oauth-app
Os aplicativos OAuth e os aplicativos GitHub suportam autenticação de usuários do GitHub usando o OAuth, consulte Autorizando aplicativos OAuth e identificando e autorizando usuários para aplicativos do GitHub.
Existem algumas diferenças:
App é para aplicativos GitHub. Se você precisar da funcionalidade específica do aplicativo OAuth, use OAuthApp .
Exemplo: assista a um repositório quando um usuário faz login usando o fluxo da web do OAuth
import { createServer } from "node:http" ;
import { App , createNodeMiddleware } from "octokit" ;
const app = new App ( {
oauth : { clientId , clientSecret } ,
} ) ;
app . oauth . on ( "token.created" , async ( { token , octokit } ) => {
await octokit . rest . activity . setRepoSubscription ( {
owner : "octocat" ,
repo : "hello-world" ,
subscribed : true ,
} ) ;
} ) ;
// Your app can receive the OAuth redirect at /api/github/oauth/callback
// Users can initiate the OAuth web flow by opening /api/github/oauth/login
createServer ( createNodeMiddleware ( app ) ) . listen ( 3000 ) ; Para ambientes sem servidor, você pode trocar explicitamente o code do redirecionamento do fluxo da Web OAuth por um token de acesso. app.oauth.createToken() retorna um objeto de autenticação e emite o evento "Token.created".
const { token } = await app . oauth . createToken ( {
code : request . query . code ,
} ) ;Exemplo: Crie um token usando o fluxo do dispositivo.
const { token } = await app . oauth . createToken ( {
async onVerification ( verification ) {
await sendMessageToUser (
request . body . phoneNumber ,
`Your code is ${ verification . user_code } . Enter it at ${ verification . verification_uri } ` ,
) ;
} ,
} ) ;Exemplo: Crie um servidor de aplicativos OAuth com escopos padrão
import { createServer } from "node:http" ;
import { OAuthApp , createNodeMiddleware } from "octokit" ;
const app = new OAuthApp ( {
clientId ,
clientSecret ,
defaultScopes : [ "repo" , "gist" ] ,
} ) ;
app . oauth . on ( "token" , async ( { token , octokit } ) => {
await octokit . rest . gists . create ( {
description : "I created this gist using Octokit!" ,
public : true ,
files : {
"example.js" : `/* some code here */` ,
} ,
} ) ;
} ) ;
// Your app can receive the OAuth redirect at /api/github/oauth/callback
// Users can initiate the OAuth web flow by opening /api/oauth/login
createServer ( createNodeMiddleware ( app ) ) . listen ( 3000 ) ;Depois de registrar seu aplicativo Github, você precisa criar e implantar um servidor que possa recuperar as solicitações de eventos do Webhook do GitHub e aceitar redirecionamentos do fluxo da web do usuário do OAuth.
A maneira mais simples de criar um servidor desse tipo é usar createNodeMiddleware() , ele funciona com ambos, o método http.createServer() do Node, bem como um middleware expresso.
As rotas padrão que o middleware expõe são
| Rota | Descrição da rota |
|---|---|
POST /api/github/webhooks | Endpoint para receber solicitações de eventos do Github Webhook |
GET /api/github/oauth/login | Redireciona para o terminal de autorização do Github. Aceita parâmetros opcionais de consulta ?state e ?scopes . ?scopes é uma lista separada por vírgula de nomes de escopo OAuth suportados |
GET /api/github/oauth/callback | O terminal de redirecionamento do cliente. É aqui que o evento token é acionado |
POST /api/github/oauth/token | Trocar um código de autorização por um token de acesso OAuth. Se for bem -sucedido, o evento token é acionado. |
GET /api/github/oauth/token | Verifique se o token é válido. Deve autenticar usando o token no cabeçalho Authorization . Usa POST /applications/{client_id}/token Endpoint |
PATCH /api/github/oauth/token | Redefina um token (invalida o atual, retorna um novo token). Deve autenticar usando o token no cabeçalho Authorization . Usa PATCH /applications/{client_id}/token endpoint. |
PATCH /api/github/oauth/refresh-token | Atualize um token expirador (invalida o atual, retorna novos token de acesso e atualizar token). Deve autenticar usando o token no cabeçalho Authorization . Usa POST https://github.com/login/oauth/access_token oauth endpoint. |
POST /api/github/oauth/token/scoped | Cria um token escopo (não invalida o atual). Deve autenticar usando o token no cabeçalho Authorization . Usa POST /applications/{client_id}/token/scoped endpoint. |
DELETE /api/github/oauth/token | Invalida o token atual, basicamente o equivalente a um logout. Deve autenticar usando o token no cabeçalho Authorization . |
DELETE /api/github/oauth/grant | Revoga a concessão do usuário, basicamente o equivalente a uma desinstalação. deve autenticar usando o token no cabeçalho Authorization . |
Exemplo: Crie um servidor github com expresso
import express from "express" ;
import { App , createNodeMiddleware } from "octokit" ;
const expressApp = express ( ) ;
const octokitApp = new App ( {
appId ,
privateKey ,
webhooks : { secret } ,
oauth : { clientId , clientSecret } ,
} ) ;
expressApp . use ( createNodeMiddleware ( app ) ) ;
expressApp . listen ( 3000 , ( ) => {
console . log ( `Example app listening at http://localhost:3000` ) ;
} ) ; Você não deve expor o segredo do cliente do seu aplicativo ao usuário, para que você não possa usar o construtor App . Em vez disso, você deve criar um servidor usando o construtor App que expõe as rotas /api/github/oauth/* , através das quais você pode implementar com segurança um login OAuth para aplicativos em execução em um navegador da web.
Se você definir (User) Authorization callback URL para seu próprio aplicativo, você precisa ler o ?code=...&state=... Parâmetros de consulta, compare o parâmetro state com o valor retornado pelo app.oauthLoginUrl() anteriormente para proteger contra ataques de falsificação, trocam o code por um token de autorização OAuth.
Se você executar um servidor de aplicativos, conforme descrito acima, a rota padrão para fazer isso é POST /api/github/oauth/token .
Depois de recuperar o token com sucesso, também é recomendável remover o ?code=...&state=... parâmetros de consulta do URL do navegador
const code = new URL ( location . href ) . searchParams . get ( "code" ) ;
if ( code ) {
// remove ?code=... from URL
const path =
location . pathname +
location . search . replace ( / b(code|state)=w+ / g , "" ) . replace ( / [?&]+$ / , "" ) ;
history . replaceState ( { } , "" , path ) ;
// exchange the code for a token with your backend.
// If you use https://github.com/octokit/oauth-app.js
// the exchange would look something like this
const response = await fetch ( "/api/github/oauth/token" , {
method : "POST" ,
headers : {
"content-type" : "application/json" ,
} ,
body : JSON . stringify ( { code } ) ,
} ) ;
const { token } = await response . json ( ) ;
// `token` is the OAuth Access Token that can be use
const { Octokit } = await import ( "https://esm.sh/@octokit/core" ) ;
const octokit = new Octokit ( { auth : token } ) ;
const {
data : { login } ,
} = await octokit . request ( "GET /user" ) ;
alert ( "Hi there, " + login ) ;
} ? Estamos trabalhando no @octokit/auth-oauth-user-client para fornecer uma API simples para todos os métodos relacionados aos tokens de usuário da OAuth.
O plano é adicionar uma nova rota GET /api/github/oauth/octokit.js para o middleware do nó que retornará um arquivo JavaScript que pode ser importado para um arquivo HTML. Ele disponibilizará uma instância octokit pré-autenticada.
Módulo independente: @octokit/action
? Um cliente Action de pleno pleno está pendente. Você pode usar @actions/github por enquanto
Mit
