راه‌اندازی GitHub Actions Runner خودمیزبان روی سرور مجازی و اختصاصی

اگر پروژه‌ای با تعداد بیلد بالا روی گیت‌هاب دارید، احتمالاً به سقف دقیقه‌های رایگان Actions برخورده‌اید. Runnerهای پیش‌فرض گیت‌هاب برای هر دقیقهٔ اضافه هزینه می‌گیرند و پرداخت آن با کارت‌های ایرانی هم عملاً ممکن نیست. راه حل، راه‌اندازی یک Runner خودمیزبان (self-hosted) روی سرور خودتان است؛ همان چیزی که در این مقاله قدم‌به‌قدم پیاده‌سازی می‌کنیم.

Runner خودمیزبان چیست

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

چرا Runner خودمیزبان روی سرور آریانت

دو دلیل عملی این تصمیم را برای اکثر تیم‌های ایرانی توجیه می‌کند:

• هزینه: پلن رایگان گیت‌هاب برای مخازن خصوصی فقط ۲۰۰۰ دقیقه در ماه می‌دهد. با یک سرور مجازی که همیشه روشن است، این محدودیت از بین می‌رود و هزینه ثابت و از پیش مشخص است.
• پرداخت: خرید دقیقهٔ اضافه یا ارتقای پلن گیت‌هاب نیاز به کارت بین‌المللی دارد. با اجرای Runner روی زیرساخت داخلی، این وابستگی حذف می‌شود و پرداخت به‌صورت ریالی روی سرور VPS یا اختصاصی انجام می‌گیرد.

کنار این دو، دسترسی مستقیم به فایل‌سیستم Runner برای کش کردن dependencyها و سرعت بالاتر شبکه بین سرور CI و سرورهای دیگر پروژه هم مزیت جانبی محسوب می‌شود. اگر از گیت‌لب هم استفاده می‌کنید، همین منطق در راه‌اندازی GitLab Runner خودمیزبان هم صدق می‌کند.

مقایسه Runner ابری گیت‌هاب و Runner خودمیزبان

ویژگی	Runner ابری گیت‌هاب	Runner خودمیزبان روی آریانت
هزینه دقیقه اضافه	پرداخت دلاری، نیاز به کارت بین‌المللی	هزینه ثابت ماهانه سرور، پرداخت ریالی
کنترل روی محیط اجرا	نسخه از پیش تعیین‌شده OS و ابزارها	کنترل کامل روی نسخه OS، پکیج‌ها و کش
زمان راه‌اندازی هر job	چند ثانیه تا چند دقیقه (provisioning)	معمولاً سریع‌تر، چون سرور از قبل آماده است
نگهداری	صفر، توسط گیت‌هاب مدیریت می‌شود	به‌عهدهٔ شما (آپدیت، امنیت، مانیتورینگ)
مناسب برای	مخازن عمومی، پروژه‌های کوچک	پروژه‌های خصوصی با بیلد زیاد یا نیاز به سخت‌افزار خاص

پیش‌نیازها

• یک سرور مجازی یا اختصاصی با لینوکس (اوبونتو ۲۲.۰۴ یا جدیدتر در این آموزش استفاده شده)
• دسترسی SSH امن با کاربری غیر از root
• دسترسی Admin یا Owner روی مخزن یا سازمان گیت‌هاب مربوطه
• حداقل ۲ هسته پردازنده و ۲ گیگابایت رم برای بیلدهای معمولی؛ برای پروژه‌های سنگین‌تر (کامپایل، تست کانتینری) منابع بیشتری در نظر بگیرید

مرحله ۱: ساخت توکن ثبت‌نام Runner در گیت‌هاب

در مخزن یا سازمان موردنظر، به مسیر Settings > Actions > Runners بروید و روی New self-hosted runner بزنید. گیت‌هاب سیستم‌عامل را می‌پرسد و بعد یک اسکریپت نصب همراه با توکن رجیستریشن نشان می‌دهد. این توکن کوتاه‌مدت است، پس همین حالا سرور را باز نگه دارید و به مرحله بعد بروید.

نکته امنیتی: اگر مخزن عمومی است، Runner خودمیزبان را روی آن فعال نکنید. هر کسی که pull request بزند می‌تواند کد دلخواه روی سرور شما اجرا کند. این حالت فقط برای مخازن خصوصی یا داخل سازمان با دسترسی محدود مناسب است.

مرحله ۲: دانلود و پیکربندی Runner روی سرور

با یک کاربر مجزا (نه root) وارد سرور شوید و پوشه‌ای برای Runner بسازید؛ اگر می‌خواهید همین ساخت کاربر و تنظیمات اولیه را در لحظهٔ boot سرور خودکار کنید، خودکارسازی راه‌اندازی اولیه سرور با Cloud-Init را ببینید:

sudo adduser --disabled-password ghrunner
sudo su - ghrunner
mkdir actions-runner && cd actions-runner

بسته رسمی را از صفحهٔ Runners همان مخزن دانلود کنید (نسخه و لینک هر بار متفاوت است، دقیقاً همان چیزی که گیت‌هاب نشان می‌دهد را کپی کنید):

curl -o actions-runner-linux-x64.tar.gz -L https://github.com/actions/runner/releases/download/vX.Y.Z/actions-runner-linux-x64-X.Y.Z.tar.gz
tar xzf actions-runner-linux-x64.tar.gz

سپس با توکنی که در مرحله قبل گرفتید، پیکربندی را اجرا کنید:

./config.sh --url https://github.com/<org>/<repo> --token <REGISTRATION_TOKEN>

اسکریپت نام Runner، لیبل‌ها و گروه اجرا را می‌پرسد. لیبل‌های معنادار (مثلاً self-hosted, linux, production) بگذارید تا در workflow بتوانید دقیقاً همین Runner را هدف بگیرید:

jobs:
  build:
    runs-on: [self-hosted, linux, production]

مرحله ۳: اجرای دائمی Runner با systemd

اجرای ./run.sh به‌صورت دستی با بسته شدن ترمینال متوقف می‌شود. برای اجرای دائمی، از سرویس systemd که خود اسکریپت نصب می‌کند استفاده کنید (این بخش را با کاربری که دسترسی sudo دارد اجرا کنید، نه با ghrunner):

sudo ./svc.sh install ghrunner
sudo ./svc.sh start

وضعیت سرویس و لاگ‌ها را این‌طور بررسی می‌کنید:

sudo ./svc.sh status
journalctl -u actions.runner.<org>-<repo>.<runner-name>.service -f

از این لحظه، سرور بعد از هر ریبوت هم Runner را خودکار بالا می‌آورد و در صفحهٔ Settings > Actions > Runners وضعیت آن به‌صورت Idle یا Active نمایش داده می‌شود.

مرحله ۴: تنظیمات امنیتی

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

• کاربر اختصاصی و بدون sudo: سرویس Runner را با همان کاربر ghrunner اجرا کنید، نه root. اگر job‌ها نیاز به دسترسی خاصی دارند (مثلاً اجرای Docker)، آن کاربر را فقط به گروه‌های لازم اضافه کنید.
• فایروال: Runner ارتباط خروجی به سرورهای گیت‌هاب برقرار می‌کند و نیازی به پورت باز ورودی ندارد. در فایروال سرور، ورودی را فقط روی SSH و پورت‌های سرویس‌های دیگر باز نگه دارید.
• جداسازی محیط اجرا: اگر چند پروژه یا مشتری روی یک سرور Runner دارید، هر workflow را داخل کانتینر Docker اجرا کنید تا فایل‌سیستم و متغیرهای محیطی پروژه‌ها با هم قاطی نشوند.
• بروزرسانی خودکار: گیت‌هاب به‌طور پیش‌فرض نسخهٔ Runner را خودکار بروزرسانی می‌کند؛ این گزینه را غیرفعال نکنید مگر دلیل مشخصی برای پین کردن نسخه دارید.

نگهداری و رفع اشکال رایج

بعد از راه‌اندازی اولیه، چند مورد هست که در استفاده روزمره به آن برمی‌خورید:

• Runner در گیت‌هاب Offline نشان داده می‌شود: معمولاً یعنی سرویس systemd متوقف شده یا اتصال شبکه سرور قطع بوده. با sudo ./svc.sh status وضعیت سرویس را ببینید و در صورت نیاز sudo ./svc.sh start را دوباره اجرا کنید.
• توکن رجیستریشن منقضی شده: توکن‌های config.sh فقط برای چند دقیقه معتبرند. اگر پیکربندی با خطای احراز هویت متوقف شد، از صفحه Runners گیت‌هاب یک توکن تازه بگیرید و دوباره تلاش کنید.
• فضای دیسک پر می‌شود: هر بیلد فایل‌های موقت و کش می‌سازد. پوشه _work داخل مسیر نصب Runner را از نظر حجم دوره‌ای چک کنید و در صورت نیاز پاک‌سازی خودکار بگذارید.
• حذف کامل Runner: اگر سرور را تعویض می‌کنید یا Runner دیگر لازم نیست، ابتدا sudo ./svc.sh uninstall و بعد ./config.sh remove --token <REMOVAL_TOKEN> را اجرا کنید تا هم از سرور و هم از لیست گیت‌هاب پاک شود؛ در غیر این صورت یک Runner غیرفعال در تنظیمات باقی می‌ماند.

برای پروژه‌هایی که چند Runner دارند، بررسی دوره‌ای لاگ با journalctl و تنظیم هشدار ساده (مثلاً یک اسکریپت cron که وضعیت سرویس را چک می‌کند) از قطعی‌های طولانی جلوگیری می‌کند.

انتخاب سرور مناسب: مجازی یا اختصاصی

برای اکثر پروژه‌ها یک سرور مجازی (VPS) کافی است؛ منابع را هر زمان لازم شد ارتقا می‌دهید و هزینه ماهانه پایین می‌ماند. اگر بیلدها سنگین هستند (کامپایل حجیم، تست‌های موازی زیاد، پردازش داده) یا نیاز به منابع اختصاصی و پایدار دارید که با سایر مصرف‌کنندگان سرور به اشتراک گذاشته نشود، سرور اختصاصی گزینه بهتری است.

سرور مجازی آریانت دقیقاً برای این سناریو مناسب است: پیکربندی سریع، هزینه ریالی، و امکان افزایش منابع بدون توقف طولانی سرویس. کافی است یک نمونه با ۲ هسته و ۲ تا ۴ گیگابایت رم بگیرید و همین امروز مراحل بالا را روی آن اجرا کنید.

جمع‌بندی

Runner خودمیزبان روی سرور آریانت دو مشکل واقعی تیم‌های ایرانی را حل می‌کند: سقف دقیقهٔ رایگان گیت‌هاب و ناتوانی در پرداخت دلاری برای ارتقای پلن. با یک کاربر مجزا، سرویس systemd، و چند تنظیم امنیتی ساده، می‌توانید در کمتر از نیم ساعت یک Runner پایدار برای CI/CD پروژه‌تان راه بیندازید و کنترل کامل روی محیط اجرا را هم به‌دست بیاورید.