octokit.js
v4.0.2
El SDK GitHub, incluido en baterías para navegadores, Node.js y Deno.
El paquete octokit integra las tres bibliotecas principales de Octokit
Octokitoctokit.restoctokit.request()| Navegadores | Cargue octokit directamente desde Esm.sh < script type =" module " >
import { Octokit , App } from "https://esm.sh/octokit" ;
</ script > |
|---|---|
| Deno | Cargue octokit directamente desde Esm.sh import { Octokit , App } from "https://esm.sh/octokit?dts" ; |
| Nodo | Instalar con import { Octokit , App } from "octokit" ; |
Importante
A medida que utilizamos las exportaciones condicionales, deberá adaptar su tsconfig.json configurando "moduleResolution": "node16", "module": "node16" .
Consulte los documentos de TypeScript en el paquete.json "Exports".
Vea esta útil guía sobre la transición a ESM desde @sindresorhus
Octokit Octokit mínimo independiente : @octokit/core .
El cliente Octokit se puede usar para enviar solicitudes a la API REST de GitHub y consultas a la API GRAPHQL de GitHub.
Ejemplo : Obtenga el nombre de usuario para el usuario 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 ) ;Las opciones más utilizadas son
| nombre | tipo | descripción |
|---|---|---|
userAgent | String | Configuración de un agente de usuario es necesario para todas las solicitudes enviadas a las API de la plataforma de GitHub. El agente del usuario predetermina algo como esto: const octokit = new Octokit ( {
userAgent : "my-app/v1.2.3" ,
} ) ; |
authStrategy | Function | El valor predeterminado a Ver autenticación a continuación. |
auth | String u Object | Establecer en un token de acceso personal a menos que haya cambiado la opción Ver autenticación a continuación. |
baseUrl | String | Cuando se use con GitHub Enterprise Server, establezca const octokit = new Octokit ( {
baseUrl : "https://github.acme-inc.com/api/v3" ,
} ) ; |
Opciones avanzadas
| nombre | tipo | descripción |
|---|---|---|
request | Object |
Solo nodo
La opción |
timeZone | String | Establece el encabezado de const octokit = new Octokit ( {
timeZone : "America/Los_Angeles" ,
} ) ;El encabezado de la zona horaria determinará la zona horaria utilizada para generar la marca de tiempo al crear compromisos. Vea la documentación de las zonas horarias de GitHub. |
throttle | Object | Por defecto, las solicitudes se vuelven a conectar una vez y las advertencias se registran en el caso de alcanzar una tasa o límite de tasa secundaria. {
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 no participar en esta característica: new Octokit ( { throttle : { enabled : false } } ) ; El estrangulamiento en un clúster es compatible con un backend redis. Ver |
retry | Object | Para optar por no participar en esta característica: new Octokit ( { retry : { enabled : false } } ) ; |
Por defecto, el cliente API Octokit admite la autenticación utilizando un token estático.
Existen diferentes medios de autenticación que son compatibles con GitHub, que se describen en detalle en OCTOKIT/Autenticación-Strategies.js. Puede configurar cada uno de ellos como la opción authStrategy Constructor y pasar las opciones de estrategia como la opción de constructor auth .
Por ejemplo, para autenticarse como una instalación de la aplicación 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 ,
} ) ; Puede usar la App o los SDK OAuthApp que proporcionan API y cableado interno para cubrir la mayoría de los casos de uso.
Por ejemplo, para implementar la aplicación anterior 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 ,
} ) ;Obtenga más información sobre cómo funcionan las estrategias de autenticación o cómo crear las suyas propias.
De manera predeterminada, el cliente API Octokit no utiliza las variables de entorno de servidor proxy estándar. Para agregar soporte para servidores proxy, deberá proporcionar un cliente HTTPS que los admite como undici.ProxyAgent() .
Por ejemplo, esto usaría un ProxyAgent para realizar solicitudes a través de un 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
} ,
} ) ; Si está escribiendo un módulo que usa Octokit y está diseñado para ser utilizado por otras personas, debe asegurarse de que los consumidores puedan proporcionar un agente alternativo para su Octokit o como un parámetro para llamadas 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
} ,
} ) ; Si recibe el siguiente error:
La búsqueda no está configurada. Pase una implementación de Fetch como nuevo OctoKit ({Solicitud: {Fetch}}).
Probablemente significa que está tratando de ejecutar Octokit con una versión no compatible de NodeJS. Octokit requiere el nodo 18 o más, que incluye una API de Fetch nativa.
Para evitar este problema, puede proporcionar su propia implementación fetch (o una versión incorporada como node-fetch ) como esta:
import fetch from "node-fetch" ;
const octokit = new Octokit ( {
request : {
fetch : fetch ,
} ,
} ) ; Hay dos formas de usar la API REST GitHub, el octokit.rest.* Métodos de punto final y octokit.request . Ambos actúan de la misma manera, los métodos octokit.rest.* Se acaban de agregar por conveniencia, usan octokit.request internamente.
Por ejemplo
await octokit . rest . issues . create ( {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ;Es lo mismo que
await octokit . request ( "POST /repos/{owner}/{repo}/issues" , {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ; En ambos casos, una solicitud determinada se autentica, se refería y se estrangula transparentemente por la instancia octokit que también administra los encabezados de accept y user-agent según sea necesario.
octokit.request se puede usar para enviar solicitudes a otros dominios aprobando una URL completa y enviar solicitudes a puntos finales que no están (aún) documentados en la documentación de la API REST de GitHub.
octokit.rest Cada punto final de API REST de GitHub tiene un método asociado de punto octokit.rest . Consulte @octokit/plugin-rest-endpoint-methods para obtener detalles completos.
Ejemplo: crear un problema
await octokit . rest . issues . create ( {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ; Los métodos de punto final octokit.rest se generan automáticamente a partir de la especificación OpenAPI de GitHub. Rastizamos la ID de operación y los cambios en el nombre de los parámetros para implementar advertencias de deprecación y reducir la frecuencia de los cambios de ruptura.
Debajo de las cubiertas, cada método de punto final es solo octokit.request con los valores predeterminados establecidos, por lo que admite los mismos parámetros, así como la API .endpoint() .
octokit.request() Puede llamar a la API REST GitHub directamente usando octokit.request . La API request coincide con la documentación de la API REST de GitHub 1: 1, así que cualquier cosa que vea allí, puede llamar usando request . Consulte @octokit/request para todos los detalles.
Ejemplo: crear un problema
La llamada de API octokit.request correspondiente a ese problema de la documentación de creación se ve así:
// 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!" ,
} ) ;El primer argumento es la ruta API REST como se enumera en la documentación de la API de GitHub. El segundo argumento es un objeto con todos los parámetros, independientemente de si se usan en la ruta, consulta o cuerpo.
Todos los puntos finales de REST API que paginan devuelven los primeros 30 elementos de forma predeterminada. Si desea recuperar todos los artículos, puede usar la API de paginación. La API de la paginación espera la ruta REST API como primer argumento, pero también puede aprobar cualquiera de los octokit.rest.*.list* Métodos para conveniencia y mejor legibilidad de código.
Ejemplo: iterar a través de todos los problemas en un repositorio
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 ) ;
}
}Usar el iterador Async es la forma más eficiente de la memoria de iterar a través de todos los elementos. Pero también puede recuperar todos los artículos en una sola llamada
const issues = await octokit . paginate ( octokit . rest . issues . listForRepo , {
owner : "octocat" ,
repo : "hello-world" ,
per_page : 100 ,
} ) ; Los formatos de tipo de medios se pueden establecer usando mediaType: { format } en cada solicitud.
Ejemplo: recupere el contenido sin procesar de un archivo 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 ) ;Obtenga más información sobre los formatos de tipo de medios.
Módulo independiente: @octokit/request-error
Para el manejo de errores de solicitud, importe RequestError y use la declaración de 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 ;
}
} Octokit también admite la API GHITHUB GRAPHQL directamente: puede usar las mismas consultas que se muestran en la documentación y disponible en el Explorador GraphQL en sus llamadas con octokit.graphql .
Ejemplo: obtenga el inicio de sesión del usuario autenticado
const {
viewer : { login } ,
} = await octokit . graphql ( `{
viewer {
login
}
}` ) ;Las variables se pueden pasar 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" ,
} ,
) ; La API GRAPHQL de GitHub devuelve un máximo de 100 elementos. Si desea recuperar todos los artículos, puede usar la API de paginación.
Ejemplo: Obtenga todos los 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" ,
} ,
) ;Obtenga más información sobre el uso de Pagination Ghithub.
Las vistas previas se pueden habilitar usando la opción {mediaType: previews: [] } .
Ejemplo: crear una etiqueta
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" ] ,
} ,
} ,
) ;Obtenga más información sobre las vistas previas del esquema Github Ghithub
El cliente App combina funciones para aplicaciones GitHub, Webhooks y Oauth
Módulo independiente : @octokit/app
Para los integradores, las aplicaciones GitHub son un medio de autenticación y autorización. Una aplicación GitHub se puede registrar en una cuenta de usuario u organización de GitHub. Un registro de la aplicación GitHub define un conjunto de permisos y eventos de webhooks que desea recibir y proporciona un conjunto de credenciales a cambio. Los usuarios pueden otorgar acceso a repositorios instalándolos.
Algunos puntos finales de API requieren que la aplicación GitHub se autentique como él mismo utilizando un token web JSON (JWT). Para las solicitudes que afectan una instalación, se debe crear un token de acceso de instalación utilizando las credenciales de la aplicación y la ID de instalación.
El cliente App se encarga de todo eso por usted.
Ejemplo: enviar un evento de repositorio en cada repositorio La aplicación está instalada en
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 ) ;
} Ejemplo: obtenga una instancia octokit autenticada como una instalación
const octokit = await app . getInstallationOctokit ( 123 ) ;Obtenga más información sobre las aplicaciones.
Módulo independiente : @octokit/webhooks
Al instalar una aplicación, los eventos que las solicitudes de registro de la aplicación se enviarán como solicitudes a la URL de Webhook establecida en el registro de la aplicación.
Las solicitudes de eventos de Webhook se firman utilizando el secreto de Webhook, que también es parte del registro de la aplicación. Debe verificar ese secreto antes de manejar la carga útil de la solicitud.
Las app.webhooks.* Las API proporcionan métodos para recibir, verificar y manejar eventos webhook.
Ejemplo: crear un comentario sobre nuevos 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 entornos sin servidor, puede verificar explícitamente y recibir un 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 ,
} ) ;Obtenga más información sobre GitHub Webhooks.
Módulo independiente: @octokit/oauth-app
Tanto las aplicaciones de OAuth como las aplicaciones GitHub admiten autenticar a los usuarios de GitHub que usan OAuth, consulte Autorizar aplicaciones OAuth e identificar y autorizar a los usuarios para aplicaciones GitHub.
Hay algunas diferencias:
App es para aplicaciones GitHub. Si necesita una funcionalidad específica de la aplicación OAuth, use OAuthApp en su lugar.
Ejemplo: mire un repositorio cuando un usuario inicia sesión con el flujo web de 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 entornos sin servidor, puede intercambiar explícitamente el code desde la redirección de flujo web de OAuth para un token de acceso. app.oauth.createToken() devuelve un objeto de autenticación y emite el evento "token.created".
const { token } = await app . oauth . createToken ( {
code : request . query . code ,
} ) ;Ejemplo: cree un token usando el flujo del 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 } ` ,
) ;
} ,
} ) ;Ejemplo: cree un servidor de aplicaciones OAuth con alcances predeterminados
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 ) ;Después de registrar su aplicación GitHub, debe crear e implementar un servidor que pueda recuperar las solicitudes de eventos de Webhook de GitHub, así como aceptar redirecciones del flujo web de usuario OAuth.
La forma más sencilla de crear dicho servidor es usar createNodeMiddleware() , funciona con ambos, el método http.createServer() de Node, así como un middleware expreso.
Las rutas predeterminadas que expone el middleware son
| Ruta | Descripción de la ruta |
|---|---|
POST /api/github/webhooks | Punto final para recibir solicitudes de evento GitHub Webhook |
GET /api/github/oauth/login | Redirige al punto final de autorización de GitHub. Acepta parámetros de consulta opcional ?state y ?scopes ?scopes son una lista separada por comas de nombres de alcance Oauth compatibles |
GET /api/github/oauth/callback | El punto final de redirección del cliente. Aquí es donde se activa el evento token |
POST /api/github/oauth/token | Intercambie un código de autorización por un token de acceso OAuth. Si tiene éxito, el evento token se activa. |
GET /api/github/oauth/token | Compruebe si el token es válido. Debe autenticarse usando el token en el encabezado Authorization . Utiliza POST /applications/{client_id}/token Endpoint |
PATCH /api/github/oauth/token | Restablece un token (invalida actual, devuelve un nuevo token). Debe autenticarse usando el token en el encabezado Authorization . Utiliza PATCH /applications/{client_id}/token endpoint. |
PATCH /api/github/oauth/refresh-token | Actualiza un token expirado (invalida actual, devuelve un nuevo token de acceso y actualiza el token). Debe autenticarse usando el token en el encabezado Authorization . Utiliza POST https://github.com/login/oauth/access_token oauth endpoint. |
POST /api/github/oauth/token/scoped | Crea un token de alcance (no invalida el actual). Debe autenticarse usando el token en el encabezado Authorization . Utiliza POST /applications/{client_id}/token/scoped Endpoint. |
DELETE /api/github/oauth/token | Invalida el token actual, básicamente el equivalente de un inicio de sesión. Debe autenticarse usando el token en el encabezado Authorization . |
DELETE /api/github/oauth/grant | Revoca la subvención del usuario, básicamente el equivalente de una desinstalación. Debe autenticarse usando el token en el encabezado Authorization . |
Ejemplo: cree un servidor GitHub con Express
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` ) ;
} ) ; No debe exponer el secreto del cliente de su aplicación al usuario, por lo que no puede usar el constructor App . En su lugar, debe crear un servidor utilizando el constructor App que exponga las rutas /api/github/oauth/* , a través de las cuales puede implementar un inicio de sesión de OAuth para aplicaciones que se ejecutan en un navegador web.
Si establece (User) Authorization callback URL state app.oauthLoginUrl() propia aplicación, entonces necesita leer el code ?code=...&state=...
Si ejecuta un servidor de aplicaciones como se describió anteriormente, la ruta predeterminada para hacerlo es POST /api/github/oauth/token .
Una vez que recuperó con éxito el token, también se recomienda eliminar el ?code=...&state=...
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 trabajando en @octokit/auth-oauth-user-client para proporcionar una API simple para todos los métodos relacionados con los tokens de usuario OAuth.
El plan es agregar una nueva ruta GET /api/github/oauth/octokit.js al middleware del nodo que devolverá un archivo JavaScript que se puede importar a un archivo HTML. Hará que esté disponible una instancia octokit preautenticada.
Módulo independiente: @octokit/action
? Un cliente Action completamente incapaz está pendiente. Puedes usar @actions/github por el momento
MIT
