.gitlab-ci.yml (stages / jobs)

بنية pipeline في GitLab CI/CD .gitlab-ci.yml (stages / jobs)

.gitlab-ci.yml ملف YAML واحد في جذر المستودع يعرّف كل الـ pipeline في GitLab CI/CD عبر stages متسلسلة تحتوي كل واحدة عدة jobs تعمل بالتوازي.

بدل مجلد .github/workflows/ مع عدة ملفات منفصلة كما في GitHub Actions، GitLab يستخدم ملف واحد .gitlab-ci.yml في جذر المستودع. البنية الأساسية مرحلتان من التسلسل الهرمي: stage (مرحلة) تمثل تجميعة زمنية — لا تبدأ مرحلة إلا بعد نجاح كل jobs المرحلة السابقة — وjob (وظيفة) هي وحدة العمل الفعلية التي تحتوي script بأوامر التنفيذ. كل الـ jobs داخل نفس stage تعمل بالتوازي تلقائياً دون إعداد إضافي.

المعادل لـ needs في GitHub Actions هنا غير إلزامي بشكل افتراضي لأن الترتيب بين stages مضمون تلقائياً؛ يُستخدم needs في GitLab فقط لكسر هذا الترتيب الافتراضي وتشغيل job أبكر عمداً (DAG pipelines). artifacts مدمجة مباشرة في بنية الـ job نفسها بدل action منفصل، وتُمرَّر تلقائياً بين المراحل التالية.

الصياغة

<اسم الوظيفة>:
  stage: <اسم المرحلة>
  script:
    - <أمر>

📄 مثال

build-job:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

test-job:
  stage: test
  script:
    - npm test

deploy-job:
  stage: deploy
  script:
    - echo "نشر $CI_COMMIT_BRANCH"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

أهم النقاط

العنصر	الوظيفة
stage	المرحلة التي تنتمي إليها الوظيفة؛ المراحل تُنفَّذ بالتسلسل، والوظائف بنفس المرحلة تتوازى
script	قائمة الأوامر التي يُنفّذها الـ runner فعلياً لهذه الوظيفة
artifacts	ملفات تُمرَّر تلقائياً للمراحل التالية، مدمجة في بنية الوظيفة نفسها
rules / only	شروط تتحكم بتشغيل الوظيفة (فرع معين، حدث معين)، مشابهة لـ if في GitHub Actions

💡 نصائح عملية

استخدم rules بدل only/except القديمة نسبياً — أكثر مرونة وهي الاتجاه الموصى به حالياً في وثائق GitLab
الـ tags على مستوى job تحدد أي runner (بذلك الوسم) يُنفّذها، مفيد لتوجيه وظائف معينة لـ runner له إمكانيات خاصة (GPU، Docker...)

⚠️ أخطاء شائعة

توقع أن jobs بمراحل مختلفة تعمل بالتوازي — التسلسل بين stages مضمون وإلزامي ما لم تُستخدم needs لكسره عمداً
الخلط بين متغيرات GitLab المدمجة (مثل $CI_COMMIT_BRANCH) ومتغيرات GitHub Actions (github.ref) عند نقل pipeline بين المنصتين

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار DEVOPS الكامل بالعربي.

📚 للتعمق التقني الكامل بالإنجليزية: MDN Web Docs