اتصال به GitLab

اتصال GitLab پروژه‌های کد و وظیفه‌ها را کنار هم نگه می‌دارد. مدیر فضای کاری نشانی GitLab و یک توکن دسترسی را وارد می‌کند و پروژه‌هایی را که باید دنبال شوند علامت می‌زند؛ از آن به بعد هر مرج‌ریکوئست، ایشو، شاخه یا کامیتی که شناسهٔ وظیفه‌ای مثل TASK-12 را بیاورد، در بخش «توسعه»ی همان وظیفه فهرست می‌شود. هم gitlab.com و هم نمونهٔ خودمیزبان پشتیبانی می‌شود.

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

پیش از شروع

• در تسکیـ باید مالک یا مدیر فضای کاری باشید.
• در GitLab یک «توکن دسترسی شخصی» (Personal Access Token) با دسترسی api بسازید. تسکیـ با همین دسترسی روی پروژه‌ها وب‌هوک می‌سازد، کامنت می‌گذارد و شاخه یا ایشو می‌سازد.
• تسکیـ فقط پروژه‌هایی را نشان می‌دهد که حساب صاحب توکن در آن‌ها دست‌کم نقش Maintainer دارد.
• نشانی سرور خودمیزبان باید با HTTPS و از اینترنت در دسترس باشد؛ نشانی‌های داخلی یا خصوصی پذیرفته نمی‌شوند. GitLab شما هم باید بتواند درخواست وب‌هوک را به تسکیـ بفرستد.
• اتصال GitLab یکی از یکپارچه‌سازی‌های فضای کاری حساب می‌شود و سقف تعداد آن‌ها به پلن بستگی دارد.

ساخت اتصال

1. در GitLab توکن دسترسی شخصی با دسترسی api بسازید و آن را کپی کنید.
2. در تسکیـ از تنظیمات، «مرکز اپ‌ها» را باز کنید، روی کارت GitLab بزنید و زبانهٔ «فضای کاری» را انتخاب کنید.
3. در «آدرس پایه» نشانی سرور GitLab را بنویسید. برای gitlab.com می‌توانید آن را خالی بگذارید.
4. توکن را در «توکن دسترسی» بچسبانید و در صورت تمایل یک «برچسب» برای این اتصال بنویسید.
5. «اتصال GitLab» را بزنید. تسکیـ پیش از ذخیره، توکن و دسترسی api آن را بررسی می‌کند و بعد فهرست پروژه‌ها را در پس‌زمینه دریافت می‌کند.

اگر اتصال ساخته نشد: پیام خطا علت را می‌گوید: توکن منقضی یا لغوشده است («GitLab این توکن را نپذیرفت»)، دسترسی api ندارد، یا تسکیـ نتوانسته به نشانی GitLab برسد. وقتی توکن منقضی شد، کافی است با همان حساب GitLab و همان نشانی دوباره وصل شوید؛ تسکیـ توکن اتصال موجود را جایگزین می‌کند و اتصال دوم نمی‌سازد.

انتخاب پروژه‌ها و وب‌هوک‌ها

برخلاف GitHub، یک توکن GitLab به همهٔ پروژه‌های صاحبش دسترسی دارد؛ برای همین پروژه‌های تازه‌یافته‌شده ابتدا دنبال نمی‌شوند و خودتان انتخاب می‌کنید کدام‌ها به تسکیـ وصل شوند. روی کارت اتصال «مدیریت» را بزنید و در بخش «مخزن‌ها»:

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

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

لینک خودکار و بخش «توسعه»

شناسهٔ وظیفه را در نام شاخه، پیام کامیت، عنوان و توضیح مرج‌ریکوئست یا عنوان و توضیح ایشو بنویسید؛ شکل‌های TASK-12، #TASK-12 و CU-TASK-12 پذیرفته می‌شوند، حروف کوچک و رقم‌های فارسی هم خوانده می‌شوند. برای نمونه شاخهٔ feature/TASK-12-login خودکار به وظیفهٔ TASK-12 وصل می‌شود. لینک فقط از پروژه‌های دنبال‌شده و فقط به وظیفه‌های همان فضای کاری ساخته می‌شود.

• دسته‌ها: بخش «توسعه» موارد را در «درخواست‌های ادغام (PR / MR)»، «شاخه‌ها»، «کامیت‌ها»، «ایشوها» و «سایر لینک‌ها» نشان می‌دهد و کنار مرج‌ریکوئست یا شاخهٔ متصل، نتیجهٔ آخرین پایپ‌لاین را می‌آورد. حذف شاخه در GitLab هم روی لینک همان شاخه ثبت می‌شود.
• کار روی این وظیفه: «نام شاخه»، دستور «ساخت شاخه»، «پیام کامیت» و عبارت «بستن با ادغام» آمادهٔ کپی‌اند.
• افزودن لینک: نشانی یک مرج‌ریکوئست، ایشو یا کامیت GitLab (نشانی‌هایی که /-/merge_requests/، /-/issues/ یا /-/commit/ دارند) را بچسبانید تا دستی وصل شود.
• ساخت شاخه و ساخت ایشو: روی یکی از پروژه‌های دنبال‌شده شاخه یا ایشو بسازید؛ بلافاصله به وظیفه وصل می‌شود. اگر هنوز پروژه‌ای انتخاب نکرده باشید، پنجرهٔ ساخت از شما می‌خواهد پروژه‌ها را در «مدیریت» اتصال انتخاب کنید.

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

ذکر سادهٔ شناسه فقط وظیفه را وصل می‌کند. وظیفه وقتی تکمیل می‌شود که یک مرج‌ریکوئست ادغام شود و در عنوان یا توضیح آن، شناسه بعد از یکی از کلمه‌های بستن انگلیسی آمده باشد: close/closes/closed، fix/fixes/fixed یا resolve/resolves/resolved. چند شناسه را می‌توان با ویرگول یا and پشت سر هم آورد، مثل Closes TASK-12, TASK-15 and TASK-18.

• قواعد اختیاری: «تکمیل وظیفه‌هایی که در پوش به شاخهٔ اصلی بعد از کلمهٔ بستن آمده‌اند» و «تکمیل وظیفه وقتی شاخهٔ ادغام‌شده به نام آن است، حتی بدون کلمهٔ بستن» در بخش «قواعد» هستند و هر دو به‌طور پیش‌فرض خاموش‌اند.
• تغییر وضعیت با کروشه: TASK-12[In Review] یا TASK-12[در حال بررسی] وظیفه را به همان وضعیت پروژه می‌برد؛ بین شناسه و کروشه فاصله نگذارید.
• شرط‌ها: کلید «جابه‌جایی و تکمیل وظیفه‌ها» باید روشن باشد، و اگر وابستگی‌های وظیفه یا گردش‌کار وضعیت‌ها جابه‌جایی را اجازه ندهند، وظیفه سر جایش می‌ماند.

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

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

فعالیت، اعلان‌ها و قطع اتصال

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

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

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

• توکن بدون دسترسی api یا توکن منقضی؛ با توکن تازه دوباره وصل شوید تا همان اتصال به‌روز شود.
• پیدا نکردن پروژه در فهرست؛ صاحب توکن باید در آن پروژه دست‌کم نقش Maintainer داشته باشد. بعد «همگام‌سازی دوباره» را بزنید.
• انتظار لینک از پروژه‌ای که علامت نخورده است؛ پروژه‌های تازه تا انتخاب نشوند دنبال نمی‌شوند.
• نوشتن عبارت بستن فقط در پیام کامیت؛ عبارت باید در عنوان یا توضیح مرج‌ریکوئستِ ادغام‌شده باشد، مگر قاعدهٔ push به شاخهٔ اصلی روشن باشد.

گام بعدی: اگر از GitHub هم استفاده می‌کنید، اتصال به GitHub را ببینید؛ و برای دسترسی برنامه‌نویسی به تسکیـ، دسترسی برنامه‌نویسی و توکن‌ها را مرور کنید.