สร้าง GitHub App

คู่มือนี้แสดงวิธีมอบตัวตน GitHub ของตัวเองให้เซิร์ฟเวอร์ของคุณ ใช้เวลาประมาณสองนาที มีเพียงเจ้าของเซิร์ฟเวอร์เท่านั้นที่ทำ และต้องทำเพียงครั้งเดียวต่อเซิร์ฟเวอร์

คุณอาจไม่จำเป็นต้องมีมัน

บิลด์อย่างเป็นทางการมาพร้อม client id ของ GitHub อยู่แล้ว ดังนั้น ลงชื่อเข้าใช้ด้วย GitHub จึงใช้งานได้ทันที โดยไม่ต้องลงทะเบียนอะไรเลย — device flow ตรวจสอบสิทธิ์ด้วย client id เพียงอย่างเดียว จึงปลอดภัยที่จะเผยแพร่ไปกับบิลด์ ลงทะเบียนแอปของคุณเองเมื่อคุณต้องการให้ เซิร์ฟเวอร์ ทำหน้าที่เป็นตัวเอง (webhook การโพลล์ PR และการซิงค์ตั๋วงานที่รันบน การติดตั้งแอป แทนข้อมูลรับรองของบุคคล) หรือเมื่อคุณบิลด์จากซอร์สโค้ด

สำหรับการเชื่อมต่อบัญชีของคุณเองในภายหลัง ดู ตั้งค่าการผสาน GitHub

ทำไมเซิร์ฟเวอร์ของคุณจึงต้องมีแอปของตัวเอง

งานสองอย่างที่ต่างกันออกมาจากการลงทะเบียนครั้งเดียว และแอปคือสิ่งที่ทำให้ทั้งสองอย่างซื่อสัตย์:

งาน	อะไรเป็นตัวตอบ	ทำไมจึงสำคัญ
บุคคลลงชื่อเข้าใช้	client id ของแอป ผ่าน device flow	คุณได้ข้อมูลรับรองที่เป็นของคุณเอง บนเซิร์ฟเวอร์ บนทุกอุปกรณ์ — โดยไม่มีโทเค็นให้วางหรือหมุนเวียน
เซิร์ฟเวอร์ลงมือทำ	id ของแอป + private key → โทเค็นการติดตั้ง	webhook การโพลล์ PR และการซิงค์ตั๋วงานเลิกพึ่งพาว่าโทเค็นของมนุษย์คนหนึ่งยังใช้ได้อยู่หรือไม่

สังเกตว่าสิ่งที่ ไม่ อยู่ในตารางนั้นคือ client secret — device flow ของ GitHub ตรวจสอบสิทธิ์ด้วย client id เพียงอย่างเดียว ทั้งคำขอ device code และการโพลล์ โทเค็น — จึงไม่มีข้อมูลลับใดให้เก็บไว้สำหรับการลงชื่อเข้าใช้

หากไม่มีแอปของคุณเอง อย่างแรกก็ยังทำงานได้ผ่าน client id ที่บิลด์มาพร้อมให้ ส่วนอย่างที่สองจะถอยไปใช้ข้อมูลรับรองของเจ้าของเซิร์ฟเวอร์ งานเบื้องหลังจึงพ่วงอยู่กับคนที่เริ่มตั้งค่าก่อน

ไม่มีปุ่ม “ติดตั้ง GitHub App ของ Control Center”

GitHub App แบบแจกจ่ายจะหมายถึง client secret ร่วมกันหนึ่งตัวและการติดตั้งร่วมกันหนึ่งชุด บนเซิร์ฟเวอร์ของทุกคน การเข้าถึงรีโพสิทอรีของทุกเวิร์กสเปซจึงไหลผ่านข้อมูลรับรองที่ไม่มีใคร ในเวิร์กสเปซนั้นควบคุม เซิร์ฟเวอร์แต่ละแห่งจึงเป็นเจ้าของแอปของตัวเอง — คู่มือนี้ว่าด้วยว่ามันมีต้นทุนน้อยเพียงใด

สิ่งที่ต้องมีก่อน

• คุณเป็นเจ้าของเซิร์ฟเวอร์ — การดำเนินการ providerApps.* ถูกจำกัดไว้เฉพาะเจ้าของ และการ์ดนี้มองไม่เห็นสำหรับคนอื่น
• บัญชี GitHub หรือองค์กรที่คุณสร้างแอปได้
• ไม่มีอะไรที่ต้องเข้าถึงได้จากสาธารณะ: การลงชื่อเข้าใช้เป็น device flow เซิร์ฟเวอร์ จึงไม่ต้องมีพอร์ตขาเข้า ทันเนล callback URL หรือโดเมนใด ๆ

ลงทะเบียนแอป

1. ไปที่ github.com/settings/apps/new (สำหรับองค์กร: Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name — อะไรก็ได้; Control Center (yourname) ก็ใช้ได้ ชื่อนี้จะ ปรากฏบนคอมมิตและคอมเมนต์ที่เซิร์ฟเวอร์สร้าง
3. Homepage URL — อะไรก็ได้ เช่น https://github.com/your-name
4. Callback URL — เว้นว่างไว้ device flow ไม่ต้องใช้มัน
5. ติ๊ก Enable Device Flow นี่คือการตั้งค่าเดียวที่การลงชื่อเข้าใช้ขาดไม่ได้
6. ยกเลิกติ๊ก Webhook → Active เว้นแต่คุณจะต่อ webhook แยกต่างหาก
7. ใต้ Repository permissions ให้สิทธิ์อย่างน้อย:
   • Contents: Read and write
   • Metadata: Read-only (บังคับ)
   • Pull requests: Read and write
   • Issues: Read and write หากคุณใช้ GitHub Issues เป็นตั๋วงาน และ สำหรับการค้นหาคอมเมนต์ในบทสนทนา PR ของบอต (ดูคุยกับ Control Center จาก GitHub PR)
   • Checks: Read-only สำหรับสถานะ CI บนหน้า PR
8. ใต้ Where can this GitHub App be installed? เลือกแบบที่เหมาะกับคุณ — “Only on this account” เหมาะกับเซิร์ฟเวอร์ส่วนตัว
9. คลิก Create GitHub App

เก็บค่าทั้งสาม

บนหน้าแอป ทันทีหลังสร้างเสร็จ:

ค่า	ตำแหน่ง
App ID	แท็บ General ใกล้ด้านบน
Client ID	แท็บ General ใต้ “Client secrets”
Private key	Generate a private key — ไฟล์ .pem จะถูกดาวน์โหลด

ไฟล์ private key จะถูกดาวน์โหลดเพียงครั้งเดียว และ GitHub จะไม่แสดงมันอีก เก็บไว้ จนกว่าคุณจะวางมันเสร็จ; คุณสร้างไฟล์ใหม่ได้เสมอ

client secret เป็นทางเลือก และให้ผลอย่างเดียวเท่านั้น: หากคุณเปิด “Expire user authorization tokens” ไว้ มันคือสิ่งที่ต่ออายุโทเค็นของใครสักคน อย่างเงียบ ๆ แทนที่จะให้เขาลงชื่อเข้าใช้อีกครั้งทุกแปดชั่วโมง ส่วนการ ลงชื่อเข้าใช้เองไม่เคยใช้มัน

การตั้งค่าที่ง่ายกว่าคือปิดการหมดอายุนั้น แล้วจะไม่ต้องมี secret ที่ไหนเลย หากคุณเปิดไว้ ให้สร้าง secret แล้ววางใน การตั้งค่า → เซิร์ฟเวอร์ → ลงชื่อเข้าใช้ครั้งเดียว (การ์ด แอปผู้ให้บริการ) — ไม่มีตัวแปรสภาพแวดล้อมสำหรับ มัน และไม่มีอะไรถูกฝังไว้ในบิลด์ มันจึงอยู่บนเซิร์ฟเวอร์ของคุณ

ติดตั้งบนบัญชีของคุณ

แอปที่ลงทะเบียนแล้วแต่ยังไม่ติดตั้งนั้นยืนยันตัวตนผู้คนได้ แต่อ่านอะไรไม่ได้เลย

1. บนหน้าแอป เปิด Install App
2. ติดตั้งบนบัญชีหรือองค์กรของคุณ
3. เลือก All repositories หรือเลือกรีโพที่เซิร์ฟเวอร์นี้ควรเห็น

วางลงใน Control Center

1. ไปที่ การตั้งค่า → เซิร์ฟเวอร์ → ลงชื่อเข้าใช้ครั้งเดียว แล้วเลื่อนไปที่ การ์ด แอปผู้ให้บริการ
2. ในบล็อก GitHub ตั้งค่าแต่ละช่อง:
   • App id — App ID ที่เป็นตัวเลข
   • Private key — วาง .pem ทั้งไฟล์ รวมบรรทัด BEGIN และ END
   • Client id — จากหน้าเดียวกัน
   • Client secret — เฉพาะเมื่อคุณสร้างไว้ (สำหรับการต่ออายุโทเค็น)
3. คลิก ทดสอบ

คีย์จะถูกแยกวิเคราะห์ทันทีที่บันทึก การวางที่ถูกตัดขาดหรือรูปแบบผิดจึงถูกปฏิเสธ ตรงนั้นทันที แทนที่จะไปล้มเหลวในคำขอเบื้องหลังหลายชั่วโมงให้หลัง ทดสอบ ไปไกลกว่านั้น และถาม GitHub ว่าแอปติดตั้งอยู่บนบัญชีใดบ้าง — “บันทึกแล้ว” กับ “ใช้งานได้” เป็นข้ออ้างคนละแบบ และมีเพียงอย่างหลังเท่านั้นที่หมายความว่าจะมีอะไรทำงาน

จุดตรวจสอบ: บล็อก GitHub อ่านได้ว่า “เซิร์ฟเวอร์ทำหน้าที่เป็นตัวเองได้ และคนลงชื่อเข้าใช้ได้” และแถว GitHub ใต้ การตั้งค่า → เวิร์กสเปซ → โปรไฟล์และตัวตน → โฮสต์โค้ด ตอนนี้มี ลงชื่อเข้าใช้ด้วย GitHub ให้เลือก

ตั้งค่าด้วยตัวแปรสภาพแวดล้อมแทน

สำหรับการติดตั้งแบบไม่มีส่วนติดต่อหรือแบบสคริปต์ เซิร์ฟเวอร์จะเติมแต่ละช่องจาก ตัวแปรสภาพแวดล้อมในครั้งแรกที่ยังไม่มีค่าจัดเก็บไว้:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

ไม่มีแฟล็กบนบรรทัดคำสั่งสำหรับค่าเหล่านี้ — ความลับบนบรรทัดคำสั่งนั้นทุกโปรเซส บนโฮสต์อ่านได้ผ่าน ps ตัวแปรสภาพแวดล้อมเป็นที่เดียวที่ตั้งค่าเหล่านี้ได้ และมัน มีสิทธิ์เหนือกว่าสิ่งที่บิลด์มาพร้อมให้ .env.template คือรายการที่สมบูรณ์

สำหรับการพัฒนาภายในเครื่อง .env ที่รากของรีโพเก็บค่าเดียวกัน และเดสก์ท็อป ส่งค่าเหล่านั้นให้เซิร์ฟเวอร์ที่มันเปิดขึ้น ใส่คีย์บนบรรทัดเดียวที่นั่น: ค่าใน .env หนึ่งค่าคือหนึ่งบรรทัด และ \n ภายในเครื่องหมายอัญประกาศคู่จะถูกถอดเป็นขึ้นบรรทัดใหม่

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID และ GITHUB_APP_PRIVATE_KEY เป็นชื่อเดียวกับที่โบรกเกอร์โทเค็นของแซนด์บ็อกซ์ อ่านอยู่แล้ว โฮสต์ที่ตั้งค่าโทเค็นเอเจนต์แบบละเอียดไว้แล้วจึงได้ช่องทางการลงชื่อเข้าใช้ไปฟรี ๆ การเติมค่าจะเกิดขึ้นครั้งเดียวต่อหนึ่งช่อง — หลังจากนั้นค่าที่จัดเก็บไว้จะเป็นฝ่ายชนะ การแก้ไขในการตั้งค่าจึงไม่ถูกย้อนโดยการรีสตาร์ตครั้งถัดไป

ทำแบบเดียวกันกับ Linear

Linear ไม่มี device flow การลงชื่อเข้าใช้ของมันจึงเป็นการไปกลับผ่านเบราว์เซอร์ และ ต้องมี callback URL — การ์ด แอปผู้ให้บริการ แสดง URL ที่คุณต้องลงทะเบียนให้อย่างแม่นยำ

1. สร้างแอปพลิเคชัน OAuth ที่ linear.app/settings/api/applications/new
2. ตั้ง Callback URL เป็น URL ที่การ์ดแสดง ตามตัวอักษร
3. วาง Client ID และ Client secret ลงในบล็อก Linear
4. จะเพิ่มคีย์ API ของเวิร์กสเปซก็ได้ — นั่นคือข้อมูลรับรองที่เซิร์ฟเวอร์ ใช้ซิงค์ตั๋วงานเมื่อไม่มีมนุษย์ร้องขอ

การแก้ปัญหา

กล่องโต้ตอบการลงชื่อเข้าใช้บอกว่าผู้ให้บริการไม่ได้ส่ง device code กลับมา

Enable Device Flow ปิดอยู่บนแอป เปิดมันใต้ General แล้วลองใหม่

การทดสอบบอกว่าข้อมูลรับรองใช้งานได้ แต่แอปไม่ได้ติดตั้งที่ใดเลย

การลงทะเบียนและการติดตั้งเป็นคนละขั้นตอน เปิด Install App บนหน้าแอป แล้วติดตั้งมัน

การทดสอบบอกว่าไม่สามารถอ่าน private key ได้

วางไฟล์ .pem ทั้งไฟล์ รวมบรรทัด -----BEGIN และ -----END คีย์ ed25519 หรือ EC ใช้ไม่ได้ — GitHub Apps ลงนามด้วย RSA

สมาชิกลงชื่อเข้าใช้แล้ว แต่ไม่เห็นรีโพสิทอรีใดเลย

แอปไม่ได้ติดตั้งบนบัญชีที่เป็นเจ้าของรีโพเหล่านั้น หรือการติดตั้งของมันเลือก รีโพอื่น การลงชื่อเข้าใช้ของสมาชิกเองให้สิทธิ์เพียงเท่าที่แอปได้รับอนุญาตให้เห็นเท่านั้น

คู่มือที่เกี่ยวข้อง

• ตั้งค่าการผสาน GitHub
• คุยกับ Control Center จาก GitHub PR
• เชื่อมต่อโฮสต์โค้ด
• จัดการคีย์ API
• ตั้งค่าการผสาน Slack