ایجاد GitHub App

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

شاید به آن نیازی نداشته باشید

یک ساخت رسمی از پیش یک شناسهٔ کلاینت GitHub همراه دارد، پس ورود با GitHub بدون هیچ ثبت‌نامی کار می‌کند — جریان دستگاه تنها با شناسهٔ کلاینت احراز هویت می‌کند، پس همراه داشتن آن ایمن است. برنامهٔ خودتان را ثبت کنید وقتی می‌خواهید سرور به نام خودش عمل کند (وبهوک‌ها، نظرسنجی PR و همگام‌سازی تیکت روی نصب یک برنامه اجرا شوند، نه روی اعتبارنامهٔ یک شخص)، یا وقتی از کد منبع می‌سازید.

برای اتصال حساب خودتان پس از این کار، راه‌اندازی یکپارچه‌سازی GitHub را ببینید.

چرا سرور شما به برنامهٔ خودش نیاز دارد

از یک ثبت‌نام، دو کار متفاوت بیرون می‌آید و برنامه همان چیزی است که هر دو را صادق می‌کند:

کار	چه چیزی پاسخ می‌دهد	چرا مهم است
یک شخص وارد می‌شود	شناسهٔ کلاینت برنامه، از راه جریان دستگاه	اعتبارنامه‌ای می‌گیرید که مال خودتان است، روی سرور و روی هر دستگاه — بدون توکنی که باید جای‌گذاری یا چرخش دهید
سرور عمل می‌کند	شناسهٔ برنامه + کلید خصوصی ← توکن نصب	وبهوک‌ها، نظرسنجی PR و همگام‌سازی تیکت دیگر به معتبر ماندن توکن یک انسان وابسته نیستند

توجه کنید چه چیزی در آن جدول نیست: راز کلاینت. جریان دستگاه GitHub تنها با شناسهٔ کلاینت احراز هویت می‌کند — هم درخواست کد دستگاه و هم نظرسنجی توکن — پس رازی برای نگه‌داشتن به‌خاطر ورود وجود ندارد.

بدون برنامهٔ اختصاصی، کار اول همچنان با شناسهٔ کلاینتی که ساخت همراه دارد کار می‌کند؛ کار دوم به اعتبارنامهٔ مالک سرور برمی‌گردد، پس کار پس‌زمینه سوار بر اعتبار کسی می‌شود که اول از همه راه‌اندازی کرده است.

دکمهٔ «نصب GitHub App متعلق به Control Center» وجود ندارد

یک GitHub App توزیع‌شده یعنی یک راز کلاینت مشترک و یک نصب مشترک روی سرورهای همه؛ آن‌وقت دسترسی هر فضای کاری به مخزن‌ها از میان اعتبارنامه‌هایی می‌گذرد که هیچ‌کس در آن فضای کاری کنترلی بر آن‌ها ندارد. پس هر سرور برنامهٔ خودش را دارد — این راهنما دربارهٔ این است که این کار چقدر کم هزینه است.

پیش‌نیازها

• شما مالک سرور هستید — عملیات providerApps.* فقط برای او باز است، و آن کارت برای بقیه نامرئی است
• یک حساب GitHub، یا سازمانی که بتوانید در آن برنامه بسازید
• هیچ چیز نباید از اینترنت در دسترس باشد: ورود یک جریان دستگاه است، پس سرور به پورت ورودی، تونل، URL بازگشت یا دامنه نیازی ندارد

ثبت برنامه

1. به github.com/settings/apps/new بروید (برای یک سازمان: Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name — هر چیزی؛ Control Center (yourname) هم خوب است. این نام روی کامیت‌ها و نظرهایی که سرور می‌گذارد دیده می‌شود
3. Homepage URL — هر چیزی، مثلاً https://github.com/your-name
4. Callback URL — آن را خالی بگذارید. جریان دستگاه آن را ندارد
5. تیک Enable Device Flow را بزنید. این تنها تنظیمی است که ورود بدون آن کار نمی‌کند
6. تیک Webhook → Active را بردارید، مگر اینکه وبهوک‌ها را جداگانه وصل کنید
7. زیر Repository permissions، حداقل این‌ها را بدهید:
   • Contents: Read and write
   • Metadata: Read-only (الزامی)
   • Pull requests: Read and write
   • Issues: Read and write، اگر برای تیکت‌ها از GitHub Issues استفاده می‌کنید و برای جستجوی نظرهای گفتگوی PR توسط ربات (به گفتگو با Control Center از یک pull request در GitHub نگاه کنید)
   • Checks: Read-only، برای وضعیت CI در صفحهٔ PR
8. زیر Where can this GitHub App be installed?، هر کدام که مناسب است را انتخاب کنید — «Only on this account» برای یک سرور شخصی درست است
9. روی Create GitHub App کلیک کنید

جمع‌آوری سه مقدار

در صفحهٔ برنامه، بلافاصله پس از ساخت:

مقدار	کجا
App ID	تب General، نزدیک بالای صفحه
Client ID	تب General، زیر «Client secrets»
Private key	Generate a private key — یک فایل .pem دانلود می‌شود

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

راز کلاینت اختیاری است و دقیقاً یک چیز می‌خرد: اگر «Expire user authorization tokens» را روشن بگذارید، همان است که توکن شخص را بی‌صدا تازه می‌کند، به‌جای اینکه هر هشت ساعت دوباره از او بخواهد وارد شود. خودِ ورود هرگز از آن استفاده نمی‌کند.

راه‌اندازی ساده‌تر این است که آن انقضا را خاموش کنید؛ آن‌وقت هیچ‌جا به رازی نیاز نیست. اگر روشنش نگه دارید، یک راز بسازید و آن را در تنظیمات ← سرور ← ورود یکپارچه (کارت برنامه‌های ارائه‌دهنده) جای‌گذاری کنید — متغیر محیطی‌ای برای آن وجود ندارد و هیچ‌کدام هم در ساخت پخته نمی‌شود، پس روی سرور خودتان می‌ماند.

نصب آن روی حساب شما

برنامه‌ای که ثبت شده ولی نصب نشده باشد، می‌تواند افراد را احراز هویت کند و هیچ چیز نمی‌خواند.

1. در صفحهٔ برنامه، Install App را باز کنید
2. آن را روی حساب یا سازمان خود نصب کنید
3. All repositories را انتخاب کنید، یا مخزن‌هایی را برگزینید که این سرور باید ببیند

جای‌گذاری آن در Control Center

1. به تنظیمات ← سرور ← ورود یکپارچه بروید و تا کارت برنامه‌های ارائه‌دهنده پایین بروید
2. در بلوک GitHub، هر فیلد را تنظیم کنید:
   • شناسهٔ برنامه — همان App ID عددی
   • کلید خصوصی — کل .pem را جای‌گذاری کنید، با احتساب سطرهای BEGIN و END
   • شناسهٔ کلاینت — از همان صفحه
   • راز کلاینت — فقط اگر یکی ساخته باشید (برای تازه‌سازی توکن)
3. روی آزمایش کلیک کنید

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

نقطهٔ بررسی: در بلوک GitHub «سرور می‌تواند به‌عنوان خودش عمل کند، و افراد می‌توانند وارد شوند.» خوانده می‌شود، و ردیف GitHub زیر تنظیمات ← فضای کاری ← نمایه و هویت ← میزبانی کد اکنون ورود با GitHub را پیشنهاد می‌دهد.

پیکربندی آن با متغیرهای محیطی به‌جای این کار

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

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

هیچ پرچم خط فرمانی برای این‌ها وجود ندارد — رازی روی خط فرمان، برای هر فرایند روی میزبان با ps قابل خواندن است. محیط تنها جای پیکربندی آن‌هاست و بر هر چیزی که ساخت همراه دارد اولویت دارد. .env.template فهرست کامل است.

برای توسعهٔ محلی، .env در ریشهٔ مخزن همان مقادیر را دارد و دسکتاپ آن‌ها را به سروری که اجرا می‌کند می‌فرستد. کلید را آن‌جا در یک خط بگذارید: مقدار یک .env یک خط است و \n داخل گیومه‌های دوتایی به خط جدید تفسیر می‌شود.

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID و GITHUB_APP_PRIVATE_KEY همان نام‌هایی هستند که کارگزار توکن سندباکس از قبل می‌خواند، پس میزبانی که توکن‌های ریزدانهٔ عامل را پیکربندی کرده، مسیر ورود را مجانی می‌گیرد. پرکردن یک‌بار برای هر فیلد رخ می‌دهد — بعد از آن مقدار ذخیره‌شده برنده است، پس ویرایش در تنظیمات با راه‌اندازی دوبارهٔ بعدی از بین نمی‌رود.

انجام همین کار برای Linear

Linear جریان دستگاه ندارد، پس ورود آن یک رفت‌وبرگشت در مرورگر است و به URL بازگشت نیاز دارد — کارت برنامه‌های ارائه‌دهنده دقیقاً همان نشانی‌ای را که باید ثبت کنید نشان می‌دهد.

1. یک برنامهٔ OAuth در linear.app/settings/api/applications/new بسازید
2. Callback URL را عیناً روی همان URL که کارت نشان می‌دهد بگذارید
3. شناسهٔ کلاینت و راز کلاینت را در بلوک Linear جای‌گذاری کنید
4. به اختیار یک کلید API فضای کاری اضافه کنید — همان اعتبارنامه‌ای است که سرور برای همگام‌سازی تیکت‌ها به کار می‌برد وقتی هیچ انسانی درخواست نکرده

عیب‌یابی

پنجرهٔ ورود می‌گوید ارائه‌دهنده کد دستگاهی برنگرداند

Enable Device Flow در برنامه خاموش است. آن را زیر General روشن کنید و دوباره امتحان کنید.

آزمایش می‌گوید اعتبارنامه‌ها کار می‌کنند ولی برنامه هیچ‌جا نصب نیست

ثبت و نصب دو گام جدا هستند. در صفحهٔ برنامه Install App را باز کنید و نصبش کنید.

آزمایش می‌گوید کلید خصوصی خوانده نشد

کل فایل .pem را جای‌گذاری کنید، همراه با سطرهای -----BEGIN و -----END. کلید ed25519 یا EC قابل استفاده نیست — GitHub Appها با RSA امضا می‌کنند.

عضوی وارد شده ولی هیچ مخزنی نمی‌بیند

برنامه روی حسابی که مالک آن‌هاست نصب نشده، یا نصبش مخزن‌های دیگری را انتخاب کرده است. ورود خودِ آن شخص تنها همان چیزی را می‌دهد که برنامه اجازهٔ دیدنش را دارد.

راهنماهای مرتبط

• راه‌اندازی یکپارچه‌سازی GitHub
• گفتگو با Control Center از یک pull request در GitHub
• اتصال میزبان کد
• مدیریت کلیدهای API
• راه‌اندازی یکپارچه‌سازی Slack