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

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

การผสานรวมนี้สำหรับเทนเนนต์ SaaS ของ GitHub Enterprise Cloud ที่มีการคงอยู่ของข้อมูลเท่านั้น ไม่รองรับ GitHub Enterprise Server หรือโดเมน GitHub ที่กำหนดเอง

ก่อนที่คุณจะเริ่มต้น

คุณต้องมี:

• องค์กร Apidog Enterprise ที่สามารถเข้าถึงการผสานรวมได้
• สิทธิ์ผู้ดูแลระบบองค์กร (Organization Admin) ใน Apidog
• เทนเนนต์ GitHub Enterprise Cloud ที่มีการคงอยู่ของข้อมูล บนโดเมนหลัก `*.ghe.com` เช่น `https://company.ghe.com`
• สิทธิ์ในการสร้างแอป OAuth บนเทนเนนต์นั้น
• การเข้าถึงองค์กร, คลังเก็บข้อมูล และสาขา GitHub ที่คุณวางแผนจะเชื่อมต่อ

ผู้ใช้ที่เชื่อมต่อคลังเก็บข้อมูลจะต้องมีสิทธิ์การเชื่อมต่อ Git ระดับโปรเจกต์ที่เกี่ยวข้องใน Apidog ด้วย

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

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

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

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

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

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

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

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

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

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

เมื่อแก้ไขการกำหนดค่าในภายหลัง การเว้นช่อง Client Secret ว่างไว้จะคงค่าความลับที่มีอยู่ หากต้องการเปลี่ยนให้ป้อนค่าใหม่เฉพาะเมื่อมีการหมุนเวียน (rotating) เท่านั้น

ขั้นตอนที่ 3: เชื่อมต่อคลังเก็บข้อมูลจากโปรเจกต์ Apidog

หลังจากกำหนดค่าระดับองค์กรเสร็จสมบูรณ์แล้ว:

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

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

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

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

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

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

เลือกคลังเก็บข้อมูล, สาขา และไฟล์ข้อกำหนดที่โปรเจกต์ต้องการ

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

ขั้นตอนที่ 5: เลือกขั้นตอนการซิงโครไนซ์ที่กำลังดำเนินอยู่

การเชื่อมต่อคลังเก็บข้อมูลสามารถรองรับขั้นตอนการทำงานที่แตกต่างกันได้ เลือกแหล่งข้อมูลที่ถูกต้องแหล่งเดียว และจัดทำเอกสารสำหรับทีม

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

สำหรับการสำรองข้อมูล:

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

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

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

เรียกใช้การทดสอบแบบ end-to-end ขนาดเล็ก:

1. ยืนยันว่าการอนุญาตเปิดเทนเนนต์ GHE.com ที่กำหนดค่าไว้
2. ยืนยันว่ามีเฉพาะองค์กรและคลังเก็บข้อมูลที่คาดหวังเท่านั้น
3. นำเข้าไฟล์ OpenAPI ที่รู้จัก และเปรียบเทียบผลลัพธ์กับแหล่งที่มา
4. ทดสอบทิศทางการสำรองข้อมูลหรือการซิงโครไนซ์ที่เลือกในสาขาชั่วคราว
5. ยืนยันว่าการป้องกันสาขาและสิทธิ์คลังเก็บข้อมูลทำงานได้ตามที่คาดไว้
6. ตรวจสอบบันทึกการซิงค์หรือข้อผิดพลาด
7. หมุนเวียน Client Secret ของแอป OAuth และยืนยันว่ากระบวนการอัปเดตที่ระบุไว้ทำงานได้

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

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

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

หากต้องการลบการกำหนดค่าระดับองค์กร ให้เปิด การตั้งค่าองค์กร (Organization Settings) > การผสานรวม GitHub (GitHub Integration) ค้นหาการผสานรวมการคงอยู่ของข้อมูล (data-residency) และเลือก ล้างการตั้งค่า (Clear settings)

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

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

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

• เฉพาะผู้ดูแลระบบองค์กร (Organization Admins) เท่านั้นที่สามารถกำหนดค่าหรือลบการผสานรวม GHE.com ได้
• Client Secret จะไม่แสดงหลังจากกำหนดค่าแล้ว
• สิทธิ์ของโปรเจกต์ยังคงควบคุมว่าใครสามารถสร้างหรืออัปเดตการเชื่อมต่อ Git ได้
• การอนุญาต OAuth เกิดขึ้นผ่านเทนเนนต์ GHE.com ที่กำหนดค่าไว้
• สิทธิ์ OAuth ที่ร้องขอสามารถรวมถึงการเข้าถึงที่จำเป็นในการอ่านองค์กร, คลังเก็บข้อมูล, สาขา, นำเข้าไฟล์, เขียนข้อมูลสำรอง และจัดการ hook ของคลังเก็บข้อมูล เมื่อขั้นตอนการซิงโครไนซ์ต้องการ

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

บทแนะนำเกี่ยวกับการกำกับดูแล 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) — เชื่อมต่อคลังเก็บข้อมูล GHE.com ที่รองรับสำหรับขั้นตอนการทำงาน OpenAPI

เอกสารประกอบอย่างเป็นทางการที่เกี่ยวข้อง:

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