چرا runner خودم را اجرا کنم بهجای runner میزبان GitHub؟

سه دلیل واقعی: وابستگیها و زنجیرهٔ ابزار خودتان از پیش پختهشده (بدون نصب دوبارهٔ هر اجرا)، دسترسی به منابع خصوصی مثل یک registry داخلی یا پایگاهداده، و کنترل روی ماشین — اندازهاش، cacheهایش، شبکهاش. اگر دقیقههای میزبان GitHub و یک محیط تمیز شما را راضی میکند، رویشان بمانید. زمانی خودمیزبانی کنید که مشخصاً به یکی از آن سه نیاز دارید.

آیا استفاده از یک runner خودمیزبان امن است؟

روی یک مخزن خصوصی، بله. روی یک مخزن عمومی، نه — هرگز. یک workflow کد دلخواهِ هرکسی را که آن را trigger میکند اجرا میکند، و روی یک مخزن عمومی pull request یک غریبه میتواند کدش را روی runner شما اجرا کند. مستندات خود GitHub همین را میگویند. runnerهای خودمیزبان را به مخازن خصوصی محدود کنید، یا بپذیرید که دارید ماشینتان را تحویل اینترنت میدهید.

یک runner چقدر CPU و RAM نیاز دارد؟

کاملاً به build شما بستگی دارد. یک کار معمولِ compile-and-test با ۲ هسته و ۴ تا ۸ گیگابایت راحت است — Small یا Medium در اینجا. buildهای سنگین (کامپایلهای native بزرگ، ایمیجهای بزرگ Docker، مجموعههای تست حافظهبَر) بیشتر میخواهند، و باید اندازه را بر اساس کار واقعی خود انتخاب کنید، نه یک حدس. یک اجرای واقعی را تماشا کنید و خواهید دانست.

آیا یک runner میتواند چند مخزن را مدیریت کند؟

یک runner میتواند به یک سازمان ثبت شود و توسط چند مخزن برداشته شود، بهطور پیشفرض هر بار یک کار. برای موازیسازی بیشتر، runnerهای بیشتری اجرا کنید — هرکدام سرویس systemd خودش است. فقط همهشان را روی مخازن خصوصی نگه دارید.

آیا باید به شما یک مدرک شناسایی بدهم؟

نه. ایمیل برای ثبتنام، USDC یا USDT برای پرداخت. بدون سند، root در حدود یک دقیقه.

اجرای یک Runner خودمیزبان GitHub Actions روی یک VPS

runnerهای میزبان GitHub یک پیش‌فرض خوب‌اند. همان لحظه‌ای دیگر به آن‌ها نیاز ندارید که یک build چیزی را می‌خواهد که آن‌ها ندارند — registry پکیج خصوصی شما، یک نسخهٔ خاص از زنجیرهٔ ابزار که از نصب دوبارهٔ هر اجرا خسته شده‌اید، یک پایگاه‌داده روی شبکهٔ خودتان، یا فقط کنترل بیشتر روی ماشین. آنجاست که یک runner خودمیزبان روی یک VPS نانش را درمی‌آورد.

این راهنما یکی را درست راه می‌اندازد: نصب‌شده، ثبت‌شده، زنده زیر systemd، و — بخشی که مردم اشتباه می‌گیرند — امن. بیایید با همان بخش آخر شروع کنیم، چون همان بخشی است که گاز می‌گیرد.

آن یک قانون امنیتی

یک workflow مربوط به GitHub Actions کد دلخواه را اجرا می‌کند — هرچه در فایل workflow هست، و هرچه آن کد می‌کشد. روی مخزن خودتان آن کد شماست، و اشکالی ندارد. روی یک مخزن عمومی، یک pull request از یک غریبه می‌تواند کد او را روی runner شما اجرا کند. این یک باگ نیست؛ همان‌طوری است که CI کار می‌کند. مستندات خود GitHub رک می‌گویند: از runnerهای خودمیزبان با مخازن عمومی استفاده نکنید.

پس قانون ساده و غیرقابل‌مذاکره است: runnerهای خودمیزبان برای مخازن خصوصی‌اند. اگر مخزنتان عمومی است، از runnerهای میزبان GitHub استفاده کنید و رد شوید. هرچه در ادامه می‌آید یک مخزن خصوصی را فرض می‌کند.

یک runner از ماشین چه می‌خواهد

به build بستگی دارد، و باید اندازه را بر اساس مال خودتان انتخاب کنید نه یک عدد از روی یک صفحه:

یک کار معمولِ compile-and-test — ۲ هسته و ۴ تا ۸ گیگابایت راحت است. Small (۸ دلار، 4 vCPU / 4 GB) یا Medium (۱۲ دلار، 6 vCPU / 6 GB) اغلب این‌ها را می‌پوشاند.
build‌های سنگین‌تر — کامپایل‌های native بزرگ، build‌های ایمیج بزرگ Docker، مجموعه‌های تست حافظه‌بَر — فضای بیشتری می‌خواهند. یک اجرای واقعی را تماشا کنید (htop حین build) و اندازه را بر اساس آنچه واقعاً می‌بینید انتخاب کنید، نه بر اساس امید.

دیسک هم مهم است: cache‌های build، لایه‌های Docker، و مخازن clone‌شده جمع می‌شوند. حواستان به آن باشد و هرس کنید.

۱. ماشین را آماده کنید

یک کاربر غیر-root برای runner بسازید — نصب‌کنندهٔ GitHub به‌هرحال از اجرا به‌عنوان root سر باز می‌زند، و شما هم همان را می‌خواهید:

sudo adduser --disabled-password --gecos "" runner
sudo usermod -aG sudo runner   # only if your builds genuinely need sudo

هرچه build‌هایتان نیاز دارند نصب کنید — یک زنجیرهٔ ابزار زبان، Docker، ابزارهای build. برای مثال، اگر کارهایتان container می‌سازند:

sudo apt update && sudo apt install -y docker.io
sudo usermod -aG docker runner

۲. runner را دانلود و ثبت کنید

در مخزن (یا سازمان) خود روی GitHub، به Settings → Actions → Runners → New self-hosted runner بروید. GitHub دقیقاً دستورهای دانلود و یک registration token به شما می‌دهد (کوتاه‌عمر است — تازه‌اش را بگیرید). به‌عنوان کاربر runner:

sudo -iu runner
mkdir actions-runner && cd actions-runner
# use the exact URL GitHub shows you for your OS/arch:
curl -o actions-runner-linux-x64.tar.gz -L "URL_FROM_GITHUB"
tar xzf actions-runner-linux-x64.tar.gz
./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN

config.sh یک نام runner، برچسب‌ها (labels)، و یک پوشهٔ work می‌خواهد — پیش‌فرض‌ها برای شروع خوب‌اند. برچسب‌ها همان چیزی‌اند که workflow شما با آن‌ها این runner را هدف می‌گیرد (runs-on: self-hosted).

۳. آن را به‌عنوان یک سرویس systemd اجرا کنید

runner با یک helper می‌آید که یک سرویس systemd را برایتان نصب می‌کند — از آن استفاده کنید، تا runner از ری‌بوت‌ها جان سالم به‌در ببرد و در صورت خرابی دوباره راه بیفتد. هنوز از دلِ نصب کاربر runner، اما دستورهای سرویس به root نیاز دارند:

sudo ./svc.sh install runner
sudo ./svc.sh start
sudo ./svc.sh status

این actions.runner.* را به‌عنوان یک unit مربوط به systemd ثبت می‌کند که به‌عنوان کاربر runner اجرا می‌شود و روی بوت شروع می‌شود. لاگ‌ها به journald می‌روند:

sudo journalctl -u 'actions.runner.*' -f

برگردید به صفحهٔ Runners در GitHub، runner شما حالا Idle نشان می‌دهد — نقطهٔ سبز. یک workflow را رویش نشانه بگیرید:

jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - run: make test

Push کنید، و کار روی ماشین شما اجرا می‌شود.

۴. تمیزش نگه دارید

یک runner خودمیزبان فایل‌سیستمش را بین کارها دوباره استفاده می‌کند — این هم بُردِ سرعت است (cache‌های گرم) و هم تفنگِ زیرِ پا (وضعیت باقی‌مانده). دو عادت سالم نگهش می‌دارند:

مرتب هرس کنید. به‌ویژه Docker — ‏docker system prune روی یک cron، وگرنه دیسک بی‌سروصدا از لایه‌های مرده پر می‌شود.
اسرار را روی ماشین ذخیره نکنید. از secretهای GitHub Actions استفاده کنید که به‌ازای هر اجرا تزریق می‌شوند، نه فایل‌هایی که در خانهٔ runner می‌نشینند. اگر runner به‌خطر بیفتد، هرچه روی دیسک هست با آن می‌رود.

اگر به یک محیط واقعاً تمیز به‌ازای هر کار نیاز دارید، هر کار را داخل یک گام container اجرا کنید — runner می‌ماند، آشفتگی کار نمی‌ماند.

چه زمانی خودمیزبانی کنیم، صادقانه

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

اگر یک runner برای مخزن خصوصی همان چیزی است که نیاز دارید: یک پلن انتخاب کنید — Small (۸ دلار) برای build‌های سبک‌تر، Medium (۱۲ دلار) وقتی سنگین‌تر می‌شوند — با USDC یا USDT پرداخت کنید (بدون KYC، بدون سند)، و در حدود ۶۰ ثانیه root خواهید داشت. سپس این صفحه را پایین بروید و چند دقیقه بعد یک runner خواهید داشت که کارها را برمی‌دارد.