octokit.js
v4.0.2
All-Batheries, включающие GitHub SDK для браузеров, node.js и deno.
Пакет octokit объединяет три основных библиотеки Octokit
Octokit api клиентoctokit.rest Методы конечной точкиoctokit.request()| Браузеры | Загрузите octokit непосредственно с Esm.sh < script type =" module " >
import { Octokit , App } from "https://esm.sh/octokit" ;
</ script > |
|---|---|
| Дено | Загрузите octokit непосредственно с Esm.sh import { Octokit , App } from "https://esm.sh/octokit?dts" ; |
| Узел | Установите с помощью import { Octokit , App } from "octokit" ; |
Важный
Поскольку мы используем условный экспорт, вам нужно будет адаптировать свой tsconfig.json , установив "moduleResolution": "node16", "module": "node16" .
См. Typescript Docs на package.json "Экспорт".
Смотрите это полезное руководство по переходу на ESM с @sindresorhus
Octokit api клиент Автономный минимальный Octokit : @octokit/core .
Клиент Octokit может использоваться для отправки запросов в API и запросы GitHub Rest в API Github Github.
Пример : получить имя пользователя для аутентифицированного пользователя.
// 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 ) ;Наиболее часто используемые варианты
| имя | тип | описание |
|---|---|---|
userAgent | String | Установка пользовательского агента требуется для всех запросов, отправленных на API платформы GitHub. Пользователь по умолчанию по умолчанию примерно так: const octokit = new Octokit ( {
userAgent : "my-app/v1.2.3" ,
} ) ; |
authStrategy | Function | По умолчанию Смотрите аутентификацию ниже. |
auth | String или Object | Установите на личный токен доступа, если вы не изменили опцию Смотрите аутентификацию ниже. |
baseUrl | String | При использовании с GitHub Enterprise Server установите const octokit = new Octokit ( {
baseUrl : "https://github.acme-inc.com/api/v3" ,
} ) ; |
Расширенные варианты
| имя | тип | описание |
|---|---|---|
request | Object |
Только узел
Опция |
timeZone | String | Устанавливает заголовок const octokit = new Octokit ( {
timeZone : "America/Los_Angeles" ,
} ) ;Заголовок часового пояса будет определять часовой построй, используемый для создания временной метки при создании коммитов. Смотрите документацию Github's TimeZone. |
throttle | Object | По умолчанию запросы пересматриваются один раз, а предупреждения регистрируются в случае достижения уровня или вторичного ограничения. {
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 ;
}
} ,
} ;Чтобы отказаться от этой функции: new Octokit ( { throttle : { enabled : false } } ) ; Дроить в кластере поддерживается с использованием бэкэнда Redis. Смотрите |
retry | Object | Чтобы отказаться от этой функции: new Octokit ( { retry : { enabled : false } } ) ; |
По умолчанию клиент API Octokit поддерживает аутентификацию с использованием статического токена.
Существуют различные средства аутентификации, которые поддерживаются GitHub, которые подробно описаны в Octokit/Authentication-strategies.js. Вы можете установить каждый из них в качестве опции конструктора authStrategy и передать параметры стратегии в качестве опции конструктора auth .
Например, для проверки подлинности в качестве установки приложения 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 ,
} ) ; Вы можете использовать App или SDK OAuthApp , которые обеспечивают API и внутреннюю проводку, чтобы покрыть большинство вариантов использования.
Например, для реализации вышеупомянутого 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 ,
} ) ;Узнайте больше о том, как работают стратегии аутентификации или как создать свои собственные.
По умолчанию клиент API Octokit не использует стандартные переменные среды прокси -сервера. Чтобы добавить поддержку прокси -серверов, вам необходимо предоставить HTTPS -клиент, который поддерживает их, такой как undici.ProxyAgent() .
Например, это будет использовать ProxyAgent для выполнения запросов через прокси -сервер:
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
} ,
} ) ; Если вы пишете модуль, который использует Octokit и предназначен для использования другими людьми, вы должны убедиться, что потребители могут предоставить альтернативный агент для вашего Octokit или в качестве параметра для конкретных вызовов, таких как:
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
} ,
} ) ; Если вы получите следующую ошибку:
Фетч не установлен. Пожалуйста, передайте реализацию Fetch как новый Octokit ({запрос: {fetch}}).
Это, вероятно, означает, что вы пытаетесь запустить Octokit с неподдерживаемой версией Nodejs. Octokit требует узла 18 или выше, что включает в себя нативный API.
Чтобы обойти эту проблему, вы можете предоставить свою собственную fetch (или встроенную версию, такую как node-fetch ), например:
import fetch from "node-fetch" ;
const octokit = new Octokit ( {
request : {
fetch : fetch ,
} ,
} ) ; Есть два способа использования API GitHub Rest, octokit.rest.* Методы конечной точки и octokit.request . Оба действуют одинаково, octokit.rest.* Методы просто добавляются для удобства, они используют octokit.request внутри.
Например
await octokit . rest . issues . create ( {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ;Так же, как
await octokit . request ( "POST /repos/{owner}/{repo}/issues" , {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ; В обоих случаях заданный запрос аутентифицируется, пересмотрен и прозрачно запускается экземпляром octokit , который также управляет заголовками accept и user-agent по мере необходимости.
octokit.request может использоваться для отправки запросов в другие домены, передавая полный URL и отправил запросы на конечные точки, которые (пока) не задокументированы в документации GitHub Resi.
octokit.rest Методы конечной точки Каждая конечная точка API GitHub REST имеет соответствующий метод конечной точки octokit.rest для лучшей читаемости кода и удобства разработчика. См. @octokit/plugin-rest-endpoint-methods для получения полной информации.
Пример: создать проблему
await octokit . rest . issues . create ( {
owner : "octocat" ,
repo : "hello-world" ,
title : "Hello, world!" ,
body : "I created this issue using Octokit!" ,
} ) ; Методы конечной точки octokit.rest автоматически генерируются из спецификации GitHub OpenAPI. Мы отслеживаем изменения имени операции и имени параметра, чтобы реализовать предупреждения об испаке и уменьшить частоту нарушений изменений.
В соответствии с обложками каждый метод конечной точки - это всего лишь octokit.request с установленными значениями по умолчанию, поэтому он поддерживает те же параметры, а также API .endpoint() .
octokit.request() Вы можете позвонить в API GitHub Rest напрямую, используя octokit.request . API request соответствует документации Github Rest API 1: 1, поэтому все, что вы видите там, вы можете позвонить, используя request . Смотрите @octokit/request на все детали.
Пример: создать проблему
Коллект octokit.request api, соответствующий документации по созданию этой проблемы, выглядит следующим образом:
// 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!" ,
} ) ;1 -й аргумент - это маршрут API REST, указанный в документации GitHub's API. 2 -й аргумент - это объект со всеми параметрами, независимо от того, используются ли они на пути, запросе или теле.
Все конечные точки API REST, которые странит, возвращают первые 30 элементов по умолчанию. Если вы хотите получить все элементы, вы можете использовать API страниц. Pagination API ожидает маршрута API REST в качестве первого аргумента, но вы также можете передать любой из octokit.rest.*.list* методов для удобства и лучшей читаемости кода.
Пример: вытекать через все вопросы в репозитории
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 ) ;
}
}Использование асинхронного итератора - самый эффективный способ итерации по всем элементам. Но вы также можете получить все элементы за один звонок
const issues = await octokit . paginate ( octokit . rest . issues . listForRepo , {
owner : "octocat" ,
repo : "hello-world" ,
per_page : 100 ,
} ) ; Форматы типа мультимедиа могут быть установлены с использованием mediaType: { format } по каждому запросу.
Пример: получить необработанное содержание файла 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 ) ;Узнайте больше о форматах медиа.
Автономный модуль: @octokit/request-error
Для обработки ошибок запроса импортируйте RequestError и используйте оператор 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 также поддерживает API GithQL GraphQL от GitHub - вы можете использовать те же запросы, указанные в документации, и доступны в GraphQL Explorer в ваших вызовах с octokit.graphql .
Пример: получить вход в систему аутентифицированного пользователя
const {
viewer : { login } ,
} = await octokit . graphql ( `{
viewer {
login
}
}` ) ;Переменные могут быть переданы как 2 -й аргумент
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" ,
} ,
) ; Github GraphQL API возвращает максимум 100 пунктов. Если вы хотите получить все элементы, вы можете использовать API страниц.
Пример: получить все проблемы
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" ,
} ,
) ;Узнайте больше об использовании Github GraphQL Pagination.
Предварительные просмотра могут быть включены с использованием опции {mediaType: previews: [] } .
Пример: создать этикетку
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" ] ,
} ,
} ,
) ;Узнайте больше о предварительном просмотре схемы Github GraphQL
Клиент App объединяет функции для приложений GitHub, Webhooks и OAuth
Автономный модуль : @octokit/app
Для интеграторов приложения GitHub являются средством аутентификации и авторизации. Приложение GitHub может быть зарегистрировано в учетной записи пользователя или организации GitHub. Регистрация приложения GitHub определяет набор разрешений и событий Webhooks, которые они хотят получить, и предоставляет набор учетных данных взамен. Пользователи могут предоставить доступ к репозиториям, установив их.
Некоторые конечные точки API требуют, чтобы приложение GitHub провела подлинность как само по себе, используя веб -токен JSON (JWT). Для запросов, влияющих на установку, необходимо создать токен доступа к установке с использованием учетных данных приложения и идентификатора установки.
Клиент App заботится обо всем этом для вас.
Пример: отправьте событие репозитория в каждом хранилище, на котором установлено приложение
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 ) ;
} Пример: получить экземпляр octokit , аутентифицированный как установка
const octokit = await app . getInstallationOctokit ( 123 ) ;Узнайте больше о приложениях.
Автономный модуль : @octokit/webhooks
При установке приложения события, которые запросы на регистрацию приложений будут отправлены в качестве запросов на URL -адрес Webhook, установленную в регистрации приложения.
Запросы на мероприятия Webhook подписаны с использованием секрета Webhook, который также является частью регистрации приложения. Вы должны проверить этот секрет перед обработкой полезной нагрузки запроса.
app.webhooks.* API предоставляют методы для получения, проверки и обработки событий WebHook.
Пример: создайте комментарий по новым вопросам
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 ) ;Для средств без серверов вы можете явно проверить и получить событие
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 ,
} ) ;Узнайте больше о Github Webhooks.
Автономный модуль: @octokit/oauth-app
Как приложения OAuth, так и приложения GitHub поддерживают аутентификацию пользователей GitHub, используя OAuth, см. Авторизация приложений OAuth и определение и авторизацию пользователей для приложений GitHub.
Есть некоторые различия:
App для приложений GitHub. Если вам нужна функциональность OAuth, специфичная для приложения, используйте вместо этого OAuthApp .
Пример: посмотрите репозиторий, когда пользователь входит в систему, используя веб -поток 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 ) ; Для среды без серверов вы можете явно обменять code из перенаправления веб -потока OAuth на токен доступа. app.oauth.createToken() возвращает объект аутентификации и издает событие «token.created».
const { token } = await app . oauth . createToken ( {
code : request . query . code ,
} ) ;Пример: создайте токен, используя поток устройства.
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 } ` ,
) ;
} ,
} ) ;Пример: создать сервер приложений OAuth с по умолчанию
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 ) ;После регистрации вашего приложения GitHub вам необходимо создать и развернуть сервер, который может извлечь запросы на событие WebHook от GitHub, а также принять перенаправления из пользовательского потока OAuth.
Самый простой способ создания такого сервера - использовать createNodeMiddleware() , он работает с обоими методом http.createServer() Node.
Маршруты по умолчанию, которые разоблачает промежуточное программное обеспечение
| Маршрут | Описание маршрута |
|---|---|
POST /api/github/webhooks | Конечная точка для получения запросов на мероприятие GitHub Webhook |
GET /api/github/oauth/login | Перенаправление в конечную точку авторизации GitHub. Принимает необязательные ?state и ?scopes ?scopes -это разделенный запятой список поддерживаемых имен OAuth Scope |
GET /api/github/oauth/callback | Клиент перенаправляет конечная точка. Вот где инициируется событие token |
POST /api/github/oauth/token | Обмен код авторизации на токен доступа OAUTH. В случае успеха, событие token запускается. |
GET /api/github/oauth/token | Проверьте, действителен ли токен. Должен аутентифицировать использование токена в заголовке Authorization . Использует Github's POST /applications/{client_id}/token конечная точка |
PATCH /api/github/oauth/token | Сбрасывает токен (аниверситет текущий, возвращает новый токен). Должен аутентифицировать использование токена в заголовке Authorization . Использует PATCH /applications/{client_id}/token конечная точка. |
PATCH /api/github/oauth/refresh-token | Обновляется истекающий токен (аниверситет текущий, возвращает новый токен доступа и токен обновления). Должен аутентифицировать использование токена в заголовке Authorization . Использует POST https://github.com/login/oauth/access_token oauth endpoint. |
POST /api/github/oauth/token/scoped | Создает токен с обрезкой (не недействительный текущий). Должен аутентифицировать использование токена в заголовке Authorization . Использует Github's POST /applications/{client_id}/token/scoped конечная точка. |
DELETE /api/github/oauth/token | Недействительно ток тока, в основном эквивалент входа в систему. Должен аутентифицировать использование токена в заголовке Authorization . |
DELETE /api/github/oauth/grant | Отменяет грант пользователя, в основном эквивалент удаления. Должен аутентифицировать использование токена в заголовке Authorization . |
Пример: создать сервер GitHub с 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` ) ;
} ) ; Вы не должны разоблачить секрет клиента вашего приложения пользователю, поэтому вы не можете использовать конструктор App . Вместо этого вы должны создать сервер, используя конструктор App , который разоблачает маршруты /api/github/oauth/* , через которые вы можете безопасно реализовать вход OAuth для приложений, работающих в веб -браузере.
Если вы установите (User) Authorization callback URL в свое собственное приложение, то вам нужно прочитать ?code=...&state=... Параметры запроса, сравните параметр state с значением, возвращаемым app.oauthLoginUrl() ранее, чтобы защитить от подделки, а затем обмениваться code на токен авторизации OAuth.
Если вы запускаете сервер приложений, как описано выше, маршрут по умолчанию, чтобы сделать это POST /api/github/oauth/token .
Как только вы успешно получили токен, также рекомендуется удалить ?code=...&state=... Параметры запроса из URL -адреса браузера
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 ) ;
} ? Мы работаем над @octokit/auth-oauth-user-client чтобы предоставить простой API для всех методов, связанных с токенами пользователей OAuth.
План состоит в том, чтобы добавить новый маршрут GET /api/github/oauth/octokit.js в промежуточное программное обеспечение узла, которое вернет файл JavaScript, который можно импортировать в HTML -файл. Это сделает доступным экземпляром Octokit предварительно аутированного экземпляра octokit .
автономный модуль: @octokit/action
? Полностью клиент с полным запертым Action находится на рассмотрении. Вы можете использовать @actions/github на данный момент
Грань
