GitHub Actions और Pages के साथ इवेंट डेटा प्रकाशित करें: चरण-दर-चरण गाइड

GitHub पर काम करने वाली टीमें सहयोग के लिए इवेंट डेटा पर भरोसा करती हैं। इश्यू, पुल रिक्वेस्ट और टिप्पणियों के रूप में रिकॉर्ड किया गया डेटा प्रोजेक्ट को समझने के लिए महत्वपूर्ण हो जाता है।

GitHub Actions की सामान्य उपलब्धता के साथ, हमारे पास अपने रिपॉजिटरी में GitHub इवेंट डेटा को प्रोग्रामेटिक रूप से एक्सेस और संरक्षित करने का मौका है। डेटा को रिपॉजिटरी का हिस्सा बनाना इसे GitHub के बाहर संरक्षित करने का एक तरीका है। यह हमें GitHub Pages जैसी फ्रंट-फेसिंग वेबसाइट पर डेटा प्रदर्शित करने की क्षमता भी देता है।

और, यदि आप मेरी तरह हैं, तो आप GitHub इश्यू टिप्पणियों को एक शानदार 90 के दशक के गेस्टबुक पेज में बदल सकते हैं।

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

GitHub Actions के परिचयात्मक नज़र के लिए जिसमें वर्कफ़्लो कैसे ट्रिगर होते हैं, देखें A lightweight, tool-agnostic CI/CD flow with GitHub Actions.

GitHub इवेंट डेटा तक पहुंचना

एक एक्शन वर्कफ़्लो कुछ डिफ़ॉल्ट एनवायरनमेंट वेरिएबल के साथ एक एनवायरनमेंट में चलता है। यहां बहुत सारी सुविधाजनक जानकारी उपलब्ध है, जिसमें इवेंट डेटा भी शामिल है। इवेंट डेटा तक पहुंचने का सबसे पूर्ण तरीका $GITHUB_EVENT_PATH वेरिएबल का उपयोग करना है, पूर्ण JSON इवेंट पेलोड वाली फाइल का पथ।

विस्तारित पथ /home/runner/work/_temp/_github_workflow/event.json जैसा दिखता है और इसका डेटा इसके वेबहुक इवेंट से मेल खाता है। आप GitHub REST API इवेंट प्रकार और पेलोड में वेबहुक इवेंट डेटा के लिए डॉक्यूमेंटेशन पा सकते हैं। वर्कफ़्लो एनवायरनमेंट में JSON डेटा उपलब्ध कराने के लिए, आप jq जैसे टूल का उपयोग इवेंट डेटा को पार्स करने और इसे एनवायरनमेंट वेरिएबल में डालने के लिए कर सकते हैं।

नीचे, मैं इश्यू कमेंट इवेंट से कमेंट आईडी लेता हूं:

ID="$(jq '.comment.id' $GITHUB_EVENT_PATH)"

अधिकांश इवेंट डेटा github.event कॉन्टेक्स्ट वेरिएबल के माध्यम से भी उपलब्ध है बिना JSON पार्स किए। फील्ड्स को डॉट नोटेशन का उपयोग करके एक्सेस किया जाता है, जैसा कि नीचे उदाहरण में जहां मैं वही कमेंट आईडी लेता हूं:

ID=${{ github.event.comment.id }}

मेरे गेस्टबुक के लिए, मैं उपयोगकर्ता के हैंडल, और तारीख और समय के साथ एंट्री प्रदर्शित करना चाहता हूं। मैं इस इवेंट डेटा को इस तरह कैप्चर कर सकता हूं:

AUTHOR=${{ github.event.comment.user.login }}
DATE=${{ github.event.comment.created_at }}

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

इवेंट डेटा संरक्षित करना: आर्टिफैक्ट्स का उपयोग करना

आर्टिफैक्ट्स का उपयोग करके, आप इसे अपने रिपॉजिटरी में कमिट किए बिना वर्कफ़्लो जॉब्स के बीच डेटा को बनाए रख सकते हैं। यह तब उपयोगी होता है जब, उदाहरण के लिए, आप इसे कहीं अधिक स्थायी रखने से पहले डेटा को ट्रांसफॉर्म या शामिल करना चाहते हैं। वर्कफ़्लो जॉब्स के बीच डेटा को बनाए रखना आवश्यक है क्योंकि:

वर्कफ़्लो में प्रत्येक जॉब वर्चुअल एनवायरनमेंट के एक नए इंस्टेंस में चलता है। जब जॉब पूरा होता है, तो रनर समाप्त होता है और वर्चुअल एनवायरनमेंट के इंस्टेंस को हटा देता है। (आर्टिफैक्ट्स का उपयोग करके वर्कफ़्लो डेटा को बनाए रखना)

आर्टिफैक्ट्स के उपयोग में दो एक्शन सहायता करते हैं: upload-artifact और download-artifact। आप इन एक्शन का उपयोग उसी वर्कफ़्लो में अन्य जॉब्स के लिए फाइलें उपलब्ध कराने के लिए कर सकते हैं। पूर्ण उदाहरण के लिए, वर्कफ़्लो में जॉब्स के बीच डेटा पास करना देखें।

upload-artifact एक्शन के action.yml में कीवर्ड का विवरण है। अपलोड की गई फाइलें .zip फॉर्मेट में सेव होती हैं। उसी वर्कफ़्लो रन में एक अन्य जॉब download-artifact एक्शन का उपयोग करके डेटा को दूसरे स्टेप में उपयोग कर सकता है।

आप वर्कफ़्लो रन पेज पर, रिपॉजिटरी के Actions टैब के तहत मैन्युअल रूप से आर्काइव भी डाउनलोड कर सकते हैं।

जॉब्स के बीच वर्कफ़्लो डेटा को बनाए रखने से रिपॉजिटरी फाइलों में कोई बदलाव नहीं होता है, क्योंकि उत्पन्न आर्टिफैक्ट्स केवल वर्कफ़्लो एनवायरनमेंट में रहते हैं।

व्यक्तिगत रूप से, शेल एनवायरनमेंट में काम करने में सहज होने के कारण, मैं आर्टिफैक्ट्स के लिए एक संकीर्ण उपयोग का मामला देखता हूं, हालांकि मुझे उनका उल्लेख न करना गलत होता। जॉब्स के बीच डेटा पास करने के अलावा, वे टेस्ट आउटपुट डेटा के .zip फॉर्मेट आर्काइव बनाने के लिए उपयोगी हो सकते हैं। मेरे गेस्टबुक उदाहरण के मामले में, मैंने बस सभी आवश्यक स्टेप्स को एक जॉब में चलाया, जिससे जॉब्स के बीच डेटा पास करने की किसी भी आवश्यकता को नकार दिया।

इवेंट डेटा संरक्षित करना: वर्कफ़्लो फाइलों को रिपॉजिटरी में पुश करना

वर्कफ़्लो में कैप्चर किए गए डेटा को रिपॉजिटरी में ही संरक्षित करने के लिए, इस डेटा को Git रिपॉजिटरी में जोड़ना और पुश करना आवश्यक है। आप शेल कमांड का उपयोग करके वर्कफ़्लो में नई फाइलें डेटा के साथ बना सकते हैं, या मौजूदा फाइलों में डेटा जोड़ सकते हैं।

वर्कफ़्लो में फाइलें बनाना

वर्कफ़्लो में रिपॉजिटरी फाइलों के साथ काम करने के लिए, पहले काम करने के लिए एक कॉपी प्राप्त करने के लिए checkout एक्शन का उपयोग करें:

- uses: actions/checkout@master
with:
fetch-depth: 1

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

- name: Turn comment into file
run: |
ID=${{ github.event.comment.id }}
AUTHOR=${{ github.event.comment.user.login }}
DATE=${{ github.event.comment.created_at }}
COMMENT=$(echo "${{ github.event.comment.body }}")
NO_TAGS=${COMMENT//[<>]/`}
FOLDER=comments
printf '%b\n' "
${AUTHOR} says:
${NO_TAGS//$'\n'/\}
${DATE}
\r\n" > ${FOLDER}/${ID}.html

printf का उपयोग करके और इसके आउटपुट को > के साथ एक नई फाइल में निर्देशित करके, इवेंट डेटा को एक HTML फाइल में बदल दिया जाता है, जिसका नाम कमेंट आईडी नंबर के साथ होता है, जिसमें कैप्चर किया गया इवेंट डेटा होता है। फॉर्मेट किया गया, यह इस तरह दिखता है:

victoriadrake says:
This is a comment!
2019-11-04T00:28:36Z

कमेंट के साथ काम करते समय, कमेंट आईडी का उपयोग करके फाइलों का नाम रखने का एक प्रभाव यह है कि उसी आईडी वाली एक नई फाइल पिछली को ओवरराइट कर देगी। यह गेस्टबुक के लिए उपयोगी है, क्योंकि यह कमेंट में किसी भी संपादन को मूल कमेंट फाइल को प्रतिस्थापित करने की अनुमति देता है।

यदि आप Hugo जैसे स्टेटिक साइट जनरेटर का उपयोग कर रहे हैं, तो आप मार्कडाउन फॉर्मेट फाइल बना सकते हैं, इसे अपने content/ फोल्डर में रख सकते हैं, और नियमित साइट बिल्ड बाकी का ख्याल रखेगा।

मेरे सरल गेस्टबुक के मामले में, मेरे पास व्यक्तिगत कमेंट फाइलों को एक पेज में समेकित करने के लिए एक अतिरिक्त स्टेप है। हर बार जब यह चलता है, तो यह मौजूदा index.html को header.html भाग (>) के साथ ओवरराइट करता है, फिर सभी कमेंट फाइलों की सामग्री को अवरोही क्रम में ढूंढता है और जोड़ता है (>>), और अंत में पेज को समाप्त करने के लिए footer.html भाग को जोड़ता है।

- name: Assemble page
run: |
cat header.html > index.html
find comments/ -name "*.html" | sort -r | xargs -I % cat % >> index.html
cat footer.html >> index.html

रिपॉजिटरी में परिवर्तन कमिट करना

चूंकि checkout एक्शन रिपॉजिटरी को क्लोन करने के समान नहीं है, लेखन के समय, कुछ मुद्दे अभी भी हैं जिनसे निपटना है। pull, checkout, और सफलतापूर्वक master ब्रांच में push करने के लिए कुछ अतिरिक्त स्टेप आवश्यक हैं, लेकिन यह शेल में काफी तुच्छ रूप से किया जाता है।

नीचे वह स्टेप है जो वर्कफ़्लो द्वारा किए गए परिवर्तनों को जोड़ता, कमिट करता है, और रिपॉजिटरी के master ब्रांच में वापस पुश करता है।

- name: Push changes to repo
run: |
REMOTE=https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
git config user.email "${{ github.actor }}@users.noreply.github.com"
git config user.name "${{ github.actor }}"
git pull ${REMOTE}
git checkout master
git add .
git status
git commit -am "Add new comment"
git push ${REMOTE} master

रिमोट, वास्तव में, हमारा रिपॉजिटरी है, जिसे github.repository कॉन्टेक्स्ट वेरिएबल का उपयोग करके निर्दिष्ट किया गया है। हमारे वर्कफ़्लो को master में पुश करने की अनुमति देने के लिए, हम secrets.GITHUB_TOKEN वेरिएबल का उपयोग करते हैं।

चूंकि वर्कफ़्लो एनवायरनमेंट चमकदार और नया है, हमें Git कॉन्फ़िगर करने की आवश्यकता है। उपरोक्त उदाहरण में, मैंने वर्कफ़्लो शुरू करने वाले अकाउंट के उपयोगकर्ता नाम को इनपुट करने के लिए github.actor कॉन्टेक्स्ट वेरिएबल का उपयोग किया है। ईमेल को इसी तरह डिफ़ॉल्ट noreply GitHub ईमेल पते का उपयोग करके कॉन्फ़िगर किया गया है।

इवेंट डेटा प्रदर्शित करना

6 नवंबर, 2019 सुधार: GitHub Actions को Pages साइट बिल्ड को ट्रिगर करने के लिए पर्सनल एक्सेस टोकन की आवश्यकता होती है।

यदि आप डिफ़ॉल्ट secrets.GITHUB_TOKEN वेरिएबल के साथ GitHub Pages का उपयोग कर रहे हैं और साइट जनरेटर के बिना, वर्कफ़्लो में रिपॉजिटरी में परिवर्तन पुश करने से केवल रिपॉजिटरी फाइलें अपडेट होंगी। GitHub Pages बिल्ड एक त्रुटि के साथ विफल होगा, "Your site is having problems building: Page build failed."

Actions को Pages साइट बिल्ड को ट्रिगर करने में सक्षम करने के लिए, आपको एक पर्सनल एक्सेस टोकन बनाना होगा। इस टोकन को रिपॉजिटरी सेटिंग्स में सीक्रेट के रूप में संग्रहीत किया जा सकता है और वर्कफ़्लो में डिफ़ॉल्ट secrets.GITHUB_TOKEN वेरिएबल के स्थान पर पास किया जा सकता है। मैंने इस पोस्ट में Actions एनवायरनमेंट और वेरिएबल के बारे में अधिक लिखा है।

पर्सनल एक्सेस टोकन के उपयोग के साथ, Actions वर्कफ़्लो द्वारा शुरू किया गया एक पुश Pages साइट को भी अपडेट करेगा। आप इसे स्वयं देख सकते हैं मेरे गेस्टबुक में एक टिप्पणी छोड़कर! कमेंट निर्माण इवेंट वर्कफ़्लो को ट्रिगर करता है, जो फिर गेस्टबुक पेज को अपडेट करने के लिए लगभग 30 सेकंड से एक मिनट तक चलता है।

जहां परिवर्तनों को प्रकाशित करने के लिए साइट बिल्ड आवश्यक है, जैसे Hugo का उपयोग करते समय, एक एक्शन यह भी कर सकता है। हालांकि, अनपेक्षित लूप बनाने से बचने के लिए, एक एक्शन वर्कफ़्लो दूसरे को ट्रिगर नहीं करेगा। इसके बजाय, साइट बनाने की प्रक्रिया को Makefile के साथ संभालना अत्यंत सुविधाजनक है, जिसे कोई भी वर्कफ़्लो चला सकता है। बस अपने वर्कफ़्लो जॉब में अंतिम स्टेप के रूप में Makefile चलाना जोड़ें, जहां आवश्यक हो रिपॉजिटरी टोकन के साथ:

- name: Run Makefile
env:
TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: make all

यह सुनिश्चित करता है कि आपके वर्कफ़्लो का अंतिम स्टेप अपडेटेड साइट को बिल्ड और डिप्लॉय करता है।

अब और इवेंट डेटा क्षितिज नहीं

GitHub Actions इवेंट डेटा को कैप्चर और उपयोग करने का एक साफ तरीका प्रदान करता है ताकि यह न केवल GitHub के भीतर उपलब्ध हो। संभावनाएं केवल आपकी कल्पना तक सीमित हैं! यहां कुछ विचार हैं जो यह हमें बनाने देता है:

1. एक सार्वजनिक-फेसिंग इश्यू बोर्ड, जहां GitHub अकाउंट के बिना ग्राहक प्रोजेक्ट इश्यू को देख और फीडबैक दे सकते हैं।
2. किसी भी रिपॉजिटरी के लिए नए इश्यू, टिप्पणियों, या PRs का स्वचालित रूप से अपडेट होने वाला RSS फीड।
3. स्टेटिक साइट्स के लिए एक टिप्पणी प्रणाली, GitHub इश्यू टिप्पणियों को इनपुट विधि के रूप में उपयोग करते हुए।
4. एक शानदार 90 के दशक का गेस्टबुक पेज।

क्या मैंने उल्लेख किया कि मैंने 90 के दशक का गेस्टबुक पेज बनाया? मेरा आंतरिक-जियोसिटीज-नर्ड थोड़ा उत्साहित है।