اتصال به GitHub

اتصال GitHub کار توسعه را کنار وظیفه‌ها می‌آورد. مدیر فضای کاری یک بار اپ GitHub تسکیـ را نصب می‌کند؛ از آن به بعد هر پول‌ریکوئست، ایشو، شاخه یا کامیتی که شناسهٔ وظیفه‌ای مثل TASK-12 را بیاورد، در بخش «توسعه»ی همان وظیفه فهرست می‌شود و ادغام پول‌ریکوئستی که عبارت بستن دارد، وظیفه را تکمیل می‌کند.

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

پیش از شروع

• در تسکیـ باید مالک یا مدیر فضای کاری باشید.
• در GitHub باید اجازهٔ نصب اپ روی حساب یا سازمان موردنظر را داشته باشید. اگر عضو عادی سازمان باشید، GitHub به‌جای نصب، درخواست شما را برای مالکان سازمان می‌فرستد.
• اتصال GitHub یکی از یکپارچه‌سازی‌های فضای کاری حساب می‌شود و سقف تعداد آن‌ها به پلن بستگی دارد؛ صفحهٔ اپ نشان می‌دهد چند مورد از این سقف را استفاده کرده‌اید.
• تسکیـ فایل‌های کد شما را باز نمی‌کند. از رویدادهای مخزن‌هایی که به اپ اجازه داده‌اید فقط عنوان و توضیح پول‌ریکوئست و ایشو، نام شاخه، پیام کامیت و نتیجهٔ اجرای ورک‌فلوها به کار می‌رود.

نصب اپ GitHub

تسکیـ برای GitHub از یک GitHub App استفاده می‌کند؛ یعنی خودتان در GitHub تعیین می‌کنید اپ کدام مخزن‌ها را ببیند، و نیازی به ساختن وب‌هوک دستی نیست.

1. از تنظیمات، «مرکز اپ‌ها» را باز کنید و روی کارت GitHub بزنید.
2. در صفحهٔ اپ، زبانهٔ «فضای کاری» را انتخاب کنید و در بخش «ساخت اتصال فضای کاری» روی «اتصال» بزنید.
3. در GitHub، حساب یا سازمانی را که مخزن‌ها در آن هستند انتخاب کنید، تعیین کنید اپ به همهٔ مخزن‌ها دسترسی داشته باشد یا فقط به مخزن‌های انتخابی، و نصب را تأیید کنید.
4. GitHub یک بار ورود شما را می‌خواهد. با این کار تسکیـ بررسی می‌کند که این نصب واقعاً متعلق به حساب شماست.
5. به صفحهٔ GitHub در «مرکز اپ‌ها» برمی‌گردید و کارت اتصال ظاهر می‌شود. فهرست مخزن‌ها در پس‌زمینه دریافت می‌شود و چند لحظه بعد در «مدیریت» دیده می‌شود.

اگر اتصال کامل نشد: اگر عضو سازمان باشید ولی مالک آن نباشید، پیام «درخواست شما برای مالکان سازمان ارسال شد» را می‌بینید؛ پس از تأیید مالکان، دوباره «اتصال» را بزنید. اگر اپ از قبل روی سازمان نصب شده باشد، فقط مالک همان سازمان می‌تواند آن نصب را وصل کند. هر نصب GitHub هم فقط به یک فضای کاری تسکیـ وصل می‌شود.

مدیریت اتصال و سلامت آن

کارت اتصال در صفحهٔ اپ وضعیت را با یکی از برچسب‌های «فعال»، «نیازمند بررسی» یا «قطع» نشان می‌دهد، دلیل مشکل را می‌نویسد (مثلاً معلق یا حذف‌شدن اپ در GitHub) و زمان آخرین رویداد را می‌گوید. دکمهٔ «مدیریت» صفحه‌ای با این بخش‌ها باز می‌کند:

• مخزن‌ها: فهرست مخزن‌هایی که اپ می‌بیند. افزودن یا برداشتن مخزن در تنظیمات اپ در خودِ GitHub انجام می‌شود و تسکیـ همان فهرست را خودکار دنبال می‌کند؛ اگر تغییری دیر رسید، «همگام‌سازی دوباره» را بزنید.
• تسکی به چه چیزهایی گوش می‌دهد: کلیدهای «درخواست‌های ادغام (PR)»، «ایشوها»، «پایپ‌لاین‌ها و اجرای ورک‌فلوها»، «پوش شاخه‌ها و کامیت‌ها»، «اتصال وظیفه‌هایی که شناسه‌شان آمده» و «جابه‌جایی و تکمیل وظیفه‌ها». با خاموش کردن هرکدام، تسکیـ آن نوع رویداد یا رفتار را کنار می‌گذارد.
• قواعد: چهار قاعدهٔ اختیاری برای کامنت‌گذاشتن و تکمیل وظیفه که در ادامه توضیح داده شده‌اند.
• رویدادهای اخیر: آخرین رویدادهای رسیده از GitHub با وضعیت هرکدام («پردازش‌شده»، «ردشده»، «ناموفق» و…) و دلیل ردشدن. رویداد ناموفق را با «تلاش دوباره» دوباره در صف بگذارید؛ ارسال دوباره (Redeliver) از تنظیمات اپ در GitHub هم پذیرفته می‌شود.

لینک خودکار با شناسهٔ وظیفه

کافی است شناسهٔ وظیفه را در کار GitHub بنویسید. تسکیـ آن را در نام شاخه، پیام کامیت، عنوان و توضیح پول‌ریکوئست و عنوان و توضیح ایشو پیدا می‌کند و آن مورد را به وظیفه وصل می‌کند. این شکل‌ها پذیرفته می‌شوند:

• TASK-12 — خودِ شناسهٔ نمایشی وظیفه؛ با حروف کوچک (task-12) هم خوانده می‌شود.
• #TASK-12 یا CU-TASK-12 — همان شناسه با پیشوند.
• رقم‌های فارسی هم شناخته می‌شوند؛ TASK-۱۲ همان TASK-12 است.

برای نمونه، شاخهٔ feature/TASK-12-login یا کامیتی با پیام TASK-12 Fix login redirect خودکار به وظیفهٔ TASK-12 وصل می‌شود. شناسه نباید به حرف یا رقمِ پیش از خودش چسبیده باشد؛ مثلاً در xTASK-12 خوانده نمی‌شود. لینک خودکار فقط برای مخزن‌هایی کار می‌کند که اپ به آن‌ها دسترسی دارد و فقط وظیفه‌های همان فضای کاری را پیدا می‌کند.

بخش «توسعه» در وظیفه

وقتی فضای کاری اتصال فعال GitHub یا GitLab داشته باشد، در پنجرهٔ هر وظیفه دکمهٔ «توسعه» با شمار موارد متصل دیده می‌شود. این بخش موارد را دسته‌بندی‌شده نشان می‌دهد: «درخواست‌های ادغام (PR / MR)»، «شاخه‌ها»، «کامیت‌ها»، «ایشوها» و «سایر لینک‌ها». کنار پول‌ریکوئست یا شاخهٔ متصل، نتیجهٔ آخرین اجرای GitHub Actions هم دیده می‌شود.

• کار روی این وظیفه: رشته‌های آمادهٔ کپی با شناسهٔ وظیفه: «نام شاخه»، دستور «ساخت شاخه» (git checkout -b …)، «پیام کامیت» و عبارت «بستن با ادغام» (Fixes TASK-12).
• افزودن لینک: نشانی یک پول‌ریکوئست، ایشو یا کامیت GitHub را بچسبانید تا دستی به وظیفه وصل شود. هر لینک را هم می‌توانید با «حذف لینک» بردارید.
• ساخت شاخه و ساخت ایشو: روی یکی از مخزن‌های متصل، شاخه‌ای با نام پیشنهادی از شاخهٔ پیش‌فرض مخزن، یا ایشویی با عنوان وظیفه بسازید. مورد ساخته‌شده بلافاصله به وظیفه وصل می‌شود و در انتهای توضیح ایشو پیوندی به وظیفه اضافه می‌شود.

افزودن و حذف لینک و ساخت شاخه یا ایشو برای کسانی فعال است که اجازهٔ ویرایش در آن پروژه را دارند. شاخه و ایشو فقط روی مخزن‌هایی ساخته می‌شوند که در «مدیریت» اتصال فهرست شده‌اند.

تکمیل و جابه‌جایی خودکار وظیفه

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

• close، closes، closed
• fix، fixes، fixed
• resolve، resolves، resolved

بزرگی و کوچکی حروف مهم نیست و بعد از کلمه می‌توانید دونقطه بگذارید (Fixes: TASK-12). چند وظیفه را هم می‌توان با ویرگول یا and پشت سر هم آورد: Closes TASK-12, TASK-15 and TASK-18. کلمه‌های فارسی مثل «رفع» عبارت بستن حساب نمی‌شوند، و بستن پول‌ریکوئست بدون ادغام هم وظیفه را تکمیل نمی‌کند. با تکمیل، وظیفه به وضعیت پایانی پروژه می‌رود.

دو قاعدهٔ اختیاری در بخش «قواعد» این رفتار را گسترده‌تر می‌کنند و هر دو به‌طور پیش‌فرض خاموش‌اند:

• «تکمیل وظیفه‌هایی که در پوش به شاخهٔ اصلی بعد از کلمهٔ بستن آمده‌اند»: کامیتی با پیام Fixes TASK-12 که مستقیم به شاخهٔ پیش‌فرض مخزن push شود، وظیفه را تکمیل می‌کند.
• «تکمیل وظیفه وقتی شاخهٔ ادغام‌شده به نام آن است، حتی بدون کلمهٔ بستن»: ادغام پول‌ریکوئست از شاخه‌ای مثل TASK-12-login کافی است.

تغییر وضعیت با کروشه

اگر بلافاصله بعد از شناسه نام یک وضعیت را در کروشه بنویسید، وظیفه به همان وضعیت می‌رود؛ مثلاً TASK-12[In Review] یا TASK-12[در حال بررسی]. این دستور در نام شاخه، پیام کامیت و عنوان یا توضیح پول‌ریکوئست و ایشو خوانده می‌شود. بین شناسه و کروشه فاصله نگذارید. نام باید با یکی از وضعیت‌های همان پروژه بخواند، ولی بزرگی و کوچکی حروف مهم نیست؛ اگر وضعیتی با آن نام پیدا نشود، وظیفه فقط وصل می‌شود.

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

تسکیـ چه چیزی به GitHub می‌فرستد

• یک کامنت برای هر لینک: اولین باری که تسکیـ یک پول‌ریکوئست یا ایشو را به وظیفه‌ای وصل می‌کند، یک کامنت کوتاه با شناسه و پیوند وظیفه روی آن می‌گذارد. قاعدهٔ «وقتی تسکی یک PR، MR یا ایشو را به وظیفه‌ای متصل می‌کند، روی آن کامنت بگذارد» این کار را کنترل می‌کند و به‌طور پیش‌فرض روشن است.
• عنوان وظیفه: به‌طور پیش‌فرض در کامنت نمی‌آید، چون مخزن ممکن است عمومی باشد. با قاعدهٔ «عنوان وظیفه هم در آن کامنت بیاید» می‌توانید آن را اضافه کنید.
• شاخه و ایشوی تازه: فقط وقتی که خودتان از بخش «توسعه» بسازید.

تسکیـ جز این‌ها چیزی در GitHub تغییر نمی‌دهد؛ مثلاً تکمیل وظیفه در تسکیـ، پول‌ریکوئست یا ایشو را نمی‌بندد.

فعالیت وظیفه و اعلان‌ها

افزوده‌شدن و حذف لینک و تغییر وضعیت پول‌ریکوئست یا ایشوی متصل با برچسب GitHub در فعالیت وظیفه ثبت می‌شود. مسئول و سازندهٔ وظیفه هم در این موارد اعلان می‌گیرند: شکست اجرای ورک‌فلو روی پول‌ریکوئست یا شاخهٔ متصل، باز شدن ایشوی متصل (به جز ایشوهایی که از خود تسکیـ ساخته‌اید) و تکمیل وظیفه با ادغام. راه‌های دریافت این اعلان‌ها را در تنظیم اعلان‌ها و یادآورها انتخاب کنید.

قطع اتصال

اگر اپ در GitHub معلق یا حذف شود، کارت اتصال در «مرکز اپ‌ها» همین را نشان می‌دهد. برای قطع اتصال از سمت تسکیـ، روی کارت «قطع اتصال» را بزنید؛ این دکمه فقط برای مالک یا مدیر فضای کاری است. با قطع اتصال، اپ تسکیـ از حساب یا سازمان GitHub شما حذف می‌شود و رویدادی نمی‌رسد، ولی لینک‌هایی که تا آن لحظه روی وظیفه‌ها ثبت شده‌اند باقی می‌مانند. اتصال‌های فعال فضای کاری در تنظیمات فضای کاری، زبانهٔ «یکپارچه‌سازی‌ها»، هم فهرست می‌شوند.

اشتباه‌های رایج

• نوشتن «Fixes» فقط در پیام کامیت و انتظار تکمیل؛ عبارت بستن باید در عنوان یا توضیح پول‌ریکوئستِ ادغام‌شده باشد، مگر قاعدهٔ push به شاخهٔ اصلی را روشن کرده باشید.
• ادغام شاخه‌ای که فقط به نام وظیفه است؛ بدون کلمهٔ بستن، وظیفه فقط وصل می‌شود، مگر قاعدهٔ مربوط به نام شاخه روشن باشد.
• گذاشتن فاصله بین شناسه و کروشهٔ وضعیت؛ شکل درست TASK-12[Done] است.
• انتظار لینک از مخزنی که اپ به آن دسترسی ندارد؛ GitHub رویدادهای چنین مخزنی را نمی‌فرستد. مخزن را در تنظیمات اپ در GitHub اضافه کنید.

گام بعدی: اگر تیم شما از GitLab هم استفاده می‌کند، اتصال به GitLab را ببینید؛ همان شناسه‌ها و همان بخش «توسعه» آنجا هم کار می‌کنند. برای وصل کردن سیستم‌های دیگر، API عمومی و وب‌هوک‌ها را مرور کنید.