पहली बार GitHub इंटीग्रेशन बनाते समय आप एक घंटा यह पता लगाने में बिताएँगे कि आपको GitHub App चाहिए या OAuth App। डॉक्स इन्हें समकक्ष विकल्पों की तरह दिखाते हैं। वे नहीं हैं। अकेली वेबहुक की कहानी ही ज़्यादातर मौकों पर आपके लिए फ़ैसला कर देती है।
बहुत छोटा सारांश
- GitHub App: अकाउंट या repository पर इंस्टॉल होता है, बारीक अनुमतियाँ रखता है, जिन संसाधनों पर इंस्टॉल है उनके वेबहुक पाता है, अल्पकालिक टोकन के साथ खुद के रूप में auth करता है।
- OAuth App: यूज़र इसे अधिकृत करते हैं, यह उनकी अनुमतियों के साथ उनकी ओर से कार्य करता है, वेबहुक तभी पाता है जब इसे किसी भी थर्ड-पार्टी टूल की तरह सेट किया जाए, दीर्घकालिक टोकन के साथ यूज़र के रूप में auth करता है।
अगर आप कुछ ऐसा बना रहे हैं जो बिना सक्रिय यूज़र के चलता है — एक CI बॉट, कोड रिव्यू ऑटोमेशन, कोई भी शेड्यूल्ड चीज़ — तो आपको GitHub App चाहिए। अगर आप ऐसा टूल बना रहे हैं जो लॉग-इन यूज़र की ओर से कार्य करता है (जैसे कोड सर्च UI), तो OAuth App सही रूप है।
वे वेबहुक कैसे पाते हैं
GitHub Apps
ऐप बनाते समय आप एक वेबहुक URL कॉन्फ़िगर करते हैं। जब कोई यूज़र अकाउंट या repository पर ऐप इंस्टॉल करता है, GitHub उस दायरे की इवेंट आपके URL पर भेजना शुरू करता है। इवेंट में installation (इंस्टॉल/अनइंस्टॉल जीवनचक्र), installation_repositories (जोड़े या हटाए गए repo), और आपके ऐप द्वारा subscribe किए इवेंट प्रकार (push, pull_request आदि) शामिल हैं।
हर इवेंट में एक X-GitHub-Hook-Installation-Target-Type हेडर ("integration") और एक installation ID होता है जिससे आप उस विशिष्ट इंस्टॉल के लिए टोकन बना सकते हैं। सिग्नेचर X-Hub-Signature-256 में HMAC SHA-256 है — repository वेबहुक जैसा ही रूप।
OAuth Apps
OAuth Apps में अंतर्निहित वेबहुक सब्सक्रिप्शन नहीं होता। वेबहुक पाने के लिए, ऐप के अधिकृत यूज़र को ऐप के URL की ओर इशारा करते repository या organization वेबहुक बनाने पड़ते हैं। इसका मतलब ऐप की वेबहुक पहुँच इस पर निर्भर है कि उसके यूज़र ने कहाँ सब्सक्रिप्शन सेट किए, न कि ऐप खुद कहाँ "इंस्टॉल" है।
कुछ टीमें ऐसी OAuth Apps बनाती हैं जो अधिकरण के बाद GitHub API से अपने-आप वेबहुक बना देती हैं। यह चलता है, पर अब आप ऐप के अपने लॉजिक के साथ-साथ प्रति-यूज़र वेबहुक जीवनचक्र भी प्रबंधित करते हैं।
ऑथ ही असली विभाजन है
GitHub Apps JWT-साइन किए अनुरोधों से auth करते हैं ताकि हर इंस्टॉल के लिए अल्पकालिक installation टोकन (1 घंटा) बनाए जा सकें। JWT उस private key से साइन होता है जो आप ऐप बनाते समय जेनरेट करते हैं। आपका कोड:
// 1. ऐप की private key से JWT साइन करें (10-मिनट में समाप्त)
const jwt = createAppJwt(APP_ID, PRIVATE_KEY);
// 2. JWT को installation टोकन से बदलें (1 घंटे के लिए मान्य)
const token = await fetchInstallationToken(jwt, INSTALLATION_ID);
// 3. उस टोकन से API कॉल करें
const res = await fetch('https://api.github.com/repos/x/y/issues', {
headers: { Authorization: `token ${token}` },
});installation टोकन इंस्टॉल तक सीमित होते हैं और अपने-आप समाप्त हो जाते हैं — इसलिए लीक का असर सीमित रहता है।
OAuth Apps मानक OAuth फ़्लो से प्राप्त यूज़र access टोकन से auth करते हैं। ये टोकन डिफ़ॉल्ट रूप से दीर्घकालिक होते हैं और यूज़र के रूप में कार्य करते हैं — एक लीक का मतलब हमलावर वह सब कर सकता है जो वह यूज़र कर सकता था। GitHub डॉक्स नए इंटीग्रेशन के लिए GitHub Apps की ओर धकेलते हैं, आंशिक रूप से इसी कारण।
अनुमतियाँ: सीमित बनाम व्यापक
GitHub Apps आपको बारीक अनुमतियाँ माँगने देते हैं: issues पढ़ो, checks लिखो, pull requests पढ़ो, बाक़ी किसी तक पहुँच नहीं। हर अनुमति स्वतंत्र है। यूज़र सटीक सूची देखता है और मना कर सकता है।
OAuth Apps पुराने scope-आधारित सिस्टम का उपयोग करते हैं: repo, read:user आदि। scope मोटे हैं। repo scope यूज़र को दिखने वाले सभी repository पर पढ़ने-लिखने की पहुँच देता है — "विशिष्ट repo पर केवल पढ़ना" वाला संस्करण नहीं है।
ऐसे कोड रिव्यू बॉट के लिए जिसे केवल कोड पढ़ना और check runs लिखना है, दो विशिष्ट अनुमतियों वाला GitHub App पूर्ण repo पहुँच माँगने वाले OAuth App से कहीं कम घुसपैठिया है।
दोनों की लोकल टेस्टिंग
वेबहुक सिग्नेचर तंत्र समान है — सेटअप के लिए GitHub वेबहुक लोकल टेस्टिंग देखें। फ़र्क यह है कि आप URL कैसे रजिस्टर करते हैं।
- GitHub App: अपने ऐप के settings पेज पर वेबहुक URL सेट करें। किसी टेस्ट repository पर ऐप इंस्टॉल करें। इवेंट ट्रिगर करें। हो गया।
- OAuth App: ऐप खुद वेबहुक नहीं रखता। अपने टनल URL की ओर इशारा करता एक repository वेबहुक जोड़ें (repo के settings पेज से मैन्युअल, या API से प्रोग्रामैटिकली)।
OAuth Apps के लिए, आपको OAuth callback फ़्लो भी टेस्ट करना होता है — देखें OAuth callback को लोकल कैसे टेस्ट करें।
इनके बीच माइग्रेट करना दर्दनाक है
अगर आप OAuth App से शुरू करते हैं और बाद में समझते हैं कि GitHub App चाहिए, तो आप माइग्रेट नहीं कर सकते। यूज़र को नए ऐप को फिर से अधिकृत करना होगा, आपको कोई भी संग्रहीत टोकन फिर से जारी करना होगा, और OAuth App से सेट किए गए repository वेबहुक तब तक फ़ायर करते रहेंगे जब तक हटाए न जाएँ। सही प्रकार चुनने के लिए शुरुआत में दस मिनट दें।
कब कौन-सा चुनें
GitHub App चुनें जब:
- आपका इंटीग्रेशन अपने शेड्यूल पर या इवेंट के जवाब में चलता है, बिना लॉग-इन यूज़र के।
- आप विशिष्ट repository या organization पर सीमित अनुमतियाँ चाहते हैं।
- आप इंस्टॉल दायरे से बंधे वेबहुक चाहते हैं, न कि प्रति-repo कॉन्फ़िगर किए।
- आप कुछ ऐसा बना रहे हैं जो आख़िरकार GitHub Marketplace में सूचीबद्ध होगा।
OAuth App चुनें जब:
- आपका टूल एक UI है जिसमें यूज़र लॉग इन करते हैं और अपने GitHub अकाउंट में काम करते हैं।
- आपको यूज़र के रूप में बिल्कुल सही कार्य करना है, उनके एक्सेस पैटर्न सहित।
- आपको वेबहुक नहीं चाहिए, या आप उन्हें प्रति-repo मैन्युअल सेट करेंगे।
अंतर्निहित सिग्नेचर सत्यापन विवरण के लिए सिग्नेचर सत्यापन गाइड देखें। ऐसे टनल के लिए जो GitHub के वेबहुक टाइमिंग और रीप्ले के लिए कैप्चर संभालता है, PortPreview वेटलिस्ट में शामिल हों।