یکپارچه‌سازی GitHub

Status200 خودمیزبان خود را با یک GitHub App که مال خودتان است به GitHub وصل کنید. وقتی برنامه از Status200 نصب شد، مخزن‌های آن نصب به پروژهٔ شما وارد و همگام نگه داشته می‌شوند، کارهای رفع با هوش مصنوعی pull request باز می‌کنند، و تیم شما می‌تواند با نام بردن از برنامه در GitHub کار را به آن بسپارد.

این صفحه برای کسی است که سرور Status200 را اداره می‌کند: برنامه را یک بار می‌سازید و سپس هر پروژه آن را از کد وصل می‌کند.

چگونه کار می‌کند#

نصب در Status200 آغاز می‌شود، نه در GitHub: پیوندی که Status200 شما را با آن به GitHub می‌فرستد، همان چیزی است که نصب را به پروژهٔ شما گره می‌زند.

• هدایت مرورگر، نصب و یک کد OAuth یک‌بارمصرف را با خود می‌آورد. Status200 کد را مبادله می‌کند تا تأیید کند حساب GitHub‌ای که برنامه را نصب کرده آن نصب را مدیریت می‌کند، و سپس مخزن‌های آن را وارد می‌کند. نصبی که از قبل وجود دارد، در عوض با ورود به GitHub وصل می‌شود: آن‌گاه کد به Status200 می‌گوید آن حساب کدام نصب‌ها را مدیریت می‌کند.
• وب‌هوک‌ها فهرست مخزن‌ها را همگام نگه می‌دارند و کار را به برنامه می‌سپارند: اشاره‌ها، واگذاری‌ها، برچسب‌های راه‌انداز و درخواست‌های بازبینی. GitHub هر کدام را با webhook secret امضا می‌کند و Status200 هر کدام را که نتواند تأیید کند رد می‌کند.

پیش از شروع#

• یک حساب GitHub که بتواند برای سازمان یا کاربری که برنامه روی آن نصب می‌شود GitHub App بسازد. برای نصب روی یک سازمان، باید مالک آن باشید یا درخواست را به تأیید یکی از مالکان برسانید.
• یک نام میزبان HTTPS عمومی برای Status200 که GitHub برای وب‌هوک‌ها بتواند به آن برسد. دسترسی شبکه را ببینید.
• دسترسی به پیکربندی سرور: config.env برای Docker Compose، یا مقادیر Helm برای Kubernetes.

ساختن GitHub App#

1. تنظیمات GitHub App را باز کنید#

   • برای یک سازمان: https://github.com/organizations/YOUR_ORG/settings/apps
   • برای یک حساب شخصی: https://github.com/settings/apps

   New GitHub App را برگزینید.

2. فرم ثبت را پر کنید#

   فیلد	مقدار
   GitHub App name	هر نام یکتایی، برای نمونه Status200. آن را دقیق یادداشت کنید: همان GITHUB_APP_NAME است.
   Homepage URL	https://your-oneuptime-domain.com
   Callback URL	https://your-oneuptime-domain.com/api/github/auth/callback
   Request user authorization (OAuth) during installation	روشن. این الزامی است: یادداشت زیر را ببینید.
   Setup URL	https://your-oneuptime-domain.com/api/github/auth/callback، اگر GitHub اجازهٔ وارد کردنش را بدهد (پایین‌تر را ببینید).
   Redirect on update	اختیاری. پس از اینکه کسی نصبی را در GitHub تغییر دهد، Status200 او را به کد می‌برد.
   Webhook URL	https://your-oneuptime-domain.com/api/github/webhook، با وب‌هوک در حالت Active.
   Webhook secret	یک رشتهٔ تصادفی طولانی. آن را یادداشت کنید: همان GITHUB_APP_WEBHOOK_SECRET است. الزامی: Status200 وب‌هوک‌های امضانشده را رد می‌کند، پس تنظیم نکردن GITHUB_APP_WEBHOOK_SECRET به‌جای پذیرفتن داده‌های تأییدنشده، همگام‌سازی مخزن‌ها را متوقف می‌کند.

   به گفتهٔ مستندات GitHub، با روشن بودن Request user authorization (OAuth) during installation نمی‌توانید Setup URL وارد کنید: کاربران پس از نصب برنامه به‌جای آن به Callback URL فرستاده می‌شوند. هر دو به یک نشانی Status200 اشاره می‌کنند، پس در هر حال هدایت به جای درست می‌رسد.

   مهم

   چرا «Request user authorization (OAuth) during installation» الزامی است. پس از یک نصب، GitHub با یک installation_id در نشانی برمی‌گرداند. این عدد به‌تنهایی چیزی دربارهٔ مالک نصب ثابت نمی‌کند — هر کسی می‌تواند عدد دیگری تایپ کند. با روشن بودن این گزینه، GitHub یک code یک‌بارمصرف OAuth هم برمی‌گرداند که به حساب GitHub‌ای که نصب را انجام داده گره خورده است، و Status200 آن را مبادله می‌کند تا پیش از وصل کردن نصب به پروژهٔ شما تأیید کند که آن حساب واقعاً نصب را مدیریت می‌کند.

   بدون آن، Status200 از وصل کردن نصب خودداری می‌کند و داشبورد خطایی نشان می‌دهد که از شما می‌خواهد این تنظیم را روشن کنید. این عمدی است: پذیرفتن شناسهٔ نصب بدون تأیید به یک پروژهٔ Status200 اجازه می‌داد مخزن‌های سازمان دیگری را از آن خود کند.

3. مجوزها را تنظیم کنید#

   زیر Permissions & events، این Repository permissions را تنظیم کنید:

   مجوز	دسترسی	Status200 آن را برای چه به کار می‌برد
   Contents	Read and write	خواندن فایل‌های مخزن و push کردن شاخه‌های pull requestهای رفع با هوش مصنوعی
   Pull requests	Read and write	باز کردن و به‌روزرسانی pull requestها و انتشار بازبینی‌ها
   Issues	Read and write	انتشار نظرهای برنامه — از جمله روی pull requestها، که GitHub گفت‌وگوی آن‌ها را از راه API مربوط به issues می‌گذراند
   Checks	Read-only	اختیاری. خواندن نتیجهٔ CI در pull requestهای رفع. بدون آن، وضعیت CI آن‌ها تأییدنشده می‌ماند
   Metadata	Read-only	فرادادهٔ پایهٔ مخزن (GitHub آن را الزامی می‌داند)

   آنچه برنامه را تعاملی می‌کند Issues: Read and write است. بدون آن، اشاره‌ها دریافت می‌شوند و سپس وقتی برنامه می‌خواهد پاسخ دهد بی‌صدا شکست می‌خورند — GitHub نظرهای گفت‌وگوی pull requestها را از API مربوط به issues ارائه می‌کند، پس همین یک مجوز سرنوشت هر پاسخی را که برنامه می‌نویسد تعیین می‌کند. کار با Status200 از GitHub را ببینید.

   Status200 به هیچ مجوز سازمانی یا حسابی نیاز ندارد.

4. مشترک رویدادهای وب‌هوک شوید#

   Status200 از دو دسته رویداد استفاده می‌کند و هر کدام کار متفاوتی انجام می‌دهد.

   همگام‌سازی مخزن‌ها — installation و installation_repositories. GitHub Appها این‌ها را خودکار دریافت می‌کنند؛ این رویدادها مجموعهٔ مخزن‌های وصل‌شده را با جایی که برنامه نصب شده هماهنگ نگه می‌دارند.

   برنامهٔ تعاملی — باید صریحاً مشترک این رویدادها شوید، و هر کدام راه مشخصی را برای سپردن کار به برنامه فعال می‌کند:

   رویداد	چه چیزی را ممکن می‌کند
   Issue comment	فرمان‌های @mention در issueها و در pull requestها
   Issues	واگذاری یک issue به برنامه، و برچسب راه‌انداز مخزن
   Pull request	درخواست بازبینی از برنامه، و بازبینی‌های عملیاتی درخواست‌های ادغام هنگام باز شدن و تغییرشان
   Pull request review	اشاره‌ای که در متن یک بازبینی ارسال‌شده نوشته شده است
   Pull request review comment	اشاره در یک نظر درون‌خطی در diff

   اگر مشترک هیچ‌کدام از این‌ها نباشید، GitHub App همچنان مخزن‌ها را وصل می‌کند و همچنان از Status200 pull requestهای رفع باز می‌کند — فقط هرگز به چیزی که در GitHub نوشته می‌شود پاسخ نمی‌دهد. این رایج‌ترین علت «ربات مرا نادیده می‌گیرد» است. برای اینکه فرمان‌ها چیستند و چه کسی می‌تواند آن‌ها را بدهد، کار با Status200 از GitHub را ببینید.

   رویدادهای دیگر (Push، Workflow run) تأیید و نادیده گرفته می‌شوند؛ مشترک شدن در آن‌ها اعلان یا خودکارسازی CI/CD را فعال نمی‌کند.

5. جایی را که برنامه می‌تواند نصب شود برگزینید#

   زیر Where can this GitHub App be installed? برگزینید:

   • Only on this account - برای استفادهٔ خصوصی/داخلی
   • Any account - اگر می‌خواهید دیگران هم برنامهٔ شما را نصب کنند

6. برنامه را بسازید و شناسه‌هایش را یادداشت کنید#

   Create GitHub App را برگزینید. GitHub صفحهٔ تنظیمات برنامه را باز می‌کند. App ID را در بالای صفحه و Client ID را در بخش About یادداشت کنید.

7. یک client secret بسازید#

   زیر Client secrets، Generate a new client secret را برگزینید. بی‌درنگ آن را کپی کنید: GitHub فقط یک بار آن را نشان می‌دهد.

8. یک کلید خصوصی بسازید#

   زیر Private keys، Generate a private key را برگزینید. GitHub یک فایل .pem دانلود می‌کند. آن را امن نگه دارید: Status200 با آن به‌عنوان برنامه احراز هویت می‌کند.

پیکربندی Status200#

base64 < private-key.pem | tr -d '\n'

GITHUB_APP_ID=YOUR_APP_ID
GITHUB_APP_NAME=YOUR_APP_NAME
GITHUB_APP_CLIENT_ID=YOUR_CLIENT_ID
GITHUB_APP_CLIENT_SECRET=YOUR_CLIENT_SECRET
GITHUB_APP_PRIVATE_KEY=YOUR_BASE64_ENCODED_PRIVATE_KEY
GITHUB_APP_WEBHOOK_SECRET=YOUR_WEBHOOK_SECRET

gitHubApp:
  id: "YOUR_APP_ID"
  name: "YOUR_APP_NAME" # The exact name of your GitHub App
  clientId: "YOUR_CLIENT_ID"
  clientSecret: "YOUR_CLIENT_SECRET"
  privateKey: "<BASE64_ENCODED_PRIVATE_KEY_CONTENT>"
  webhookSecret: "YOUR_WEBHOOK_SECRET"

وقتی Status200 دوباره بالا آمد، کد به‌جای GitHub App روی این سرور پیکربندی نشده است گزینهٔ اتصال GitHub را نشان می‌دهد.

مرجع متغیرهای محیطی#

هر شش مقدار الزامی‌اند.

وصل کردن مخزن‌ها#

اتصال را از Status200 آغاز کنید، نه از صفحهٔ برنامه در GitHub: پیوندی که Status200 شما را با آن به GitHub می‌فرستد، همان چیزی است که نصب را به پروژهٔ شما گره می‌زند.

وقتی برنامه از پیش روی حساب نصب شده است، برای پروژه‌ای دیگر یا مستقیم از GitHub، نصب دوباره آن را وصل نمی‌کند: GitHub تنظیمات نصب را باز می‌کند و هرگز شما را برنمی‌گرداند. به‌جای آن، زیر اتصال GitHub روی اتصال یک نصب موجود کلیک کنید. وارد GitHub می‌شوید و Status200 نصبی را وصل می‌کند که حساب GitHub شما مدیریت می‌کند. اگر بیش از یکی را مدیریت کند، کد فهرست آن‌ها را نشان می‌دهد: حسابی را انتخاب کنید که پروژه باید از مخزن‌هایش استفاده کند.

چه کسی می‌تواند وصل کند. وصل کردن، مخزن‌های نصب را به پروژه وارد می‌کند، پس به اجازهٔ افزودن مخزن کد نیاز دارد: Project Owner، Project Admin، Project Member، Settings Admin، Settings Member، یا تیمی با Create Code Repository. تیمی که این مجوز را مسدود کند، آن را پس می‌گیرد. در Status200 Cloud مخزن‌های کد به طرح Growth یا بالاتر نیاز دارند. برای هر کس دیگر، کارت قفل است و می‌گوید چه چیزی لازم است. در GitHub، حسابی که برنامه را نصب یا وصل می‌کند باید آن نصب را مدیریت کند: مالک یک حساب شخصی، یا کسی که روی همهٔ مخزن‌هایی که نصب به آن‌ها دسترسی دارد دسترسی admin دارد، همان‌طور که مالک سازمان دارد. دسترسی خواندن به یکی از مخزن‌های آن کافی نیست.

ظرف ۱۵ دقیقه و در همان مرورگر کار را تمام کنید. پیوند یک بار، به مدت ۱۵ دقیقه، در همان مرورگری کار می‌کند که آن را آغاز کرده است. وقتی GitHub شما را برمی‌گرداند، Status200 پیش از وارد کردن هر چیزی مجوز را دوباره بررسی می‌کند.

دسترسی شبکه برای استقرارهای خودمیزبان#

جهت ترافیک و نقطه‌های پایانی#

callback یک هدایت در مرورگر است، در حالی که وب‌هوک درخواستی از سرورهای GitHub است. اتصال VPN یک کاربر به GitHub دسترسی به وب‌هوک نمی‌دهد. دامنه‌های بالا درخواست‌های اصلی یکپارچه‌سازی را پوشش می‌دهند؛ ابزارهای اضافی مخزن، دانلودها، LFS یا بسته‌ها ممکن است به مقصدهای دیگری نیاز داشته باشند. این تنظیمات دربارهٔ GitHub.com است؛ تغییر فایروال پشتیبانی از نام میزبان GitHub Enterprise Server را پیکربندی نمی‌کند.

استقرارهای خصوصی و امنیت فراخوان‌های بازگشتی#

/api/github/webhook را از راه یک دروازهٔ عمومی در دسترس بگذارید که DNS عمومی، یک گواهی HTTPS مورد اعتماد عموم با زنجیرهٔ کامل و یک مسیر خصوصی تا ingress در Status200 داشته باشد. TCP ۴۴۳ ورودی به دروازه را مجاز کنید و هدایت عمومی را به همین مسیر POST محدود کنید. اگر کاربران از راه VPN به داشبورد و callback مرورگر دسترسی دارند، آن‌ها را روی ingress خصوصی نگه دارید؛ DNS دوپاره می‌تواند همان نام میزبان را در داخل و بیرون ارائه کند.

HOST=status200.example.com و HTTP_PROTOCOL=https را در config.env، یا host: status200.example.com و httpProtocol: https را در Helm تنظیم کنید. پیکربندی را اعمال کنید و صبر کنید تا Status200 دوباره راه‌اندازی شود. این مقادیر نشانی‌ها را می‌سازند؛ DNS، TLS یا دسترسی شبکه فراهم نمی‌کنند. اگر نام میزبان تغییر کند، نشانی‌های webhook، callback، setup و صفحهٔ اصلی GitHub App را به‌روز کنید.

روش، مسیر اصلی، رشتهٔ پرس‌وجو، بدنه، Content-Type، X-Hub-Signature-256، X-GitHub-Event و X-GitHub-Delivery را نگه دارید. میزبان عمومی و طرح HTTPS را از راه سرآیندهای مورد اعتماد پراکسی نگه دارید. وب‌هوک را از SSO مرورگر، CAPTCHA و صفحه‌های ورود پراکسی معاف کنید. بررسی SSL در GitHub را روشن نگه دارید و در هر دو سامانه همان GITHUB_APP_WEBHOOK_SECRET را پیکربندی کنید: Status200 درخواست‌های امضانشده را رد می‌کند و بدون این راز نمی‌تواند وب‌هوک‌ها را اعتبارسنجی کند. راهنمای GitHub دربارهٔ اعتبارسنجی وب‌هوک‌ها را ببینید.

اگر IP مبدأ وب‌هوک‌ها را هم محدود می‌کنید، از محدوده‌های کنونی hooks در Meta API مربوط به GitHub استفاده کنید و آن‌ها را مرتب به‌روز کنید؛ محدوده‌های اجراکننده‌های GitHub Actions را جایگزین آن‌ها نکنید و بررسی امضا را کنار نگذارید. GitHub هشدار می‌دهد که نشانی‌هایش تغییر می‌کنند و فهرست منتشرشده کامل نیست.

تأیید دسترسی و شناخت محدودیت‌ها#

GitHub عیب‌یابی تحویل‌ها را مستند کرده و تأیید 2xx ظرف ده ثانیه را الزامی می‌داند. یک GET از مرورگر به وب‌هوک، یک POST امضاشده را نمی‌آزماید.

تنظیم دسترسی به شبکهٔ خصوصی درخواست‌های خروجی به مقصدهای خصوصی را کنترل می‌کند و وب‌هوک را برای GitHub در دسترس نمی‌گذارد.

عیب‌یابی#

اتصال کامل نشد#

وقتی GitHub شما را برمی‌گرداند و نصب وصل نشده است، کد پیام GitHub وصل نشد را همراه یک جمله به زبان شما نشان می‌دهد که دلیلش را می‌گوید. بقیهٔ صفحه مثل همیشه بارگذاری می‌شود، پس می‌توانید همان‌جا دوباره وصل کنید. پاسخ خود GitHub هرگز نشان داده نمی‌شود: آن پاسخ همراه دلیل در لاگ سرور Status200 است.

مشکلات دیگر#

بهترین شیوه‌های امنیتی#

• رازها را مرتب عوض کنید. هر چند وقت یک بار client secret و کلید خصوصی تازه بسازید.
• webhook secret را تنظیم‌شده نگه دارید. Status200 وب‌هوک‌هایی را که نتواند تأیید کند رد می‌کند.
• دسترسی به مخزن‌ها را محدود کنید. فقط مخزن‌هایی را به نصب بدهید که باید وصل شوند.
• تحویل وب‌هوک‌ها را زیر نظر داشته باشید. مرتب تحویل‌های ناموفق یا فعالیت مشکوک را بررسی کنید.
• کلیدهای خصوصی را بیرون از کنترل نسخه نگه دارید.

گام‌های بعدی#