लोकलहोस्ट पर GitLab वेबहुक्स को सुरक्षित रूप से टेस्ट करें

लोकलहोस्ट पर GitLab वेबहूक का परीक्षण करने के लिए, अपने स्थानीय हैंडलर को एक HTTPS टनल के माध्यम से एक्सपोज़ करें, उस URL को Settings → Webhooks के अंतर्गत जोड़ें, एक साइनिंग टोकन जनरेट करें, और पे लोड पार्स करने से पहले GitLab के स्टैंडर्ड वेबहूक सिग्नेचर को वेरिफाई करें। एक पुश या मर्ज रिक्वेस्ट ट्रिगर करें, डिलीवरी का निरीक्षण करें, और हर बदलाव के बाद अपनी इंटिग्रेशन को डिप्लॉय किए बिना लोकली इटरेट करें।

GitLab साइनिंग टोकन का उपयोग करें, नया प्लेन-टेक्स्ट सीक्रेट टोकन नहीं।

GitLab दो मैकेनिज़्म को सपोर्ट करता है जो आसानी से भ्रमित हो सकते हैं। पुराना सीक्रेट टोकन X-Gitlab-Token रिक्वेस्ट हेडर में कॉपी किया जाता है। यह साझा मान का ज्ञान साबित करता है लेकिन बॉडी की अखंडता की सुरक्षा नहीं करता। GitLab अब नए वेबहूक्स के लिए साइनिंग टोकन की सिफारिश करता है। यह HMAC-SHA256 सिग्नेचर उत्पन्न करता है और स्टैंडर्ड वेबहूक मेसेज फॉर्मेट का पालन करता है।

यह आधिकारिक GitLab वेबहुक दस्तावेज़ कहता है कि एक हस्ताक्षरित अनुरोध में शामिल है webhook-id, webhook-timestamp, और webhook-signatureसिग्नेचर में संदेश आईडी, समय मुहर और सटीक कच्चा JSON बॉडी शामिल है। यह मूल और पेलोड की अखंडता दोनों की सुरक्षा करता है।

Node.js में मानक वेबहुक सत्यापन लागू करें

GitLab साइनिंग टोकन एक बार दिखाए जाते हैं और उपयोग किए जाते हैं whsec_ उपसर्ग। उस उपसर्ग को हटा दें और शेष को Base64-डिकोड करें ताकि HMAC कुंजी प्राप्त हो सके। प्रत्येक प्राप्त हस्ताक्षर का रूप है v1,<base64 signature>; हेडर में कई स्पेस-सेपरेटेड सिग्नेचर्स हो सकते हैं।

import crypto from 'node:crypto';

function safeEqual(a, b) {
  const left = Buffer.from(a);
  const right = Buffer.from(b);
  return left.length === right.length &&
    crypto.timingSafeEqual(left, right);
}

function verifyGitLabWebhook({ token, id, timestamp, body, signatures }) {
  if (!token?.startsWith('whsec_') || !id || !timestamp || !signatures) {
    return false;
  }

  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const key = Buffer.from(token.slice(6), 'base64');
  const message = `${id}.${timestamp}.${body}`;
  const digest = crypto.createHmac('sha256', key).update(message).digest('base64');
  const expected = `v1,${digest}`;
  return signatures.split(' ').some((value) => safeEqual(value, expected));
}

यहाँ दिखाया गया पांच-मिनट का टाइमस्टैम्प विंडो एक एप्लिकेशन नीति है, अंधाधुंध नक़ल करने के लिए मान नहीं। एक ऐसा सहिष्णुता चुनें जो घड़ी के अंतर को समायोजित करे लेकिन उपयोगी पुन:प्रसारण को रोके। प्राप्त करने वाली मशीन की घड़ी को सिंक्रनाइज़ करें। प्रत्येक स्वीकार किए गए को दर्ज करें webhook-id एक अद्वितीय प्रतिबंध के अंतर्गत, क्योंकि केवल ताज़ा समय-मुद्रा की जाँच ही एक ही संदेश की दो तात्कालिक डिलीवरी को रोक नहीं सकती।

Express वेबहुक रूट बनाएं

इस रूट पर कच्चे बॉडी को कैप्चर करें। सत्यापन से पहले एक वैश्विक express.json() कॉल GitLab द्वारा साइन किए गए बाइट-फॉर-बाइट प्रतिनिधित्व को नष्ट कर देता है।

import express from 'express';

const app = express();
app.post(
  '/webhooks/gitlab',
  express.raw({ type: 'application/json', limit: '2mb' }),
  async (req, res) => {
    const body = req.body.toString('utf8');
    const valid = verifyGitLabWebhook({
      token: process.env.GITLAB_WEBHOOK_SIGNING_TOKEN,
      id: req.get('webhook-id'),
      timestamp: req.get('webhook-timestamp'),
      signatures: req.get('webhook-signature'),
      body,
    });
    if (!valid) return res.sendStatus(401);

    await inbox.insertOnce(req.get('webhook-id'), JSON.parse(body));
    return res.sendStatus(202);
  },
);
app.use(express.json());
app.listen(3000);

वेबहुक रूट के बाद सामान्य JSON पार्सर को माउंट करें या उसके verify कॉलबैक का उपयोग करें ताकि कच्चा बफ़र सुरक्षित रहे। केवल इसलिए कि एंडपॉइंट लोकलहोस्ट को अग्रेषित करता है, कभी भी सिग्नेचर जांच को निष्क्रिय न करें; सुरंग URL अभी भी सार्वजनिक इंटरनेट से पहुंच योग्य है।

एक सार्वजनिक HTTPS एंडपॉइंट बनाएं

1. स्थानीय रूप से एकीकरण शुरू करें और जानबूझकर बिना साइन किए गए अनुरोध के साथ इसके रूट का परीक्षण करें। इसे 401 लौटाना चाहिए, यह प्रमाणित करता है कि प्रमाणीकरण सक्रिय है।
2. दूसरे टर्मिनल में npx portpreview 3000 चलाएं।
3. HTTPS मूल कॉपी करें और इसे जोड़ें /webhooks/gitlab.
4. कॉन्फ़िगरेशन और इवेंट परीक्षण के दौरान सुरंग को खुला रखें।

GitLab का SSL प्रमाणन सक्रिय रहना चाहिए। सार्वजनिक रूप से भरोसेमंद TLS के साथ एक टनल स्व-हस्ताक्षरित प्रमाणपत्र त्रुटियों से बचता है। यदि GitLab एक निजी स्व-प्रबंधित नेटवर्क में चलता है, तो इसे सार्वजनिक टनल URL तक आउटबाउंड एक्सेस भी होना चाहिए।

प्रोजेक्ट वेबहुक कॉन्फ़िगर करें

1. GitLab प्रोजेक्ट खोलें और चुनें सेटिंग्स → वेबहुक्स.
2. चुनें नया वेबहुक जोड़ें और पूरे टनल डिलीवरी URL को पेस्ट करें।
3. चुनें साइनिंग टोकन जनरेट करेंटोकन को तुरंत कॉपी करें, और इसे में सेव करें GITLAB_WEBHOOK_SIGNING_TOKEN.
4. केवल आवश्यक ट्रिगर्स का चयन करें—उदाहरण के लिए पुश इवेंट, मर्ज रिक्वेस्ट इवेंट, टैग पुश इवेंट, या पाइपलाइन इवेंट।
5. SSL सत्यापन सक्षम छोड़ें और वेबहुक सहेजें।
6. GitLab की टेस्ट क्रिया का उपयोग करें या एक वास्तविक घटना उत्पन्न करें, फिर स्थानीय अनुरोध और GitLab वितरण इतिहास की जाँच करें।

पर्यावरण चर सेट करने के बाद स्थानीय प्रक्रिया को पुनरारंभ करें। यदि आप मौजूदा एकीकरण को माइग्रेट कर रहे हैं, तो GitLab साइनिंग टोकन और लेगेसी सीक्रेट टोकन दोनों की अनुमति देता है। जब मौजूद हो, तो सत्यापित करें webhook-signature , अस्थायी रूप से X-Gitlab-Token पर वापस जाएं, फिर सभी रिसीवर्स सिग्नेचर्स का समर्थन करने के बाद कमजोर सीक्रेट को हटा दें।

हेडर और पेलोड द्वारा GitLab घटनाओं का प्रेषण करें

X-Gitlab-Event एक पठनीय घटना नाम देता है जैसे Push Hook या Merge Request Hook। इसका उपयोग रूटिंग के लिए करें, लेकिन पेलोड का object_kind भी सत्यापित करें। यह अप्रत्याशित संयोजनों को दृश्य बनाता है।

switch (req.get('x-gitlab-event')) {
  case 'Push Hook':
    await handlePush(payload);
    break;
  case 'Merge Request Hook':
    await handleMergeRequest(payload);
    break;
  case 'Pipeline Hook':
    await handlePipeline(payload);
    break;
  default:
    await recordUnsupportedGitLabEvent(payload.object_kind);
}

पुश घटनाएं

टेस्ट ब्रांच निर्माण, सामान्य कमिट, फ़ोर्स पुश, और ब्रांच हटाना। एक शून्य SHA रेफ ट्रांज़िशन के गायब पक्ष का प्रतिनिधित्व कर सकता है। बड़े पुश एक कमिट फ़िक्स्चर से भिन्न हो सकते हैं, इसलिए यह मत मानिए कि हर बदली गई कमिट असीमित क्रम में दिखाई देगी। डिस्प्ले स्ट्रिंग पार्स करने के बजाय प्रोजेक्ट और रेफ पहचानकर्ताओं का उपयोग करें।

मर्ज रिक्वेस्ट घटनाएँ

जैसे ओपन, अपडेट, अप्रूवल, मर्ज, और क्लोज जैसी क्रियाएँ एक ही व्यापक इवेंट प्रकार साझा कर सकती हैं। दस्तावेज़ीकृत ऑब्जेक्ट विशेषताओं के आधार पर मार्ग दें और बार-बार अपडेट को इडेम्पोटेंट बनाएं। केवल mutable शीर्षक या उपयोगकर्ता नाम मेल खाने के कारण कोड मर्ज या डिप्लॉयमेंट को अप्रूव न करें।

पाइपलाइन और जॉब घटनाएँ

ये अक्सर हो सकती हैं। प्रोजेक्ट, ब्रांच, स्टेटस, और वातावरण के आधार पर GitLab में और आपके हैंडलर में फिल्टर करें। धीमे आर्टिफैक्ट या डिप्लॉयमेंट कार्य को कतारबद्ध करें और पहले वेबहुक को मान्यता दें।

पुनः प्रयास और पुनरावर्ती ट्रिगर के लिए डिज़ाइन

GitLab में webhook-id शामिल है, जो पुनः प्रयासों के बीच स्थिर रहता है और पुरानी Idempotency-Key के बराबर होता है। इसका उपयोग डिलीवरी ऐडंपोटेंसी कुंजी के रूप में करें। X-Gitlab-Webhook-UUID एक वेबहुक निष्पादन को पहचानता है, जबकि X-Gitlab-Event-UUID घटनाओं को ट्रेस करने में मदद कर सकता है; पुनरावर्ती वेबहुक्स घटना UUID साझा कर सकते हैं।

यदि हैंडलर API के माध्यम से GitLab को संशोधित करता है, तो यह एक और वेबहुक बना सकता है। स्पष्ट लूप रोकथाम जोड़ें: अपने एकीकरण पहचान के साथ क्रियाओं को टैग करें, उन परिवर्तनों को अनदेखा करें जो इच्छित स्थिति को नहीं बदलते, और वर्कफ़्लो संक्रमणों को सीमा में रखें। पुनः प्रयास और ऐडंपोटेंसी गाइड लेन-देन इनबॉक्स पैटर्न को कवर करता है।

असफल GitLab वेबहुक परीक्षणों का निवारण करें

GitLab URL से कनेक्ट नहीं कर सकता

पुष्टि करें कि टनल प्रक्रिया सक्रिय है, पूरा पथ सही है, और आपका लोकल सर्वर अग्रेषित पोर्ट पर सुन रहा है। स्वयं-प्रबंधित GitLab के लिए, आउटबाउंड नेटवर्क नीति और DNS की जांच करें। एक अप्रासंगिक रूटिंग विफलता को छिपाने के लिए SSL सत्यापन को साफ़ न करें।

सिग्नेचर कभी मेल नहीं खाता।

साइनिंग टोकन का उपयोग करें, पुराने सीक्रेट टोकन का नहीं। whsec_को हटाएं, शेष टोकन को Base64 में डिकोड करें, और {webhook-id}.{webhook-timestamp}.{raw body} पर साइन करें। बाइनरी HMAC डाइजेस्ट को Base64 में एन्कोड करें और इसे v1, के साथ प्रारंभ करें। प्रत्येक स्पेस-सेपरेटेड सिग्नेचर के खिलाफ तुलना करें।

टाइमस्टैम्प को अस्वीकृत किया गया।

सिस्टम समय और टाइमज़ोन हैंडलिंग की जाँच करें; हेडर सेकंड में Unix टाइमस्टैम्प है। इसे JavaScript मिलीसेकंड के साथ तुलना न करें बिना इसे 1000 से विभाजित किए। यदि कब्जा किए गए पुराने अनुरोध को डीबग कर रहे हैं, तो टाइमस्टैम्प अस्वीकृति सही रिप्ले सुरक्षा है।

GitLab वेबहुक को अक्षम करता है या पीछे हटता है

हाल ही की डिलीवरी की स्थिति और आपके मार्ग की प्रतिक्रिया की जांच करें। टिकाऊ स्वीकृति के बाद जल्दी 2xx लौटाएं। लगातार 401 का मतलब है कि टोकन कॉन्फ़िगरेशन गलत है; लगातार 5xx का मतलब है हैंडलर विफलताएँ; टाइमआउट का मतलब है बहुत अधिक समकालिक कार्य।

केवल कुछ घटनाएँ आती हैं

चयनित ट्रिगर्स और ब्रांच फ़िल्टर की समीक्षा करें। समूह और प्रोजेक्ट वेबहुक का अलग दायरा होता है। पुष्टि करें कि यह घटना उसी प्रोजेक्ट में हुई जहाँ यह वेबहुक कॉन्फ़िगर किया गया है।

स्थानीय GitLab वेबहुक डेटा को सुरक्षित रखें

• साइनिंग टोकन को केवल अनदेखी की गई एनवायरनमेंट फ़ाइलों में स्टोर करें और किसी भी लीक हुए टोकन को रोटेट करें।
• साइड इफेक्ट से पहले सिग्नेचर, टाइमस्टैम्प, प्रोजेक्ट आईडी और अनुमत इवेंट प्रकार को मान्य करें।
• कैप्चर से कमिट संदेश, निजी रिपॉजिटरी URL, उपयोगकर्ता ईमेल और CI वेरिएबल्स को गुप्त करें।
• इंटीग्रेशन API टोकन को केवल उसके डाउनस्ट्रीम कार्य के लिए आवश्यक स्कोप दें।
• परीक्षण समाप्त होने पर स्थानीय पेलोड इतिहास को हटाएं।

प्रोवाइडर-स्वतंत्र डायग्नोस्टिक्स के लिए, स्थानीय वेबहुक डिबगिंग गाइड का उपयोग करें। GitHub एक अलग हस्ताक्षर प्रारूप का उपयोग करता है, इसलिए इसके विश्लेषक को पुन: उपयोग करने की बजाय अलग GitHub वेबहुक गाइड की सलाह लें।