نود GitLab در N8N

نود GitLab در N8N

نود GitLab در n8n یکی از کاربردی‌ترین نودها برای اتصال خودکار فرآیندهای توسعه نرم‌افزار به ورکفلوهای اتوماسیون است. با این نود می‌توان کارهایی مثل ساخت Issue، خواندن اطلاعات ریپازیتوری، مدیریت فایل‌ها، دریافت اطلاعات پروژه و اتصال GitLab به ابزارهایی مثل Slack، Telegram، Jira، Notion، Google Sheets و پایگاه‌داده‌ها را بدون کدنویسی سنگین انجام داد.

معرفی نود در N8N

GitLab یک پلتفرم مدیریت کد، CI/CD، Issue Tracking و همکاری تیم‌های توسعه نرم‌افزار است. نود GitLab در n8n به شما اجازه می‌دهد از طریق API رسمی GitLab با پروژه‌ها، فایل‌ها، Issueها و ریپازیتوری‌ها کار کنید.

• نام نود: GitLab
• دسته‌بندی: Integration / Action
• نوع عملکرد: اجرای عملیات روی GitLab از داخل ورکفلو
• نود مکمل: GitLab Trigger برای شروع ورکفلو بر اساس رویدادهای GitLab مانند Push، Merge Request، Issue و Pipeline

کاربرد اصلی این نود، خودکارسازی کارهای مرتبط با توسعه نرم‌افزار است. به‌عنوان مثال می‌توانید بعد از ثبت یک فرم، به‌صورت خودکار در GitLab یک Issue بسازید؛ بعد از تغییر وضعیت یک تسک، پیام اطلاع‌رسانی در Slack ارسال کنید؛ یا اطلاعات ریپازیتوری‌ها را به‌صورت دوره‌ای در Google Sheets ذخیره کنید.

موارد استفاده

ساخت خودکار Issue از فرم یا تیکت پشتیبانی

فرض کنید کاربران در یک فرم مشکل فنی خود را ثبت می‌کنند. n8n می‌تواند اطلاعات فرم را دریافت کند و با نود GitLab یک Issue جدید در پروژه مربوطه بسازد.

• نود Webhook یا Typeform برای دریافت اطلاعات کاربر
• نود Set برای آماده‌سازی عنوان و توضیحات Issue
• نود GitLab برای ساخت Issue
• نود Slack یا Telegram برای اطلاع‌رسانی به تیم فنی

ارسال اعلان بعد از Push یا Merge Request

با استفاده از GitLab Trigger می‌توان زمانی که روی یک Branch پوش انجام شد یا Merge Request جدیدی ایجاد شد، ورکفلو را اجرا کرد و جزئیات را به ابزارهای ارتباطی ارسال کرد.

• GitLab Trigger برای دریافت رویداد Push یا Merge Request
• IF Node برای بررسی Branch، مثلاً فقط main یا develop
• Slack Node برای ارسال پیام به کانال تیم توسعه

ثبت گزارش روزانه از Issueهای باز

می‌توانید با Cron Node هر روز صبح Issueهای باز یک پروژه را دریافت کرده و در Google Sheets یا Notion ذخیره کنید.

• Cron Node برای اجرای زمان‌بندی‌شده
• GitLab Node برای دریافت Issueها
• Google Sheets Node برای ذخیره گزارش
• Email Node برای ارسال خلاصه روزانه

مدیریت فایل‌های پروژه از داخل ورکفلو

نود GitLab امکان ایجاد، ویرایش، دریافت و حذف فایل در ریپازیتوری را فراهم می‌کند. این قابلیت برای تولید خودکار فایل‌های پیکربندی، مستندات یا changelog کاربرد دارد.

مانیتورینگ CI/CD و Pipeline

با GitLab Trigger می‌توان رویدادهای Pipeline یا Job را دریافت کرد و در صورت شکست Build، پیام هشدار برای تیم ارسال کرد یا یک Incident در سیستم مانیتورینگ ثبت کرد.

پارامترها و تنظیمات

احراز هویت و اتصال به GitLab

برای استفاده از نود GitLab باید ابتدا Credential مربوط به GitLab را در n8n بسازید. معمولاً این اتصال با Personal Access Token انجام می‌شود.

برای ساخت Access Token در GitLab باید از بخش Preferences وارد Access Tokens شوید و سطح دسترسی مناسب را انتخاب کنید. برای اکثر عملیات این نود، دسترسی api لازم است. برای عملیات فقط خواندنی، در برخی سناریوها read_api یا read_repository کافی است.

پارامتر Resource

پارامتر Resource مشخص می‌کند که می‌خواهید روی کدام بخش از GitLab عملیات انجام دهید.

عملیات مربوط به File

Resource برابر File برای کار با فایل‌های موجود در ریپازیتوری استفاده می‌شود. این بخش برای ساخت خودکار فایل‌های مستندات، تغییر فایل‌های پیکربندی یا خواندن محتوای فایل‌ها کاربرد دارد.

عملیات مربوط به Issue

Resource برابر Issue برای ساخت و مدیریت Issueها استفاده می‌شود. این بخش یکی از پرکاربردترین قسمت‌های نود GitLab است.

عملیات مربوط به Repository

Resource برابر Repository برای خواندن اطلاعات پروژه، لیست پروژه‌ها، Issueهای پروژه، لایسنس و اطلاعات مرتبط با ریپازیتوری استفاده می‌شود.

عملیات مربوط به User

Resource برابر User برای دریافت اطلاعات کاربری استفاده می‌شود. این بخش معمولاً برای اعتبارسنجی اتصال، دریافت مشخصات کاربر یا ترکیب با گزارش‌های مدیریتی کاربرد دارد.

پارامترهای GitLab Trigger

اگر هدف شما شروع خودکار ورکفلو بر اساس رویدادهای GitLab باشد، باید از نود GitLab Trigger استفاده کنید. این نود یک Webhook در GitLab ایجاد می‌کند و هنگام رخ دادن رویداد، داده را وارد n8n می‌کند.

نکات مهم هنگام پیکربندی

• برای GitLab.com معمولاً نیازی به تغییر Server URL نیست، اما برای GitLab Self-hosted باید آدرس دقیق سرور وارد شود.
• توکن باید سطح دسترسی کافی داشته باشد. برای ساخت Issue یا تغییر فایل معمولاً scope برابر api لازم است.
• نام Owner و Repository باید دقیقاً مطابق مسیر پروژه در GitLab باشد.
• اگر پروژه داخل Subgroup است، مسیر کامل ممکن است لازم شود؛ مانند company/platform/backend-api.
• برای ویرایش فایل، Branch باید وجود داشته باشد و کاربر باید روی آن Branch اجازه Commit داشته باشد.
• در عملیات‌هایی که تعداد زیادی خروجی دارند، استفاده از Limit می‌تواند از کند شدن ورکفلو جلوگیری کند.
• برای فیلدهای تاریخ مانند Due Date از فرمت استاندارد YYYY-MM-DD استفاده شود.
• در توضیحات Issue می‌توان از Markdown استفاده کرد؛ این قابلیت برای قالب‌بندی گزارش‌ها بسیار مفید است.

ورودی‌ها و خروجی‌ها

ورودی نود GitLab

نود GitLab می‌تواند داده‌های ورودی را از نودهای قبلی دریافت کند و با Expression در پارامترهای خود استفاده کند. برای مثال عنوان Issue می‌تواند از خروجی یک فرم، ایمیل، Webhook یا رکورد دیتابیس ساخته شود.

نمونه ورودی برای ساخت Issue:

{  "title": "خطا در صفحه پرداخت",  "description": "کاربر بعد از کلیک روی دکمه پرداخت با خطای 500 مواجه می‌شود.",  "priority": "high",  "reporter": "customer@example.com"}

در فیلد Title نود GitLab می‌توان از Expression زیر استفاده کرد:

{{$json.title}}

در فیلد Description نیز می‌توان توضیحات کامل‌تری ساخت:

گزارش‌دهنده: {{$json.reporter}}شرح مشکل:{{$json.description}}اولویت: {{$json.priority}}

خروجی نود GitLab

خروجی نود GitLab معمولاً پاسخ API GitLab است. این خروجی بسته به نوع عملیات متفاوت است. مثلاً هنگام ساخت Issue، اطلاعات Issue ساخته‌شده شامل id، iid، title، description، state، web_url و اطلاعات نویسنده برگردانده می‌شود.

نمونه خروجی عملیات Create Issue:

{  "id": 982211,  "iid": 42,  "project_id": 884422,  "title": "خطا در صفحه پرداخت",  "description": "کاربر بعد از کلیک روی دکمه پرداخت با خطای 500 مواجه می‌شود.",  "state": "opened",  "labels": ["bug", "high-priority"],  "web_url": "https://gitlab.com/my-company/web-app/-/issues/42",  "author": {    "id": 12345,    "username": "automation-bot",    "name": "Automation Bot"  },  "created_at": "2026-05-28T10:30:00.000Z"}

خروجی GitLab Trigger

اگر از GitLab Trigger استفاده شود، خروجی شامل Payload رویداد GitLab است. برای مثال در رویداد Push اطلاعات Commitها، Branch، کاربر ارسال‌کننده و پروژه در خروجی وجود دارد.

نمونه خروجی ساده‌شده Push Event:

{  "object_kind": "push",  "event_name": "push",  "ref": "refs/heads/main",  "user_name": "Ali Ahmadi",  "project": {    "id": 884422,    "name": "web-app",    "web_url": "https://gitlab.com/my-company/web-app"  },  "commits": [    {      "id": "f3a1b2c4d5",      "message": "Fix payment error",      "timestamp": "2026-05-28T09:12:00+00:00",      "url": "https://gitlab.com/my-company/web-app/-/commit/f3a1b2c4d5",      "author": {        "name": "Ali Ahmadi",        "email": "ali@example.com"      }    }  ]}

نکات پیشرفته و ترفندها

استفاده از Expression برای ساخت Issueهای هوشمند

می‌توانید Title و Description را بر اساس داده‌های قبلی ورکفلو بسازید. برای مثال اگر ورودی از یک سیستم پشتیبانی می‌آید، عنوان Issue را ترکیبی از شناسه تیکت و موضوع قرار دهید.

[Ticket #{{$json.ticket_id}}] {{$json.subject}}

فیلتر کردن رویدادها با IF Node

GitLab Trigger ممکن است برای رویدادهای مختلف اجرا شود. با IF Node می‌توانید فقط رویدادهای مهم را پردازش کنید. مثلاً فقط وقتی Branch برابر main است پیام ارسال شود.

{{$json.ref === "refs/heads/main"}}

جلوگیری از ساخت Issue تکراری

قبل از ساخت Issue جدید، می‌توانید با GitLab Node یا HTTP Request Node Issueهای موجود را جستجو کنید. اگر Issue مشابه وجود داشت، به‌جای ساخت مورد جدید، همان Issue را به‌روزرسانی کنید یا Comment بگذارید.

ترکیب با OpenAI برای خلاصه‌سازی Commitها

در رویداد Push، لیست Commitها را به نود OpenAI بدهید و یک خلاصه قابل‌فهم برای مدیر پروژه تولید کنید. سپس خلاصه را در Slack، Telegram یا ایمیل ارسال کنید.

ساخت Changelog خودکار

با دریافت Merge Requestهای ادغام‌شده یا Commitهای یک بازه زمانی، می‌توان فایل CHANGELOG.md را تولید و با Resource برابر File در ریپازیتوری ذخیره کرد.

استفاده از Split In Batches برای پروژه‌های بزرگ

اگر تعداد Issueها یا پروژه‌ها زیاد است، بهتر است خروجی‌ها را با Split In Batches مرحله‌به‌مرحله پردازش کنید تا هم مصرف منابع n8n کاهش یابد و هم احتمال برخورد با محدودیت‌های API کمتر شود.

مدیریت خطا با Error Workflow

برای ورکفلوهای حساس مانند CI/CD Notification یا ساخت خودکار Issue، بهتر است Error Workflow تعریف شود تا در صورت خطا، پیام هشدار برای تیم ارسال شود.

محدودیت‌ها و خطاها

محدودیت‌های رایج

• نود GitLab فقط عملیاتی را انجام می‌دهد که API و نسخه فعلی n8n پشتیبانی می‌کنند.
• برای برخی قابلیت‌های پیشرفته GitLab، ممکن است لازم باشد از HTTP Request Node همراه با API رسمی GitLab استفاده شود.
• دسترسی کاربر یا توکن تعیین می‌کند چه عملیاتی قابل انجام است؛ اگر کاربر اجازه نوشتن روی ریپازیتوری نداشته باشد، ایجاد یا ویرایش فایل انجام نمی‌شود.
• در GitLab Self-hosted ممکن است تنظیمات SSL، Firewall یا Reverse Proxy مانع اتصال n8n شود.
• رویدادهای Trigger وابسته به Webhook هستند؛ اگر n8n از اینترنت یا سرور GitLab قابل دسترسی نباشد، Trigger اجرا نمی‌شود.
• API GitLab محدودیت نرخ درخواست دارد؛ در پردازش‌های حجیم باید از Batch، Delay و Limit استفاده شود.

خطای 401 Unauthorized

این خطا معمولاً به معنی نامعتبر بودن Access Token یا نداشتن Scope مناسب است.

• توکن را دوباره بررسی کنید.
• مطمئن شوید توکن منقضی نشده است.
• برای عملیات نوشتن، scope مناسب مانند api را فعال کنید.

خطای 403 Forbidden

این خطا زمانی رخ می‌دهد که توکن معتبر است اما کاربر اجازه انجام عملیات را ندارد.

• سطح دسترسی کاربر در پروژه را بررسی کنید.
• برای تغییر فایل، کاربر باید اجازه Push روی Branch هدف داشته باشد.
• در پروژه‌های محافظت‌شده، قوانین Protected Branch را بررسی کنید.

خطای 404 Not Found

این خطا معمولاً به دلیل اشتباه بودن مسیر پروژه، نام Owner، نام Repository یا Project ID رخ می‌دهد.

• نام گروه، Subgroup و Repository را دقیق وارد کنید.
• اگر پروژه داخل Subgroup است، مسیر کامل را بررسی کنید.
• مطمئن شوید کاربر توکن به پروژه دسترسی دارد؛ گاهی پروژه وجود دارد اما برای کاربر قابل مشاهده نیست.

خطای مربوط به Branch یا File Path

اگر Branch یا مسیر فایل اشتباه باشد، عملیات File شکست می‌خورد.

• نام Branch را دقیق وارد کنید؛ main و master دو Branch متفاوت هستند.
• مسیر فایل باید نسبت به ریشه ریپازیتوری باشد.
• برای ویرایش یا حذف فایل، فایل باید از قبل وجود داشته باشد.

خطای Webhook در GitLab Trigger

اگر GitLab Trigger اجرا نمی‌شود، معمولاً مشکل از دسترسی GitLab به آدرس Webhook n8n است.

• آدرس Webhook باید از سمت GitLab قابل دسترسی باشد.
• در n8n Self-hosted، مقدار WEBHOOK_URL باید درست تنظیم شده باشد.
• اگر از HTTPS استفاده می‌شود، گواهی SSL باید معتبر باشد.
• در GitLab Self-hosted، تنظیمات outbound request و firewall بررسی شود.

ایده ها

• ساخت ربات گزارش باگ که ایمیل‌های دارای کلمه Error را به Issue در GitLab تبدیل کند.
• ارسال خلاصه روزانه Merge Requestهای باز به Slack یا Telegram برای تیم توسعه.
• ساخت Changelog خودکار بعد از هر Release و ذخیره آن در فایل CHANGELOG.md ریپازیتوری.
• مانیتورینگ Pipelineها و ارسال هشدار فوری در صورت شکست Build یا Deploy.
• اتصال فرم درخواست قابلیت جدید به GitLab و ساخت Issue با Labelهای خودکار بر اساس نوع درخواست.

منابع و مستندات اصلی

• مستندات رسمی نود GitLab در n8n
• مستندات رسمی GitLab Trigger در n8n
• مستندات رسمی GitLab API
• راهنمای ساخت Personal Access Token در GitLab
• انجمن رسمی n8n
• مستندات Expression در n8n