نود Git در N8N

نود Git در N8N

نود Git در n8n به شما کمک می‌کند عملیات رایج Git را مستقیماً داخل ورکفلو انجام دهید؛ از کلون کردن ریپو و گرفتن آخرین تغییرات گرفته تا گرفتن لاگ، بررسی وضعیت فایل‌ها و اجرای دستورات اتوماسیون روی مخزن. این نود وقتی ارزشمند می‌شود که بخواهید تغییرات کد، کانفیگ یا فایل‌های یک ریپو را به‌صورت زمان‌بندی‌شده یا رویدادمحور پردازش کنید و خروجی را به مرحله‌های بعدی مثل ارسال گزارش، ساخت نسخه پشتیبان یا تریگر کردن CI/CD وصل کنید.

معرفی نود در N8N

نود Git یک نود از نوع Integration/Action است که عملیات Git را روی یک مسیر (Working Directory) اجرا می‌کند. این نود معمولاً روی همان ماشینی اجرا می‌شود که n8n روی آن در حال اجراست (Self-host) یا در کانتینر/محیطی که به فایل‌سیستم دسترسی دارد.

  • کارکرد اصلی: اجرای عملیات Git (مثل clone/pull/status/log و گاهی عملیات‌های مرتبط با branch) روی یک ریپوی مشخص
  • دسته‌بندی: Integration / Action
  • اهمیت در ورکفلوها: وقتی فایل‌ها و تاریخچه تغییرات منبع داده شماست (Infrastructure as Code، فایل‌های کانفیگ، محتوا، اسکریپت‌ها)، Git تبدیل به یک منبع ورودی قابل اتکا برای اتوماسیون می‌شود.

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

1) ساخت گزارش تغییرات روزانه (Daily Changelog)

  • هر روز ساعت ۹ صبح ریپو را Pull کنید، سپس آخرین commitها را بخوانید و خلاصه تغییرات را به Slack/Email ارسال کنید.
  • ترکیب پیشنهادی نودها: Cron Trigger → Git (Pull + Log) → Code/Function → Slack/Email

2) پایش تغییرات فایل‌های کانفیگ و هشدار

  • بعد از Pull، اگر فایل‌های حساس (مثل nginx.conf یا docker-compose.yml) تغییر کرده بودند، هشدار ارسال شود.
  • ترکیب پیشنهادی نودها: Cron Trigger → Git (Pull + Status یا Diff) → IF → Telegram/Slack

3) تهیه بکاپ نسخه‌ای از خروجی‌ها در یک ریپو

  • خروجی گزارش‌ها یا فایل‌های تولید شده را در یک مسیر قرار دهید، سپس Commit و Push انجام دهید (در صورت پشتیبانی تنظیمات Push/Commit در محیط شما).
  • ترکیب پیشنهادی نودها: HTTP Request/Webhook → Write Binary File → Git (Add/Commit/Push) → Notify

4) تریگر کردن استقرار (Deploy) با بررسی شاخه و تگ

  • قبل از اجرای مراحل Deploy، شاخه و آخرین tag را بررسی کنید و فقط اگر شرایط درست بود ادامه دهید.
  • ترکیب پیشنهادی نودها: Manual Trigger → Git (Fetch/Log/Tag) → IF → SSH/Execute Command

5) تولید محتوای سایت از مخزن محتوا

  • ریپوی محتوا (Markdown/JSON) را Pull کنید، فایل‌ها را بخوانید، تبدیل کنید و در مقصد منتشر کنید.
  • ترکیب پیشنهادی نودها: Cron → Git (Pull) → Read File(s) → Code → S3/FTP/HTTP

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

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

  • Operation (عملیات) | نوع داده: String (Select)

    کاربرد: تعیین می‌کند نود چه دستور/عملیاتی از Git را اجرا کند (مثل Clone, Pull, Status, Log و غیره).

    مثال عملی: Operation = Pull برای گرفتن آخرین تغییرات از remote.

  • Repository URL | نوع داده: String

    کاربرد: آدرس ریپو برای عملیات‌هایی مثل Clone. می‌تواند HTTPS یا SSH باشد.

    مثال عملی: https://github.com/org/project.git یا git@github.com:org/project.git

  • Working Directory / Local Path | نوع داده: String

    کاربرد: مسیر محلی ریپو روی فایل‌سیستم همان محیطی که n8n اجرا می‌شود. برای Pull/Status/Log باید مسیر ریپوی کلون‌شده باشد.

    مثال عملی: /data/repos/project

  • Branch | نوع داده: String

    کاربرد: تعیین شاخه هدف برای clone/checkout/pull (اگر در عملیات وجود داشته باشد).

    مثال عملی: main یا develop

  • Depth (Shallow Clone) | نوع داده: Number

    کاربرد: برای کلون کم‌عمق و سریع‌تر (فقط آخرین N کامیت). برای ریپوهای بزرگ بسیار مفید است.

    مثال عملی: Depth = 20

  • Authentication | نوع داده: Credential/Options

    کاربرد: نحوه احراز هویت به ریپو. معمولاً یکی از حالت‌های زیر است:

    • HTTPS + Token/Username-Password: برای GitHub/GitLab معمولاً Token توصیه می‌شود.
    • SSH Key: نیازمند کلید خصوصی داخل محیط اجرا و تنظیم known_hosts.

    مثال عملی: استفاده از Personal Access Token در URL/credential یا تنظیم SSH key در کانتینر n8n.

  • Log Options (برای Operation=Log) | نوع داده: Object/Fields

    کاربرد: محدود کردن تعداد کامیت‌ها، فیلتر زمانی، یا فرمت خروجی (بسته به قابلیت‌های نود/نسخه).

    مثال عملی: دریافت 10 کامیت آخر برای ساخت خلاصه تغییرات.

  • Remote | نوع داده: String

    کاربرد: نام remote (معمولاً origin). در pull/fetch/push کاربرد دارد.

    مثال عملی: origin

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

  • مسیر Working Directory باید پایدار باشد: اگر n8n داخل Docker اجرا می‌شود، مسیر را روی یک volume نگه دارید تا با ری‌استارت از بین نرود.
  • دسترسی فایل‌سیستم: کاربر/پروسس n8n باید مجوز خواندن/نوشتن در مسیر ریپو را داشته باشد.
  • SSH در محیط‌های کانتینری: برای clone/pull با SSH معمولاً باید کلید خصوصی و known_hosts درست تنظیم شود، وگرنه خطای host verification می‌گیرید.
  • تعارض (Conflict): اگر در ورکفلو فایل‌هایی را تغییر دهید و سپس Pull کنید، ممکن است به conflict بخورید. بهتر است قبل از Pull وضعیت را بررسی کنید یا مسیر را فقط خواندنی نگه دارید.
  • امنیت: توکن‌ها را در Credentials ذخیره کنید و از گذاشتن Token داخل متن URL در نودها/کدها خودداری کنید.

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

ورودی (Input)

بیشتر عملیات Git به ورودی آیتم‌ها وابسته نیست و از تنظیمات نود استفاده می‌کند. با این حال، شما می‌توانید مسیرها/برنچ/URL را با Expression از آیتم ورودی بخوانید (برای سناریوهای چندریپو یا چندشاخه).

نمونه ورودی برای کنترل داینامیک مسیر و شاخه:

{  "repoUrl": "https://github.com/org/project.git",  "localPath": "/data/repos/project",  "branch": "main"}

خروجی (Output)

خروجی معمولاً شامل نتیجه عملیات (موفق/ناموفق)، متن خروجی استاندارد دستور، و گاهی اطلاعات ساختاریافته مثل لیست کامیت‌ها یا فایل‌های تغییر کرده است (بسته به عملیات و نسخه n8n).

نمونه خروجی متداول (نمونه‌سازی‌شده):

{  "success": true,  "operation": "pull",  "repositoryPath": "/data/repos/project",  "stdout": "Already up to date.",  "stderr": "",  "changedFiles": [],  "summary": {    "insertions": 0,    "deletions": 0  }}

نمونه خروجی برای Log (نمونه‌سازی‌شده):

{  "success": true,  "operation": "log",  "repositoryPath": "/data/repos/project",  "commits": [    {      "hash": "a1b2c3d",      "author": "Ali",      "date": "2026-02-04T07:40:12Z",      "message": "Fix config parsing"    },    {      "hash": "d4e5f6g",      "author": "Sara",      "date": "2026-02-03T18:22:01Z",      "message": "Add deployment docs"    }  ]}

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

  • مدیریت چند ریپو با یک ورکفلو: با استفاده از Split In Batches و یک لیست از repoUrl/localPath می‌توانید همان عملیات را روی چند ریپو اجرا کنید.
  • ایزوله‌سازی مسیرها: برای جلوگیری از تداخل همزمان، برای هر ریپو یک مسیر جداگانه بگذارید و از اجرای همزمان روی یک مسیر واحد خودداری کنید.
  • قفل کردن اجرا (Lock): اگر ورکفلو ممکن است همزمان اجرا شود (مثلاً Webhook)، با استفاده از Data Store/Redis یا یک فایل lock در مسیر، اجرای موازی را کنترل کنید تا خراب شدن working tree رخ ندهد.
  • تبدیل خروجی خام به داده قابل گزارش: اگر نود فقط stdout برگرداند، با Code node می‌توانید stdout را پارس کنید (مثلاً خروجی git log با فرمت مشخص) و به جدول/JSON تبدیل کنید.
  • ترکیب با نودهای فایل: پس از Pull می‌توانید با Read File/Read Binary File فایل‌ها را بخوانید، تغییرات را استخراج کنید و آن‌ها را به APIها ارسال کنید.

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

محدودیت‌ها

  • وابستگی به محیط اجرا: عملیات Git روی همان سیستم اجرا می‌شود؛ اگر دسترسی به اینترنت، DNS، یا فایل‌سیستم محدود باشد، نود هم محدود می‌شود.
  • سناریوهای پیشرفته Git: بعضی عملیات‌های پیچیده (interactive rebase، resolve conflict تعاملی) برای اتوماسیون مناسب نیستند یا در نود پوشش داده نمی‌شوند.
  • همزمانی (Concurrency): اجرای همزمان روی یک working directory ممکن است باعث خطا یا خراب شدن وضعیت ریپو شود.

خطاهای رایج و راه‌حل‌ها

  • Repository not found / Authentication failed
    • URL را بررسی کنید (HTTPS/SSH درست).
    • اگر private است، Token/SSH key را درست تنظیم کنید.
    • در GitHub/GitLab سطح دسترسی توکن را چک کنید.
  • Host key verification failed (در SSH)
    • known_hosts را در محیط n8n تنظیم کنید.
    • اگر در Docker هستید، فایل‌های SSH را به کانتینر mount کنید.
  • fatal: not a git repository
    • Working Directory اشتباه است یا Clone انجام نشده.
    • ابتدا Operation=Clone و سپس Pull/Log را اجرا کنید.
  • Permission denied (فایل‌سیستم)
    • مجوزهای مسیر را اصلاح کنید (مالکیت/دسترسی).
    • در Docker، user و volume permissions را چک کنید.
  • Merge conflict / Your local changes would be overwritten by merge
    • قبل از Pull با Operation=Status وضعیت را بررسی کنید.
    • اگر قرار نیست تغییر محلی داشته باشید، مسیر را فقط برای خواندن استفاده کنید و تغییرات را در مسیر دیگری تولید کنید.
    • در صورت نیاز، پاک‌سازی workspace با حذف و Clone مجدد (رویکرد سخت‌گیرانه اما پایدار) برای ورکفلوهای CIگونه.

ایده ها

  • ساخت یک بات گزارش‌گر: هر بار که در شاخه main کامیت جدید آمد، خلاصه پیام کامیت‌ها و لیست فایل‌های تغییر کرده به Slack ارسال شود.
  • مانیتورینگ IaC: Pull از ریپوی Terraform/Ansible، شناسایی تغییرات در مسیرهای خاص و ثبت Ticket در Jira.
  • انتشار خودکار مستندات: Pull از ریپوی docs، تبدیل Markdown به HTML/PDF و آپلود در S3 یا ارسال به ایمیل تیم.
  • کنترل سلامت نسخه‌ها: استخراج آخرین tag و مقایسه با مقدار ثبت‌شده در یک دیتابیس، سپس تولید گزارش نسخه‌ها.
  • بکاپ کانفیگ‌ها: خروجی روزانه یک سیستم (فایل‌های JSON/YAML) را تولید و به ریپو commit کنید تا تاریخچه تغییرات نگهداری شود.

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

دسته بندی: N8N برچسب ها:

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

یک × دو =