Skip to main content

معرفی سرویس گیت‌لب رانر

مقدمه​

امروزه تحویل پیوسته نرم‌افزار به عنوان یکی از رویکردهای موفق و فراگیر حوزه نرم‌افزار شناخته‌ می‌شود. در این رویکرد، تغییرات کد به صورت مرحله‌ای و مکرر وارد چرخه ساخت، تست و استقرار می‌شوند. به دلیل ادغام و تست و تحویل پیوسته اجزا و سرویس‌ها، سرعت ارائه محصول و رفع نیازمندی‌های مشتریان (به عنوان مزیتی رقابتی) افزایش می‌یابد.

مفهوم Continuous Integration​

نرم افزاری را در نظر بگیرید که دارای یک مخزن کد یا ریپو است. توسعه‌دهندگان چندین‌بار در روز، کد جدیدی را در این ریپو push می‌کنند. هر بار، مجموعه‌ای از scriptها جهت ساخت و تست به‌ صورت‌ خودکار اجرا می‌شوند. این عمل، که به آن Continuous Integration می‌گویند، تاثیر چشم‌گیری در کاهش بروز خطا و افزایش سرعت ارائه محصول داشته و باعث می‌شود که تغییرات، در هر branch از ریپو، به صورت دوره‌ای با تست‌ها، دستورالعمل‌ها و استاندارد‌های برنامه‌نویسی موردنظر پروژه هم‌راستا شوند.

مفهوم Continuous Delivery/Deployment​

Continuous Delivery یک مرحله فراتر از Continuous Integration است. نه‌ تنها، هر بار مراحل ساخت و تست اجرا می‌شوند، بلکه نرم‌افزار به شکل خودکار در محیط‌های مختلف مستقر می‌شود. تفاوت Continuous Deployment با Continuous Delivery این است که الزاما در دومی استقرار به صورت خودکار صورت نمی‌گیرد و نیاز به مداخله انسانی جهت استقرار نسخه جدید هست.

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

راه‌اندازی سرویس GitLab Runner​



سرویس GitLab Runner با نسخه‌های مختلف گیتلب از جمله سرویس گیتلب هم‌روش (هم‌گیت) یا گیتلب اختصاصی شرکتها سازگاری دارد و جهت راه‌اندازی آن، تنها لازم است مراحل زیر را دنبال کنید.

  1. ریپو (repository) یا گروهی از ریپوها (Group) که تمایل دارید GitLab Runner برای آن ثبت شود، را انتخاب کرده و به قسمت CI/CD تنظیمات آن (در منو سمت چپ صفحه) مراجعه کنید. در قسمت مربوط به Runners، مطابق با تصویر زیر، URL و registration token را شناسایی کنید. در صورتی که از گروه برای دسته‌بندی ریپوهایتان استفاده می‌کنید، پیشنهاد می‌کنیم GitLab Runner را در سطح گروه ثبت کنید تا تمام ریپو‌های گروه امکان استفاده از آن را داشته‌باشند.

همچنین در صورتی‌ که از گیتلب اختصاصی خودتان در سطح شرکت استفاده می‌کنید، می‌توانید از صفحه‌ی تنظیمات رانرها در ادمین اطلاعات ساخت Shared Runner جدید را مشاهده کنید.

  1. به صفحه دارکوب در کنسول هم‌روش مراجعه کنید. سپس در قسمت «ساخت اپ»، ذیل «ساخت اپ آماده»، GitLab Runner را انتخاب کنید. در صفحه «تنظیمات اپ»، یک نام برای Runner برگزیده و اطلاعاتی که از مرحله قبل به‌ دست‌ آوردید را وارد کنید.
  1. در صفحه بعد، پس از انتخاب پلن مورد نظر، گزینه «ساخت اپ» را انتخاب کنید.

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

تنظیمات GitLab Runner​

در تنظیمات CI/CD پروژه یا گروه، لیستی به نام Available runners وجود دارد که حاوی GitLab Runnerهای ثبت‌شده است. در این قسمت، با انتخاب گزینه Edit روبروی هر نسخه از GitLab Runner، می‌توانید تنظیمات مربوط به آن را تغییر دهید. به طور مثال با تنظیم tagهای هر GitLab Runner، می‌توانید استفاده پروژه‌ها از آن‌ را مدیریت کنید. برای اطلاعات بیشتر در این زمینه، می‌توانید به قسمت tags در تنظیمات ci مراجعه کنید.

توصیف چرخه CI/CD​

با ساخت فایل .gitlab-ci.yml در root هر پروژه‌، می‌توانید stageهای مورد نظر چرخه CI/CD را توصیف و با هر بار push کردن کد یا به صورت دستی آن‌ها را اجرا کنید. GitLab Runner در عین سادگی و راحتی، ویژگی‌های منعطف و پیشرفته‌ای از جمله اعمال محدودیت‌های مختلف بر شرایط اجرای چرخه ، به‌کارگیری serviceهای آماده حین اجرای چرخه و استفاده از متغیر‌های محیطی را فراهم می‌کند. می‌توانید برای آشنایی و بررسی این ویژگی‌ها به مستندات رسمی مراجعه کنید. اگر در ساخت و تنظیم چرخه CI/CD خود با چالشی روبرو هستید یا سوالی برایتان پیش‌ آمده ‌است، لطفا آن را در پشتیبانی هم‌روش با ما در میان بگذارید.

متغیر‌های محیطی​

می‌توانید از امکان تنظیم و استفاده از متغیرهای محیطی در گیتلب استفاده کنید. برای این کار، می‌توانید به قسمت Settings => CI/CD => Variables مراجعه کرده و نام و مقدار متغیرهای مورد نظرتان را ثبت کنید. در فایل .gitlab-ci.yml با فرمت VARIABLE_NAME$ می‌توانید به مقدار متغیرها دسترسی داشته باشید. این امکان به طور ویژه برای مدیریت و استفاده‌ از مقادیر محرمانه (که نباید در کد قرار داده ‌شوند) مفید است. برای اطلاعات بیشتر، می‌توانید به قسمت variables از مستندات GitLab مراجعه کنید.

جزئیات CI/CD پروژه‌ها​

در منوی سمت چپ هر پروژه، گزینه‌ای به نام CI/CD وجود دارد که حاوی پاره‌ای از تنظیمات و جزئیات مربوط‌ به چرخه‌ها است. در قسمت Pipelines و Jobs، می‌توانید وضعیت و لاگ‌های چرخه‌ها و جزئیات مربوط به هر stage را مشاهده کنید.

بروز مشکل در اجرای چرخه​

در صورتی‌ که مشکلی در اجرا چرخه رخ ‌داده ‌است، می‌توانید به لاگ job مراجعه کرده و علت را بررسی کنید. در صورتی که مشکل ناشی از کد باشد (مثل وجود نقصان در داکرفایل یا شکست‌خوردن تست‌ها)، لازم است اصلاحات مناسب در کد اعمال شود. اگر در حل این دست از خطاها با چالشی روبرو شده‌اید و نیاز به راهنمایی دارید، لطفا آن را در پشتیبانی هم‌روش با ما در میان بگذارید. اگر خطای چرخه مربوط به کد نیست، لطفا ابتدا یک‌بار دکمه‌ی retry را در صفحه‌ی job مربوط بزنید و در صورت بروز دوباره‌ی مشکل، به پشتیبانی هم‌روش اطلاع دهید.

اجرای دستی چرخه​

در صورتی که به هر دلیلی چرخه مورد نظر اجرا نمی‌شود و یا تمایل به اجرا چرخه بدون push کردن کد را دارید، می‌توانید این کار را به صورت دستی انجام دهید. در قسمت Pipelines، دکمه‌ی سبز رنگ Run Pipeline را بزنید، برنچ مورد نظر و متغیر‌های مورد نیاز را مشخص کنید و سپس چرخه را اجرا کنید. متغیر‌های تعریف‌شده در قسمت Variables پروژه به صورت پیش‌فرض به چرخه داده خواهند ‌شد.

چرخه CI/CD اپ‌های دارکوبی​

در حالت مشتریان سازمانی، اگر حین ساخت اپ با دارکوب، از گزینه «منبع گیت» استفاده ‌کنید و آدرس پروژه‌ای در هم‌گیت یا نسخه دیگری از GitLab را ثبت کنید، فایل .gitlab-ci.yml به‌طور خودکار در ریپو شما ساخته‌ خواهد شد و محتوایی مشابه با زیر خواهد‌ داشت. با این حال، در صورت تمایل، می‌توانید stageهای جدیدی به این فایل اضافه کنید. در صورت نیاز، می‌توانید jobهای مربوط به build و deploy دارکوب را تغییر دهید. مقادیر متغیرهای APP_ID و DEPLOY_TOKEN در صفحه‌ی ویرایش اپ در دارکوب قابل‌ مشاهده است.

darkube_build_appname_namespace:
  image: hamravesh.hamdocker.ir/public/darkube-cli:v1.1
  only:
    refs:
    - master
  script:
    - export IMAGE="registry.hamdocker.ir/hamravesh/appname"
    - 'darkube build --push -t $IMAGE:$CI_COMMIT_SHORT_SHA -t $IMAGE:$CI_COMMIT_REF_SLUG
       --file Dockerfile --build-context . --build-arg ENV=SAMPLE_ENV'
  stage: build
darkube_deploy_appname_namespace:
  image: hamravesh.hamdocker.ir/public/darkube-cli:v1.1
  only:
    refs:
    - master
  script:
    - 'darkube deploy --token ${DEPLOY_TOKEN}
      --app-id ${APP_ID}  --image-tag "${CI_COMMIT_SHORT_SHA}"
      --job-id "${CI_JOB_ID}"'
  stage: deploy

اتصال به کانتینر رجیستری​

استفاده از دارکوب برای build​

در صورتی که در مرحله‌ی build تعریف ‌شده در فایل .gitlab-ci.yml از ایمیج darkube-cli استفاده می‌کنید، لازم است متغیر‌های محیطی REGISTRY، REGISTRY_USER و REGISTRY_PASSWORD در تنظیمات CI/CD ریپو یا گروه تعریف شده‌ باشند. به طور کلی، با تنظیم این مقادیر در سطح گروه یا ریپو، دارکوب برای push و pull کردن image، از رجیستری جدید استفاده خواهد.

تعریف چرخه شخصی‌سازی‌شده​

اگر مرحله‌ی build شما شخصی‌سازی شده‌ است، می‌توانید اطلاعات اتصال به رجیستری موردنظر را با تعریف متغیرهای CI/CD در اختیار jobها قرار دهید. یک راه رایج برای این منظور تنظیم متغیر DOCKER_AUTH_CONFIG است که در این لینک جزئیات بیشتری درباره آن خواهید یافت. درباره نحوه تعیین مقدار این متغیر نیز می‌توانید به این لینک مراجعه کنید.

دیپلوی از طریق curl​

در صورت تمایل می‌توانید برای دیپلوی نسخه جدید اپ خود، به جای استفاده از darkube-cli اندپوینت زیر را در جاب دیپلوی gitlabci.yml فراخوانی کنید:

PUT https://api.console.hamravesh.ir/api/v1/darkube/apps/update_from_cli/
{
    "trigger_deploy_token": # دیپلوی توکن
    "app_id": # شناسه اپ,
    "image_tag": # تگ ایمیج,
}

اطلاعات مربوط به دیپلوی توکن و شناسه اپ در صفحه مشخصات اپ قابل دستیابی هستند.

مشکلات متداول رانر به هنگام بیلد​

ایجاد نشدن pipeline بعد از کامیت​

  • اگر در .gitlab-ci.yml با استفاده از ‍changes مسیر و یا مسیر‌هایی را تعریف کرده‌اید، باید بررسی کنید که آیا با مسیر فایل و یا فایل‌هایی که تغییر کرده‌اند، تطابق دارند یا خیر. چرا که اگر چنین نباشد، هیچ pipelineی ایجاد نخواهد شد.
  • توجه داشته باشید که فایل .gitlab-ci.yml همیشه باید در root پروژه قرار داشته باشد. رعایت نکردن این مورد هم یکی دیگر از دلایل بوجود آمدن این مشکل است.
  • با فرض اینکه رانر وجود دارد و به گیتلب متصل است، اگر رانر در وضعیت ready نباشد، jobیی اجرا نخواهد شد.

valid نبودن .gitlab-ci.yml​

برای دیباگ کردن فایل .gitlab-ci.yml می‌توانید از CI Lint موجود در صفحه pipelineهای پروژه استفاده کنید.

ERROR: Job failed: exit code 137​

کد خطای 137 بیانگر کمبود مموری می‌باشد.

ERROR: Job failed: exit code 1​

زمانی که jobی با کد خطای 1 به پایان می‌رسد، نمی‌توان نظر قطعی در رابطه با دلیل fail شدن job داد و همیشه نیازمند بررسی و مشاهده لاگ‌ها است.

<command>: command not found​

این خطا بدین معنی است که دستوری که از آن استفاده کرده‌اید، در داخل ایمیجی که در حال استفاده از آن هستید، وجود ندارد. برای رفع خطا می‌بایست پکیج مورد نظر را به ایمیج‌تان اضافه کنید.

ERROR: failed to prepare *: open /.../committed: no such file or directory​

این مورد از طریق "خالی‌کردن کش" برطرف می‌شود.

خطا‌های مربوط به network​

ممکن است یک job به هنگام دریافت یک پکیج و یا ایجاد ریکوئست، با خطاهایی روبه‌رو شود. در این میان خطاهایی همانند timout از جنس خطاهایی هستند که عموما از اختلالات شبکه‌ای ناشی می‌شوند و معمولا با تلاش مجدد موفق می‌شوند. برای این کار به jobهای خود retry: 2 را اضافه کنید. به جای عدد 2 هر عددی که مناسب به نظر می‌رسد را می‌توانید قرار دهید. اما خطا‌هایی مانند Access Denied: 403 مربوط به موارد تحریمی هستند. در صورت برخورد با این نوع خطا‌ها، مورد را از طریق تیکت با ما در میان بگذارید.