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

این راهنما بخش‌های مخصوص GitHub در راه‌اندازی را پوشش می‌دهد. GitHub یکی از سه میزبان کد پشتیبانی‌شده است — برای اتصال GitLab یا Bitbucket و برای اینکه یک فضای کاری چگونه آن‌ها را ترکیب می‌کند، اتصال میزبان کد را ببینید.

پیش‌نیازها

یک حساب GitHub با دسترسی به مخزن‌هایی که می‌خواهید روی آن‌ها کار کنید
یا یک GitHub App ثبت‌شده برای سرورتان (به ایجاد GitHub App نگاه کنید) تا بتوانید وارد شوید، یا یک توکن دسترسی شخصی با repo و read:org برای جای‌گذاری

ورود با GitHub

یک جریان دستگاه: GitHub کد کوتاهی به شما نشان می‌دهد، آن را در github.com تأیید می‌کنید و سرور اعتبارنامه را دریافت می‌کند — بدون URL بازگشت، بدون پورت و چیزی برای افشا کردن. هر زمان سرور شناسهٔ کلاینت داشته باشد در دسترس است، که یک نسخهٔ رسمی از پیش آن را همراه دارد.

به تنظیمات → فضای کاری → نمایه و هویت → میزبانی کد بروید (یا نخستین گام راه‌اندازی اولیه)
در ردیف GitHub، روی ورود با GitHub کلیک کنید
یک گفت‌وگو کدی هشت‌نویسه نشان می‌دهد و github.com/login/device را در مرورگر شما باز می‌کند. کد از قبل در کلیپ‌بورد شماست
آن را جای‌گذاری کنید، برنامه را تأیید کنید و برگردید. ردیف خودش به «وارد شده به‌عنوان your-username» تغییر می‌کند

می‌توانید گفت‌وگو را ببندید و کار را در مرورگر تمام کنید — سرور تا انقضای کد (حدود 15 دقیقه) همچنان نظرسنجی می‌کند، پس ورود همچنان انجام می‌شود.

یا یک توکن جای‌گذاری کنید

گزینهٔ پشتیبان وقتی سرور برنامه‌ای ندارد، وقتی برنامه روی حسابی که لازم دارید نصب نیست، یا وقتی به‌سادگی ترجیح می‌دهید از یک PAT استفاده کنید.

به تنظیمات → فضای کاری → نمایه و هویت → میزبانی کد بروید
در ردیف GitHub، روی افزودن توکن کلیک کنید
توکنی با repo و read:org (کلاسیک) جای‌گذاری کنید و ذخیره کنید. یک توکن ریزدانه به Contents و Pull requests مخزن (read and write) و به‌همراه Checks و Actions (read) نیاز دارد.

توکن همان لحظه که ذخیره می‌شود بررسی می‌شود، پس ردیف می‌تواند حسابی که توکن به آن تعلق دارد را نام ببرد. برای برداشتن آن روی قطع اتصال کلیک کنید.

نقطهٔ کنترل: ردیف GitHub می‌گوید «وارد شده به‌عنوان your-username». یک پسوند منبع را نام می‌برد وقتی اعتبارنامه‌ای که پاسخ می‌دهد مال شما نیست — «از طریق برنامهٔ این سرور» یا «از محیط».

یکپارچه‌سازی چه چیزی به شما می‌دهد

ویژگی	چگونه
فهرست و جزئیات PR	API REST در GitHub، از سرور، با هویت برنامه یا اعتبارنامهٔ خودتان
اجراهای بررسی	API بررسی‌های GitHub
انتشار بازبینی	گامی مشروط به کاربر که بازبینی شما را روی PR می‌گذارد
ثبت مخزن	یک checkout پذیرفته می‌شود اگر ریموت `origin` آن به github.com اشاره کند — یا به gitlab.com / bitbucket.org
دسترسی عامل به GitHub	کارگزار اعتبارنامه یک توکن فقط‌خواندنی را به‌صورت `GH_TOKEN` / `GITHUB_TOKEN` تزریق می‌کند؛ پوش‌ها از Control Center می‌گذرند
اعلان‌ها	نظرسنجی سمت سرور از صندوق ورودی اعلان‌های GitHub شما، «در pull request منشن شدید» و «بازبینی درخواست شد» را می‌سازد
نمایه‌های کاربر	کارت‌های شناور نمایه و فیلتر PR به تفکیک نویسنده

برخی مسیرها به‌جای REST از API GraphQL استفاده می‌کنند، جایی که کم‌هزینه‌تر است — فعالیت شاخه برای انتخابگر ساخت PR و وضعیت زندهٔ بازبینی که تعیین می‌کند اعلان «بازبینی درخواست شد» هنوز در انتظار است یا نه.

مراقب قطعی‌های GitHub باشید

نوار عنوان وقتی ارائه‌دهنده‌ای دچار اختلال است یک نشان وضعیت نشان می‌دهد، که GitHub، Claude، OpenAI و Kimi را در بر می‌گیرد. تا وقتی همه چیز سالم است پنهان می‌ماند — حضورش خبر از مشکل می‌دهد، نه غیابش.

روی نشان کلیک کنید تا پنجره‌ای شناور با وضعیت هر ارائه‌دهنده و یک دکمهٔ تازه‌سازی باز شود. وضعیت‌ها هر دو دقیقه خودشان تازه می‌شوند.

بدانید عامل‌ها در GitHub چگونه عمل می‌کنند

عاملی که در یک worktree گیت‌هاب کار می‌کند همیشه یک توکن فقط‌خواندنی GitHub می‌گیرد. پوش‌ها از Control Center می‌گذرند که ابتدا از قاعدهٔ پوش به یک ریموت می‌پرسد و سپس پوش را با یک توکن نوشتنی که عامل هرگز در دست ندارد عبور می‌دهد. به پیکربندی سیاست‌های سندباکس نگاه کنید
کامیت‌هایی که یک عامل می‌سازد به نام خودِ عامل نویسنده می‌شوند — نام نمایشی به‌همراه (agent)، در نشانی‌ای ساختگی که با شناسهٔ عامل کلید خورده است — و هرگز به نام یک انسان. کسی که درخواست کرده با یک trailer Co-Authored-By اعتبار می‌گیرد
با یک GitHub App پیکربندی‌شده، کارگزار در هر راه‌اندازی به‌جای سپردن یک توکن گسترده، توکن‌های نصب ریزدانه، محدود به مخزن و تقریباً یک‌ساعته ضرب می‌کند. نصب از مالک مخزن اجرا حل می‌شود، پس یک برنامه که روی چند حساب نصب شده باشد درست به همان حسابی محدود می‌شود که اجرا با آن سر و کار دارد. بدون برنامه، عامل‌ها توکن محیط را دریافت می‌کنند که نمی‌توان آن را به فقط‌خواندنی محدود کرد: در این حالت قاعدهٔ پوش git push را مقید می‌کند، اما کدی را که آن توکن را مستقیماً به کار می‌برد نه
توکن همیشه مال کارگزار است، هرگز مال عضو درخواست‌کننده. توکن سرور از اجراهایی که به نمایندگی از عضوی که مالک نیست و GitHub را متصل نکرده عمل می‌کنند بازداشته می‌شود

رفع اشکال

فهرست PR خالی است و می‌گوید GitHub متصل نیست

اعتبارنامهٔ GitHub روی این سرور ندارید. زیر میزبانی کد وارد شوید یا یک توکن جای‌گذاری کنید. مخزن‌های روی دیگر میزبان‌های کد تحت تأثیر نیستند — فقط مخزن‌های GitHub چیزی ارائه نمی‌دهند.

ردیف «افزودن توکن» را پیشنهاد می‌دهد ولی «ورود با GitHub» را نه

سرور شناسهٔ کلاینت ندارد — که وضعیت عادی یک ساخت از کد منبع است، چون اعتبارنامه‌ها فقط در نسخه‌های رسمی جای می‌گیرند. به ایجاد GitHub App نگاه کنید: حدود دو دقیقه طول می‌کشد و فقط مالک سرور باید آن را یک بار انجام دهد.

گفت‌وگوی ورود می‌گوید ارائه‌دهنده هیچ کد دستگاهی برنگرداند

GitHub App وجود دارد ولی تیک Device flow آن خاموش است. آن را در تنظیمات برنامه (General → Device flow) روشن کنید و دوباره امتحان کنید.

ردیف می‌گوید «از طریق برنامهٔ این سرور»، حال آنکه انتظار حساب خودم را داشتم

شما وارد نشده‌اید؛ آنچه می‌بینید پاسخ‌دادن هویت برنامهٔ سرور است. روی همان ردیف ورود با GitHub کلیک کنید.

یک PAT ریزدانه دکمهٔ ادغام یا وضعیت بررسی را نشان نمی‌دهد

توکن به Contents و Pull requests (read and write) و به‌همراه Checks و Actions (read) نیاز دارد. پس از تغییر دادنش، آن را دوباره زیر میزبانی کد جای‌گذاری کنید.

افزودن مخزن رد می‌شود

ثبت به هر سه مورد نیاز دارد: مسیر درون یک worktree گیت باشد، یک ریموت origin داشته باشد و آن ریموت به یک میزبان کد پشتیبانی‌شده اشاره کند (github.com، gitlab.com یا bitbucket.org). به افزودن مخزن به فضای کاری نگاه کنید.

پس از استفادهٔ سنگین همه چیز مدتی از کار می‌افتد

آن، قطع‌کنندهٔ مدار محدودیت نرخ است. GitHub محدودیت اصلی‌اش را با یک 403 که x-ratelimit-remaining: 0 و زمانی برای بازنشانی حمل می‌کند اعلام می‌کند؛ کلاینت با دیدن یکی از آن‌ها، درخواست‌های بعدی را تا گذر این پنجره بدون هیچ فراخوانی شبکه‌ای به‌صورت محلی شکست می‌دهد، پس طوفان تلاش دوباره نمی‌تواند محدودیت را عمیق‌تر کند. شکست‌های گذرا با عقب‌نشینی نمایی و با رعایت retry-after تا سه بار تلاش دوباره می‌شوند.