طريقة تشغيل GitHub Actions وGitLab CI محليًا قبل الدفع

يمكنك تشغيل GitHub Actions على حاسوبك باستخدام act، وGitLab CI باستخدام gitlab-ci-local: يقرأ كلاهما ملف خط المعالجة ويبدأ كل مهمة داخل حاوية Docker. ثبّت Docker ثم المشغّل، وشغّل act -j test أو gitlab-ci-local test من مجلد المستودع. تفشل المهمة المعطوبة الآن خلال ثوانٍ على جهازك بدل أن تنتظر دفعًا ثم مشغّلًا مستضافًا.

يشرح هذا الدليل ما تثبّته على macOS وWindows ولينكس، وأوامر المشغّلين، ونموذج سير عمل تنسخه، وحدود التشغيل المحلي، وأول الأخطاء التي يصادفها الناس. ويستخدم الشرح GitTree، برنامج Git الذي نصنعه: تفحص صفحة خطوط المعالجة المحلية فيه ما ثبّتّه، وتكتب ملفًا نموذجيًا، وتجهّز لك الأمر الدقيق. خطوط المعالجة المحلية جزء من الخطة المجانية في GitTree ولا تحتاج إلى حساب استضافة.

لماذا تشغّل خطوط CI محليًا؟

كل تعديل على ملف سير العمل شيفرة لا تستطيع اختبارها حتى تعمل. دون مشغّل محلي تكون الدورة: عدّل YAML، أودِع، ادفع، انتظر المشغّل، اقرأ السجل، وكرّر. تكلّف كل دورة دقائق وتترك أثرًا من إيداعات مثل «جرّب مجددًا». أما التشغيل المحلي فيقصّر الدورة إلى ثوانٍ ويبقي السجل نظيفًا.

ما تحتاج إليه: Docker ومشغّل واحد

يبدأ المشغّلان كل مهمة داخل حاوية، لذا يجب أن يكون محرك Docker مثبّتًا ويعمل: Docker Desktop أو OrbStack أو Colima على macOS، وDocker Desktop على Windows، وDocker Engine أو Docker Desktop على لينكس. ثم ثبّت المشغّل المناسب لملفك.

يحتاج gitlab-ci-local إلى Node.js 18 أو أحدث عند تثبيته بـ npm. تحقّق من الإعداد بـ docker info وact --version وgitlab-ci-local --version: إن فشل docker info فشغّل المحرك قبل أي شيء آخر.

تشغيل GitHub Actions محليًا باستخدام act

شغّل act من المجلد الجذر للمستودع. اعرض المهام أولًا ثم شغّل التي تعمل عليها. يحاكي act حدث push افتراضيًا، لذا تحتاج المهام التي تعمل على أحداث أخرى إلى اسم الحدث.

# list workflows and jobs
act -l

# run one job from one workflow file
act -W .github/workflows/ci.yml -j test

# simulate a pull request instead of a push
act pull_request -j test

# pass a secret the job needs
act -j deploy -s NPM_TOKEN="$NPM_TOKEN"

# Apple silicon: run x86_64 images
act -j test --container-architecture linux/amd64

يسأل التشغيل الأول عن صورة المشغّل. يناسب Medium معظم المشاريع؛ فالصور الصغيرة تفتقد أدوات تتضمّنها المشغّلات المستضافة، والصورة الكاملة كبيرة جدًا. إن فشلت خطوة بخطأ «command not found» فاختر صورة أكبر بـ -P ubuntu-latest=<image> أو ثبّت الأداة في خطوة.

تشغيل GitLab CI محليًا باستخدام gitlab-ci-local

يقرأ gitlab-ci-local الملف .gitlab-ci.yml من المجلد الحالي. دون وسائط يشغّل خط المعالجة كاملًا، ومع اسم مهمة يشغّلها وحدها. ويعرض --list المهام دون تشغيلها، وهي طريقة سريعة للتأكد من صحة YAML.

# list jobs and stages
gitlab-ci-local --list

# run one job
gitlab-ci-local test

# pass a CI/CD variable
gitlab-ci-local test --variable API_URL=http://localhost:8080

نموذج سير عمل تبدأ منه

هذا شكل نموذج GitHub Actions في GitTree: مهمتان، بناء ثم اختبار، تعملان بالطريقة نفسها مع act وعلى GitHub. استبدل الأوامر بأوامرك.

name: GitTree local check

on:
  push:
  pull_request:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4
      - name: Test
        run: npm test

كيف يختلف التشغيل المحلي عن CI المستضاف

• الأسرار والمتغيرات المضبوطة على GitHub أو GitLab غير متاحة؛ مرّر ما تحتاج إليه المهمة.
• حاويات لا آلات افتراضية: الخدمات التي تحتاج إلى systemd أو آلة افتراضية كاملة لا تعمل بالطريقة نفسها.
• الصور تختلف عن المشغّلات المستضافة؛ الأداة الناقصة حزمة ناقصة لا سير عمل معطوب.
• الأحداث محاكاة: يفترض act حدث push؛ ويحلّ المشغّل سير العمل القابل لإعادة الاستخدام والتضمينات والقوالب، لا محررك.
• نجاح التشغيل المحلي ليس نتيجة مستضافة: إنه يقصّر الدورة، ويبقى القول الفصل لمنصة الاستضافة.

أخطاء شائعة وحلولها

قبل الدفع: توقّع التعارضات وافحص الأسرار وعاين ما سيُرسل

التشغيل المحلي للمسار يجيب عن سؤال واحد: هل ستنجح المهام. وهناك ثلاثة فحوص أخرى تلتقط ما يبلّغ عنه CI متأخرًا أو لا يبلّغ عنه أصلًا، وكل منها يعمل على جهازك أيضًا قبل إرسال أي شيء.

1. توقّع الدمج. ينفّذ الأمر git merge-tree --write-tree --name-only HEAD origin/main الدمج في الذاكرة ويسرد الملفات التي ستتعارض دون أن يلمس شجرة عملك. ويجري GitTree فحصًا من النوع نفسه ويحذّرك قبل دمج سيتعارض؛ راجع كيف تحل تعارضات الدمج في Git.
2. افحص الأسرار. قبل الإيداع أو الدفع يفحص GitTree التغيير محليًا بحثًا عن رموز وكلمات مرور ومفاتيح خاصة محتملة، ويتوقف بحوار إن وجد شيئًا منها. والسر الذي يصل إلى المستودع البعيد يجب تدويره، فأرخص لحظة لالتقاطه هي قبل الدفع. والتحذير ليس ضمانًا، فراجع ما ترسله في كل الأحوال.
3. عاين الدفع. تسرد معاينة الإطلاق (Ship Preview) الـ commits والملفات التي سيرسلها الدفع، وتبيّن لكل ملف workflow تستطيع قراءته هل المسار سيعمل أو قد يعمل أو لن يعمل مع هذا الدفع، مع السبب.

ثم شغّل المهمة محليًا وادفع مرة واحدة. ويشرح دليل تحذيرات الأسرار ودليل معاينة الإطلاق الحوارين بالتفصيل.

وماذا عن Bitbucket Pipelines وAzure Pipelines؟

لا يوجد مشغّل محلي مُصان لـ bitbucket-pipelines.yml أو azure-pipelines.yml يضاهي act أو gitlab-ci-local. والحل العملي أن تضع أوامر البناء والاختبار في سكربتات تستدعيها من خط المعالجة المستضاف، وتضيف ملف GitHub Actions أو GitLab CI صغيرًا للتشغيل المحلي فقط. ويعلّم GitTree تلك الملفات بـ لا مشغّل محلي ويعرض النماذج لهذا الغرض تحديدًا.

الخطوات التالية: يشرح دليل تشغيل خطوط المعالجة محليًا كل زر، ويغطي تشغيلات CI/CD التشغيلات المستضافة وإعادة التشغيل والموافقات، ويسرد مشغّل الأدوات أدوات GitTree المدمجة الأخرى.