octokit.js
v4.0.2
All-Batteries-รวม GitHub SDK สำหรับเบราว์เซอร์, node.js และ deno
แพ็คเกจ octokit รวมไลบรารี Octokit หลักสามตัว
Octokit APIoctokit.rest Endpoint Methodsoctokit.request()| เบราว์เซอร์ | โหลด octokit โดยตรงจาก ESM.SH < script type =" module " >
import { Octokit , App } from "https://esm.sh/octokit" ;
</ script > |
|---|---|
| Deno | โหลด octokit โดยตรงจาก ESM.SH import { Octokit , App } from "https://esm.sh/octokit?dts" ; |
| โหนด | ติดตั้งด้วย import { Octokit , App } from "octokit" ; |
สำคัญ
ในขณะที่เราใช้การส่งออกแบบมีเงื่อนไขคุณจะต้องปรับ tsconfig.json ของคุณโดยการตั้งค่า "moduleResolution": "node16", "module": "node16"
ดูเอกสาร TypeScript บน package.json "Exports"
ดูคำแนะนำที่เป็นประโยชน์นี้เกี่ยวกับการเปลี่ยนเป็น ESM จาก @Sindresorhus
Octokit API Octokit ขั้นต่ำแบบสแตนด์อโลน : @octokit/core
ไคลเอนต์ Octokit สามารถใช้ส่งคำขอไปยัง REST API ของ GitHub และสอบถามไปยัง GraphQL API ของ 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" ,
} ) ;ส่วนหัวของโซนเวลาจะกำหนดเขตเวลาที่ใช้ในการสร้างการประทับเวลาเมื่อสร้างการกระทำ ดูเอกสาร Timezones ของ GitHub |
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 } } ) ; |
โดยค่าเริ่มต้นไคลเอนต์ Octokit API รองรับการรับรองความถูกต้องโดยใช้โทเค็นแบบคงที่
มีวิธีการที่แตกต่างกันในการตรวจสอบความถูกต้องที่ได้รับการสนับสนุนโดย GitHub ซึ่งอธิบายไว้ในรายละเอียดที่ Octokit/Authentication-Strategies.js คุณสามารถตั้งค่าแต่ละตัวเป็นตัวเลือก authStrategy Constructor และผ่านตัวเลือกกลยุทธ์เป็นตัวเลือกตัวสร้าง 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 หรือ OAuthApp SDK ซึ่งให้ 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 ,
} ) ;เรียนรู้เพิ่มเติมเกี่ยวกับวิธีการตรวจสอบความถูกต้องหรือวิธีการสร้างของคุณเอง
โดยค่าเริ่มต้นไคลเอนต์ Octokit API ไม่ได้ใช้ประโยชน์จากตัวแปรสภาพแวดล้อมเซิร์ฟเวอร์พร็อกซีมาตรฐาน ในการเพิ่มการสนับสนุนสำหรับพร็อกซีเซิร์ฟเวอร์คุณจะต้องจัดหาไคลเอนต์ 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
} ,
} ) ; หากคุณได้รับข้อผิดพลาดต่อไปนี้:
ไม่ได้ตั้งค่าการดึงข้อมูล โปรดผ่านการใช้งานการดึงข้อมูลเป็น Octokit ใหม่ ({คำขอ: {fetch}})
อาจหมายความว่าคุณกำลังพยายามเรียกใช้ Octokit ด้วย NodeJS รุ่นที่ไม่ได้รับการสนับสนุน Octokit ต้องการโหนด 18 หรือสูงกว่าซึ่งรวมถึง API Fetch Native
ในการหลีกเลี่ยงปัญหานี้คุณสามารถให้การใช้งานการ fetch ของคุณเอง (หรือเวอร์ชันในตัวเช่น node-fetch ) เช่นนี้:
import fetch from "node-fetch" ;
const octokit = new Octokit ( {
request : {
fetch : fetch ,
} ,
} ) ; มีสองวิธีในการใช้ GitHub REST API, 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 เต็มรูปแบบและส่งคำขอไปยังจุดสิ้นสุดที่ยังไม่ได้บันทึกไว้ในเอกสาร REST API ของ GitHub
octokit.rest Endpoint Methods จุดสิ้นสุดของ GitHub REST API ทุกครั้งมีวิธี octokit.rest Endpoint สำหรับการอ่านรหัสที่ดีขึ้นและความสะดวกสบายของนักพัฒนา ดู @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 Endpoint จะถูกสร้างขึ้นโดยอัตโนมัติจากข้อกำหนดของ OpenAPI ของ GitHub เราติดตาม ID การทำงานและการเปลี่ยนแปลงชื่อพารามิเตอร์เพื่อใช้คำเตือนการเสื่อมราคาและลดความถี่ในการทำลายการเปลี่ยนแปลง
ภายใต้ฝาครอบทุกวิธีปลายทางเป็นเพียง octokit.request ที่มีชุดค่าเริ่มต้นดังนั้นจึงรองรับพารามิเตอร์เดียวกันเช่นเดียวกับ .endpoint() API
octokit.request() คุณสามารถโทรหา GitHub REST API โดยตรงโดยใช้ octokit.request request API ตรงกับเอกสาร REST API ของ GitHub 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 คือเส้นทาง REST API ตามที่ระบุไว้ในเอกสาร API ของ GitHub อาร์กิวเมนต์ที่ 2 เป็นวัตถุที่มีพารามิเตอร์ทั้งหมดโดยไม่ขึ้นกับว่าจะใช้ในเส้นทางการสืบค้นหรือร่างกาย
จุดสิ้นสุดของ REST API ทั้งหมดที่ paginate ส่งคืน 30 รายการแรกโดยค่าเริ่มต้น หากคุณต้องการดึงรายการทั้งหมดคุณสามารถใช้ API Pagination API Pagination คาดว่าเส้นทาง REST API เป็นอาร์กิวเมนต์แรก แต่คุณสามารถผ่าน 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 ) ;
}
}การใช้ตัววนซ้ำ Async เป็นวิธีที่มีประสิทธิภาพมากที่สุดในการวนซ้ำผ่านรายการทั้งหมด แต่คุณสามารถดึงรายการทั้งหมดในการโทรครั้งเดียว
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 ยังรองรับ GraphQL API ของ 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" ,
} ,
) ; GraphQL API ของ GitHub ส่งคืนสูงสุด 100 รายการ หากคุณต้องการดึงรายการทั้งหมดคุณสามารถใช้ API Pagination
ตัวอย่าง: รับปัญหาทั้งหมด
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" ,
} ,
) ;เรียนรู้เพิ่มเติมเกี่ยวกับการใช้การปนเปื้อน GraphQL ของ GitHub
ตัวอย่างสามารถเปิดใช้งานได้โดยใช้ตัวเลือก {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" ] ,
} ,
} ,
) ;เรียนรู้เพิ่มเติมเกี่ยวกับตัวอย่าง GraphQl Schema ของ GitHub
ไคลเอน App รวมคุณสมบัติสำหรับแอพ GitHub, WebHooks และ OAuth
โมดูลแบบสแตนด์อโลน : @octokit/app
สำหรับผู้รวมระบบแอพ GitHub เป็นวิธีการตรวจสอบสิทธิ์และการอนุญาต แอพ GitHub สามารถลงทะเบียนในบัญชีผู้ใช้ GitHub หรือบัญชีองค์กร การลงทะเบียนแอป GitHub กำหนดชุดของการอนุญาตและเหตุการณ์ webhooks ที่ต้องการรับและจัดทำชุดข้อมูลรับรองในทางกลับกัน ผู้ใช้สามารถให้การเข้าถึงที่เก็บโดยการติดตั้ง
จุดสิ้นสุด API บางแห่งต้องการแอพ GitHub เพื่อตรวจสอบสิทธิ์ในตัวเองโดยใช้ Token Web 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 Secret ซึ่งเป็นส่วนหนึ่งของการลงทะเบียนของแอป คุณต้องตรวจสอบความลับนั้นก่อนที่จะจัดการการยื่นคำขอ
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 แทน
ตัวอย่าง: ดูที่เก็บเมื่อผู้ใช้เข้าสู่ระบบโดยใช้ FLOW WEB 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 Web Flow เปลี่ยนเส้นทางสำหรับโทเค็นการเข้าถึงได้อย่างชัดเจน 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 และยอมรับการเปลี่ยนเส้นทางจาก FLOW ผู้ใช้ Web OAUTH
วิธีที่ง่ายที่สุดในการสร้างเซิร์ฟเวอร์ดังกล่าวคือการใช้ createNodeMiddleware() มันทำงานกับทั้งสองวิธี http.createServer() ของ Node ของ Node รวมถึงมิดเดิลแวร์ด่วน
เส้นทางเริ่มต้นที่มิดเดิลแวร์เปิดรับคือ
| เส้นทาง | คำอธิบายเส้นทาง |
|---|---|
POST /api/github/webhooks | จุดสิ้นสุดเพื่อรับคำขอเหตุการณ์ GitHub WebHook |
GET /api/github/oauth/login | เปลี่ยนเส้นทางไปยังจุดสิ้นสุดการอนุญาตของ GitHub ยอมรับพารามิเตอร์การค้นหา ?state และ ?scopes การสืบค้น ?scopes เป็นรายการชื่อขอบเขต OAUTH ที่คั่นด้วยเครื่องหมายจุลภาค |
GET /api/github/oauth/callback | ปลายทางการเปลี่ยนเส้นทางของลูกค้า นี่คือที่เหตุการณ์ token ถูกกระตุ้น |
POST /api/github/oauth/token | แลกเปลี่ยนรหัสการอนุญาตสำหรับโทเค็นการเข้าถึง OAuth หากประสบความสำเร็จเหตุการณ์ token จะถูกกระตุ้น |
GET /api/github/oauth/token | ตรวจสอบว่าโทเค็นถูกต้องหรือไม่ ต้องตรวจสอบความถูกต้องโดยใช้โทเค็นในส่วนหัว Authorization ใช้ POST /applications/{client_id}/token endpoint |
PATCH /api/github/oauth/token | รีเซ็ตโทเค็น (ทำให้เป็นโมฆะปัจจุบันส่งคืนโทเค็นใหม่) ต้องตรวจสอบความถูกต้องโดยใช้โทเค็นในส่วนหัว Authorization ใช้ PATCH /applications/{client_id}/token endpoint |
PATCH /api/github/oauth/refresh-token | รีเฟรชโทเค็นที่หมดอายุ (ทำให้เป็นโมฆะปัจจุบันส่งคืนโทเค็นการเข้าถึงใหม่และโทเค็นรีเฟรช) ต้องตรวจสอบความถูกต้องโดยใช้โทเค็นในส่วนหัว Authorization ใช้ POST https://github.com/login/oauth/access_token Oauth Endpoint |
POST /api/github/oauth/token/scoped | สร้างโทเค็นที่กำหนดขอบเขต (ไม่ได้ทำให้เป็นโมฆะปัจจุบัน) ต้องตรวจสอบความถูกต้องโดยใช้โทเค็นในส่วนหัว Authorization ใช้ 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 นี้เพื่อป้องกันการโจมตีแบบปลอม
หากคุณเรียกใช้เซิร์ฟเวอร์แอพตามที่อธิบายไว้ข้างต้นเส้นทางเริ่มต้นที่จะทำคือ 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/action
- ไคลเอนต์ Action ที่เต็มเปี่ยมกำลังรอดำเนินการ คุณสามารถใช้ @actions/github ได้ในขณะนี้
มิกซ์
