نحوه راه اندازی و تنظیم Gitlab Runner

در این مقاله با مفاهیم اصلی GitLab Runner و نحوه استفاده از آن برای اجرای Pipelineهای CI/CD آشنا می‌شویم. ابتدا ساختار Runner، Executorهای مختلف مانند Docker و Shell، نحوه نصب و ثبت Runner و نقش `tags` در انتخاب Runner مناسب بررسی می‌شود. سپس با اجرای یک Job ساده، نحوه ایجاد محیط اجرای Job، استفاده از متغیرهای CI/CD و بررسی لاگ‌ها و خطاهای اجرای Pipeline به‌صورت عملی مرور می‌شود.

در ادامه، تنظیمات مهم `config.toml`، نحوه استفاده از Helper Image و اهمیت نسخه و دسترسی به Imageها بررسی شده و در نهایت با چند نمونه عملی، روش عیب‌یابی Jobها و مدیریت Runner توضیح داده می‌شود. هدف مقاله ارائه یک دید عملی و پایه برای راه‌اندازی، استفاده و مدیریت GitLab Runner در پروژه‌های CI/CD است.
 

رانر (Runner) و اجراکننده (Executor). رانر ماشینی (یا سرویسی) است که جاب‌های شما را واقعاً اجرا می‌کند. اجراکننده(executer) مشخص می‌کند چگونه: 

اجراکننده docker یک کانتینر تازه از image:ای که مشخص کرده‌اید بالا می‌آورد و اجراکننده shell دستورها را مستقیم روی هاست رانر اجرا می‌کند. با tags: جاب‌ها را به رانر درست هدایت می‌کنید; یک جاب فقط روی رانری اجرا می‌شود که تگ مطابق را داشته باشد.

برای نصب گیتلب رانر ساده ترین راه استفاده از ایمیج داکری اون هست که با دستور زیر میتونیم اون رو روی کامپیوتر خودمون یا سروری که برای گیتلب رانر اختصاص داده ایم دانلود کنیم

docker pull gitlab/gitlab-runner

و در ادامه برای اجرا کردن رانر هم از این فایل داکر کامپوز استفاده میکنیم

services:
  gitlab-runner:
    image: gitlab/gitlab-runner:v18.11.4
    container_name: gitlab-runner
    restart: always
    volumes:
      - ./config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock

در بخش volumes مورد Docker socket را نباید صرفاً یک volume معمولی در نظر گرفت. دسترسی به Docker daemon می‌تواند سطح دسترسی بسیار بالایی روی host ایجاد کند؛ بنابراین Runnerهایی که به Docker socket دسترسی دارند باید به‌عنوان یک جزء حساس زیرساخت در نظر گرفته شوند.

برای ران کردن داکر کامپوز :

docker compose up -d

برای تغییر دادن فایل کانفیگ رانر که معمولا نیاز نداریم که دستی تغییرش بدیم و بطور خودکار توسط ابزار تحت ترمینال گیتلب رانر ادیت میشه ولی در بعضی مواقع خاص هم نیاز به تغییرش داریم میتونیم از volume درست شده و در مسیر اون volume فایل config.toml رو ادیت کنیم

در نهایت باید دستور gitlab-runner register رو یا بصورت خالی و بعد پر کردن مقادیر توسط interactive shell ساخته شده توسط این برنامه, ماشین خودمون رو به هاست گیتلب معرفی و ثبت نام کنیم یا اینکه از دستور کلی که توی گیت لب بخش رانر ها بهمون میده استفاده کنیم تا one shot فرایند ثبت نام انجام بشه

برای درست کردن رانر از بخش settings -> cicd -> runners یک رانر جدید ایجاد میکنیم و در صفحه بعدی که باز میشه باید tag هایی که میخوایم این رانر براشون اجرا بشه رو مشخص کنیم به عنوان مثال من دو عدد رانر یکی با تگ docker و یکی با تگ shell درست کردم

بعد از اینکه گیت لب رانر ماشین مارو شناخت و ثبت شد هم با دستور

gitlab-runner run

اون رو اماده دریافت جاب ها و اجرای اسکریپت ها میکنیم

در صورتی که GitLab Runner را مستقیماً روی سیستم‌عامل نصب کرده باشید، باید سرویس Runner در حال اجرا باشد. اما در روش Docker Compose که در این مقاله استفاده کردیم، process مربوط به Runner داخل container اجرا می‌شود و docker compose up -d آن را اجرا و در پس‌زمینه فعال نگه می‌دارد.

هر جاب از صفر شروع می‌شود. این مهم‌ترین مدل ذهنی در CI/CD است. وقتی یک جاب شروع می‌شود، رانر یک محیط تمیز می‌سازد: ابتدا یک ایمیج کمکی (Helper Image) کوچک، ریپوی شما را دانلود می‌کند، بعد image: جاب بالا می‌آید و before_script و script شما داخل آن اجرا می‌شوند. هیچ‌چیز بین جاب‌ها باقی نمی‌ماند مگر اینکه صریحاً منتقلش کنید. به همین دلیل است که جاب تست ما هر بار make را نصب می‌کند، محیط در هر اجرا کاملاً نو است.

متغیرهای CI/CD. رمزها و تنظیمات در بخش Settings → CI/CD → Variables پروژه شما در GitLab زندگی می‌کنند و به‌صورت متغیر محیطی به جاب‌ها تزریق می‌شوند. پایپ‌لاین ما از یکی از آن‌ها استفاده می‌کند: به عنوان مثال در مقاله نحوه استفاده از ssh key در گیتلب، SSH_KEY که به‌صورت متغیر از نوع File ذخیره شده; GitLab آن را در یک فایل موقت می‌نویسد و مسیر فایل را به جاب می‌دهد ($SSH_KEY یک مسیر است، نه محتوای کلید) که دقیقاً همان چیزی است که ssh -i می‌خواهد.

برخی تنظیمات کانفیگ رانر در config.toml

• برای هر جاب از نوع docker دو ایمیج دانلود می‌شود: image: خود جاب و یک ایمیج کمکی (Helper Image) کوچک (برای کلون کردن ریپو و آماده‌سازی محیط). اگر رانر شما به رجیستری‌های رسمی دسترسی نداشته باشد، معمولاً اولین چیزی که شکست می‌خورد دانلود ایمیج کمکی است

• نسخه رانر و ایمیج کمکی باید یکی باشد. اگر رانر را روی یک نسخه پین کرده‌اید، مطمئن شوید رجیستری شما واقعاً تگ Helper متناظر را دارد. با API رجیستری می‌توانید ببینید چه تگ‌هایی موجود است:

  curl -s d-hosted.dornadevops.com/gitlab-runner-helper/tags/list | jq
  

• اگر رجیستری رسمی روی شبکه شما محدود است، ایمیج‌ها را به یک رجیستری داخلی Mirror کنید و رانر را در config.toml برای ان ادرس mirror تنظیم کنید:

  [[runners]]
    [runners.docker]
      helper_image = "d-hosted.dornadevops.com/gitlab-runner-helper:x86_64-v18.11.4"
      pull_policy = "if-not-present"
  

  • شرط pull_policy = "if-not-present" به‌جای دانلود در هر جاب، از کش استفاده می‌کند پایپ‌لاین‌ها سریع‌تر می‌شوند.
  • ادرس ایمیج helper مشخص شده در بلاک بالا یک mirror هاست شده توسط درنادواپس هست که میتونید برای پروژه های خودتون ازش استفاده کنید و دسترسی عمومی به این ایمیج بدون مشکلات تحریم و سرعت دانلود کم در دسترس است

اجرای یک جاب ساده

برای اینکه نحوه کار کردن و دیدن لاگ های ماشین رانر رو باهم مرور کنیم یک جاب ساده ایجاد میکنیم و مرحله به مرحله مشکلات و ارور هایی که بهشون برمیخوریم رو حل میکنیم.

در ابتدا بعد از رجیستر شدن رانرمون توی گیت لب با دسترسی به پروژه، فایل .gitlab-ci.yml رو ادیت میکنیم تا اولین جابمون رو بسازیم

test_job:
  stage: test
  image: python:3.9-slim-bookworm
  before_script:
    - apt update
    - apt install cowsay -y
  script:
	- cowsay "hi"

بعد از درست کردن این فایل و پوش کردن تغییرات به ریپو گیتلب میبینیم که در صفحه ریپو اطلاعات جدیدی راجب پایپ لاین اجرا شده اضافه شده

که علامت سمت راست این نوار بسته به اینکه وضعیت پایپ لاین نهایی اجرا شده چی هست تغییر میکنه
سبز به معنی موفق بودن پایپ لاین قرمز به معنی شکست خوردن پایپ لاین و آبی به معنی در حال اجرا بودن اون پایپ لاین هست
حالت های دیگری مثل رنگ زرد هم ممکنه رخ بده که به دلیل مشکلات رانر ممکنه که این حالت رو هم ببینید
از منوی سمت چپ یا کلیک روی نوار ایجاد شده در صفحه اصلی ریپو خودتون میتونید جزئیات بیشتر پایپ لاین و یا لیستی از پایپ لاین های اجرا شده بصورت کلی رو مشاهده کنید
از بخش Build دو گزینه Pipelines برای پایپ لاین های ران شده تا به اکنون و Jobs برای لیست مفصل تری از جاب های هر پایپ لاین رو میتونید کلیک کنید و لیست مربوط بهش رو پیدا کنید

در این مثال چون هر پایپ لاین فقط یک جاب داره هر دو لیست این ریپو تقریبا به یک صورت نمایش داده میشن, اگر راجب پایپ لاین ها و نحوه نوشتن اونها اطلاعی ندارید میتونید از مقاله پایپ لاین نویسی شروع کنید به مطالعه راجبش

در کنار هر جاب هم علامت restart هست که میتونید بدون ایجاد کردن کامیت جدید روی ریپو اون پایپ لاین رو دوباره اجرا کنید

با کلیک بر روی هر کدوم از این جاب ها میتونید لاگ اون پایپ لاین رو ببینید در اونجا خط به خط اتفاقات و خروجی هایی که رانر شما در محیط بوجود اومده بدست اورده رو میتونید مشاهده کنید که خب طبعا برای دیباگ کردن و چک کردن وضعیت رانر از این اطلاعات میتونید استفاده خیلی زیادی بکنید

نمونه یک پایپ لاین شکست خورده و مشاهده ارور بوجود اومده که باعث شکسته شدن پایپ لاینمون شده

همینطور که میبینید به دلیل اینکه فایل اجرایی برنامه cowsay در مسیر PATH ماشین قرار نداره کامند اجرا نشده و جاب failed شده
با تغییر دادن فایل گیتلب ci به این مقدار

	script:
		- /usr/games/cowsay "hi"

این مشکل رو میتونیم حل کنیم یا راه حل های دیگه ای که خودتون میتونید برای اینجا ارائه بدید
و بعد از اینکه این تغییر رو پوش کردیم روی ریپوزیتوری گیتلب میبینیم که یک پایپ لاین جدید اجرا شده و موفق بوده

جمع بندی

بصورت کلی برای مدیریت رانر باید با همین موضوعات سر و کار داشته باشید. اجرا کردن جاب های موقتی که فقط برای چک کردن خروجی هایی که توی لاگ های جاب بوجود میاد انجام میشه تا تغییر دادن مقادیر فایل config.toml ماشین رانر مواردی هست که توی مبحث گیتلب رانر ازشون زیاد استفاده میشه