วิธีเชื่อมต่อ Repository ของ GHE.com กับ Apidog

เชื่อมต่อ Apidog กับ GitHub Enterprise Cloud Data Residency บน *.ghe.com

Apidog สามารถเชื่อมต่อกับเทนเนนต์ GitHub Enterprise Cloud ที่มีการคงอยู่ของข้อมูล (data residency) ซึ่งโฮสต์อยู่บนโดเมน *.ghe.com ได้ หลังจาก Organization Admin กำหนดค่าเทนเนนต์และแอป OAuth แล้ว ผู้ใช้โปรเจกต์ที่ได้รับอนุญาตจะสามารถเชื่อมต่อ repositories และใช้งานการนำเข้า OpenAPI การสำรองข้อมูล และการซิงโครไนซ์ได้

ลองใช้ Apidog วันนี้

การผสานรวมนี้รองรับเฉพาะเทนเนนต์ SaaS ของ GitHub Enterprise Cloud ที่มี data residency ไม่รองรับ GitHub Enterprise Server หรือโดเมน GitHub ที่กำหนดเอง

ก่อนเริ่มต้น

คุณต้องมี:

• องค์กร Apidog Enterprise ที่เข้าถึงการผสานรวมนี้ได้
• สิทธิ์ Organization Admin ใน Apidog
• เทนเนนต์ GitHub Enterprise Cloud ที่มี data residency บนโดเมนหลัก *.ghe.com เช่น https://company.ghe.com
• สิทธิ์สร้าง OAuth App บนเทนเนนต์ดังกล่าว
• สิทธิ์เข้าถึงองค์กร repositories และ branches ของ GitHub ที่ต้องการเชื่อมต่อ
• ผู้ใช้ที่เชื่อมต่อ repository ต้องมีสิทธิ์การเชื่อมต่อ Git ระดับโปรเจกต์ใน Apidog

ขั้นตอนที่ 1: สร้าง OAuth App บนเทนเนนต์ GHE.com

1. ลงชื่อเข้าใช้เทนเนนต์ GHE.com ขององค์กร
2. เปิดการตั้งค่า OAuth App
3. สร้าง OAuth App ใหม่
4. ตั้งชื่อแอปพลิเคชันที่ระบุได้ชัดเจน
5. ตั้งค่า URL ของหน้าแรกเป็น https://apidog.com
6. ตั้งค่า Authorization callback URL เป็น https://api.apidog.com/passport/github/callback
7. ลงทะเบียน OAuth App
8. คัดลอก Client ID
9. สร้างและคัดลอก Client Secret แล้วจัดเก็บอย่างปลอดภัย

URL การเรียกกลับต้องตรงกับ URL ของ Apidog ที่ระบุไว้ทุกประการ

จัดเก็บ Client Secret ในระบบจัดการความลับที่ได้รับอนุมัติ ห้ามใส่ไว้ในภาพหน้าจอ ตั๋วงาน หรือเอกสารที่แชร์

ขั้นตอนที่ 2: กำหนดค่าเทนเนนต์ GHE.com ใน Apidog

เฉพาะ Organization Admin เท่านั้นที่สามารถกำหนดค่าหรือลบการผสานรวมนี้ได้

1. เปิดองค์กร Apidog
2. ไปที่ Organization Settings
3. เปิด GitHub Integration
4. ค้นหา GitHub Enterprise Cloud Data Residency แล้วเลือก Configure

1. ป้อน URL โฮสต์ GHE.com เช่น https://company.ghe.com
2. เลือก OAuth App เป็นวิธียืนยันตัวตน
3. ป้อน Client ID
4. ป้อน Client Secret
5. บันทึกการกำหนดค่า

กำหนดค่าโฮสต์เทนเนนต์และข้อมูลรับรอง OAuth App ในระดับองค์กร

หลังบันทึก Apidog จะแสดง URL โฮสต์ที่กำหนดค่าไว้ แต่จะไม่แสดงหรือกรอก Client Secret ล่วงหน้าอีก

เมื่อแก้ไขการกำหนดค่า:

• เว้นช่อง Client Secret ว่างไว้เพื่อคงค่าความลับเดิม
• ป้อนค่าใหม่เฉพาะเมื่อต้องการหมุนเวียน (rotate) Client Secret

ขั้นตอนที่ 3: เชื่อมต่อ Repository จากโปรเจกต์ Apidog

หลังจากกำหนดค่าระดับองค์กรแล้ว:

1. เปิดโปรเจกต์ Apidog ที่ต้องการ
2. เริ่มการเชื่อมต่อ Git หรือการนำเข้า Git
3. เลือก GitHub Enterprise Cloud
4. ไปยังหน้าการอนุญาตบนเทนเนนต์ GHE.com ที่กำหนดค่าไว้
5. ลงชื่อเข้าใช้และอนุญาต OAuth App
6. เลือกองค์กร GitHub
7. เลือก repository และ branch
8. ดำเนินการเชื่อมต่อให้เสร็จสมบูรณ์

การอนุญาตดำเนินการบนเทนเนนต์ GHE.com ที่กำหนดค่าไว้ ไม่ใช่บน github.com มาตรฐาน

หากไม่พบองค์กรหรือ repository ที่ต้องการ ให้ตรวจสอบสิทธิ์เข้าถึงบัญชี GitHub และการอนุญาตของ OAuth App ก่อนเปลี่ยนการตั้งค่าองค์กร Apidog

ขั้นตอนที่ 4: นำเข้าไฟล์ OpenAPI

เมื่อต้องการนำเข้าไฟล์ OpenAPI หรือ Swagger จาก repository ที่เชื่อมต่อ:

1. เริ่มขั้นตอนการนำเข้าในโปรเจกต์ Apidog
2. เลือก OpenAPI/Swagger
3. เลือก Git Repository
4. เลือกองค์กร GitHub, repository, branch และไฟล์
5. เลือก Continue
6. เลือกโมดูลเป้าหมายที่มีอยู่ หรือสร้างโมดูลใหม่
7. ดำเนินการนำเข้าให้เสร็จสมบูรณ์
8. ตรวจสอบ endpoints และ schemas ก่อนยอมรับผลลัพธ์

เลือก repository, branch และไฟล์ข้อกำหนดที่โปรเจกต์ต้องการ

สำหรับการนำเข้าครั้งแรก ควรใช้โปรเจกต์ที่ไม่ใช่โปรเจกต์ใช้งานจริง โดยเฉพาะเมื่อโมดูลเป้าหมายมีคำจำกัดความ API อยู่แล้ว

ขั้นตอนที่ 5: เลือกวิธีซิงโครไนซ์

การเชื่อมต่อ repository รองรับขั้นตอนการทำงานหลายรูปแบบ ให้เลือกแหล่งข้อมูลหลักเพียงแหล่งเดียว และจัดทำเอกสารให้ทีมเข้าใจตรงกัน

ขั้นตอนการทำงาน	ใช้เมื่อ	พฤติกรรมที่สำคัญ
นำเข้าด้วยตนเอง	ต้องการนำการเปลี่ยนแปลงเข้า Apidog เมื่อมีการร้องขอเท่านั้น	ตรวจสอบทุกครั้งที่นำเข้า รวมถึงโมดูลเป้าหมาย
นำเข้าตามกำหนดเวลา	ไฟล์ Git เป็นแหล่งข้อมูลหลัก และ Apidog ควรอัปเดตเป็นระยะ	ทำงานผ่านไคลเอนต์ภายในเครื่องหรือ Runner ที่โฮสต์ด้วยตนเอง ตามโหมดที่กำหนดค่าไว้
สำรองข้อมูลไปยัง Git	ต้องการเขียนเนื้อหาจาก Apidog ลงในไฟล์ของ repository	กำหนด repository, branch และเส้นทางไฟล์เป้าหมาย การสำรองข้อมูลอัตโนมัติจะทำงานในช่วง off-peak ที่สุ่มไว้ในเวลากลางคืน
โหมด Spec-first	ไฟล์ข้อกำหนดเป็นแหล่งข้อมูลที่ถูกต้อง และทีมทำงานผ่าน Git	ฟีเจอร์ยังอยู่ในช่วงเบต้า การติดตั้ง webhook มักต้องใช้สิทธิ์ผู้ดูแลระบบ repository

อย่ากำหนดค่าขั้นตอนการทำงานอัตโนมัติสองแบบที่ขัดแย้งกันกับไฟล์เดียวกัน หากยังไม่มีกฎจัดการข้อขัดแย้งที่ชัดเจน

ตั้งค่าการสำรองข้อมูลไปยัง Git

1. สร้างหรือเลือก Git connection ในการตั้งค่าโปรเจกต์
2. เปิด Overview > API Specification ของโมดูล
3. เพิ่มหรือเลือก OpenAPI specification
4. เปิดใช้งาน Backup to Git Repository
5. เลือก repository connection, branch และเส้นทางไฟล์เป้าหมาย
6. บันทึกการกำหนดค่า

สำหรับแหล่งข้อมูลหลักที่ขับเคลื่อนด้วย repository ให้ใช้ การนำเข้าตามกำหนดเวลา (Scheduled Import) หรือทบทวน โหมด Spec-first (Spec-first Mode)

ขั้นตอนที่ 6: ตรวจสอบการผสานรวม

ทำการทดสอบแบบ end-to-end ขนาดเล็ก:

• ยืนยันว่าหน้าการอนุญาตเปิดเทนเนนต์ GHE.com ที่กำหนดค่าไว้
• ยืนยันว่ามีเฉพาะองค์กรและ repository ที่คาดหวัง
• นำเข้าไฟล์ OpenAPI ที่รู้จัก แล้วเปรียบเทียบผลลัพธ์กับแหล่งข้อมูล
• ทดสอบทิศทางการสำรองข้อมูลหรือซิงโครไนซ์บน branch ชั่วคราว
• ตรวจสอบว่าการป้องกัน branch และสิทธิ์ repository ทำงานตามที่คาดไว้
• ตรวจสอบบันทึกการซิงค์และข้อผิดพลาด
• หมุนเวียน Client Secret แล้วทดสอบกระบวนการอัปเดตที่กำหนดไว้

หากใช้ webhook synchronization ให้ยืนยันว่าผู้ติดตั้งมีสิทธิ์ผู้ดูแลระบบ repository และเหตุการณ์ push ที่คาดหวังสามารถกระตุ้นการซิงโครไนซ์ได้

อัปเดตหรือล้างการตั้งค่าองค์กร

Organization Admins สามารถแก้ไข URL โฮสต์หรือ Client ID และหมุนเวียน Client Secret ได้โดยป้อนค่าใหม่

หากต้องการลบการกำหนดค่าระดับองค์กร:

1. เปิด Organization Settings > GitHub Integration
2. ค้นหาการผสานรวม data residency
3. เลือก Clear settings

หลังล้างการตั้งค่า ผู้ใช้จะไม่สามารถสร้าง GitHub Enterprise Cloud connection ใหม่ได้จนกว่าจะกำหนดค่าการผสานรวมอีกครั้ง การเชื่อมต่อเดิมอาจต้องกำหนดค่าหรืออนุญาตใหม่ ขึ้นอยู่กับสถานะโทเค็นและการตั้งค่าองค์กร

การแก้ไขปัญหา

ปัญหา	สิ่งที่ต้องตรวจสอบ
ตัวเลือกการผสานรวมไม่พร้อมใช้งาน	ยืนยันว่าองค์กรเข้าถึงฟีเจอร์ Enterprise ได้ และคุณเป็น Organization Admin
OAuth ส่งคืนข้อผิดพลาดการเรียกกลับ	ตรวจสอบว่า callback URL ของ OAuth App คือ https://api.apidog.com/passport/github/callback อย่างถูกต้อง
การอนุญาตเปิดไปที่ github.com	ตรวจสอบว่าโฮสต์ระดับองค์กรเป็นเทนเนนต์หลัก *.ghe.com ที่ต้องการ
ไม่พบ repository	ตรวจสอบสิทธิ์ของผู้ใช้ GitHub ในองค์กรและ repository รวมถึงข้อจำกัด OAuth
ผู้ใช้โปรเจกต์สร้าง connection ไม่ได้	ยืนยันว่าผู้ใช้มีสิทธิ์การเชื่อมต่อ Git ระดับโปรเจกต์
การนำเข้าหรือซิงค์ล้มเหลว	ตรวจสอบ branch, เส้นทางไฟล์, รูปแบบไฟล์, สิทธิ์ repository และบันทึกการซิงค์

ขอบเขตความปลอดภัยและการคงอยู่ของข้อมูล

• เฉพาะ Organization Admins เท่านั้นที่กำหนดค่าหรือลบการผสานรวม GHE.com ได้
• Client Secret จะไม่แสดงหลังการกำหนดค่า
• สิทธิ์ระดับโปรเจกต์ยังควบคุมว่าใครสามารถสร้างหรืออัปเดต Git connection ได้
• OAuth authorization ดำเนินการผ่านเทนเนนต์ GHE.com ที่กำหนดค่าไว้
• OAuth scopes ที่ร้องขออาจรวมสิทธิ์อ่านองค์กร repositories และ branches นำเข้าไฟล์ เขียนข้อมูลสำรอง และจัดการ repository hooks ตามความต้องการของขั้นตอนการซิงโครไนซ์

การเชื่อมต่อเทนเนนต์ที่มี data residency ไม่ได้พิสูจน์ด้วยตัวเองว่าข้อมูลทุกประเภทที่เกี่ยวข้องกับ GitHub หรือ Apidog จะอยู่ในภูมิภาคเดียวกัน GitHub มีเอกสารเกี่ยวกับข้อมูลที่ครอบคลุมโดยข้อเสนอ data residency และข้อยกเว้นที่เกี่ยวข้อง ส่วน Apidog เป็นบริการแยกต่างหากที่มีโมเดลการจัดเก็บและการปรับใช้ของตัวเอง ควรตรวจสอบเอกสารปัจจุบันของผู้ให้บริการทั้งสองเมื่อประเมิน data residency หรือข้อกำหนดด้านการปฏิบัติตามกฎระเบียบ

บทแนะนำเกี่ยวกับการกำกับดูแล API ที่เกี่ยวข้อง

• กรอบการกำกับดูแล API (API Governance Framework) — เชื่อมโยงความเป็นเจ้าของ การควบคุม หลักฐาน และการตัดสินใจตลอดวงจรชีวิต
• การแมปกลุ่ม SAML กับ Microsoft Entra ID (SAML Group Mapping with Microsoft Entra ID) — กำหนดการเข้าถึงทีมจากกลุ่มผู้ให้บริการข้อมูลระบุตัวตน
• เครื่องสแกนความลับ (Secret Scanner) — ตรวจสอบข้อมูลรับรองที่อาจเปิดเผยในสินทรัพย์ Apidog ที่รองรับ
• บันทึกการตรวจสอบ (Audit Logs) — ตรวจสอบและส่งออกกิจกรรมการดูแลระบบองค์กร
• การจัดเตรียม SCIM (SCIM Provisioning) — จัดการผู้ใช้ในองค์กรผ่านวงจรชีวิตข้อมูลระบุตัวตน
• นโยบายระดับองค์กร (Enterprise Policies) — กำหนดค่าการควบคุมข้อมูลรับรอง สมาชิกภาพ เซสชัน SSO และการเชิญ
• ทีม API แบบบริการตนเอง (Self-Service API Teams) — อนุญาตให้สมาชิกสร้างทีมโดยยังคงดูแลความเป็นเจ้าของ
• การผสานรวม GitHub Enterprise Cloud (GitHub Enterprise Cloud Integration) — เชื่อมต่อ repository GHE.com ที่รองรับสำหรับขั้นตอนการทำงาน OpenAPI

เอกสารประกอบอย่างเป็นทางการ

• Apidog GitHub Enterprise Cloud
• การเชื่อมต่อ Git
• การนำเข้าตามกำหนดเวลา
• โหมด Spec-first
• GitHub: เกี่ยวกับการคงอยู่ของข้อมูล
• GitHub: การจัดเก็บข้อมูลด้วยการคงอยู่ของข้อมูล