DevOps والتشغيل الأدلة التقنية

مفهوم CI/CD للمبتدئين: من كل Push إلى سيرفر يعمل

ما الذي يعنيه التكامل المستمر والتسليم المستمر فعلاً، وكيف تبني خطاً صغيراً يختبر كل Push وينشر إلى staging ويتحقق منه، مع الأخطاء الحقيقية التي يكشفها وتلك التي لا يكشفها.

مفهوم CI/CD للمبتدئين: من كل Push إلى سيرفر يعمل

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

وفي ما هو DevOps؟ رأينا نشراً يدوياً نسي سيرفراً واحداً، ثم سكربتاً ينشر من وسم Git ويتحقق من كل سيرفر، وقلنا إن ما ينقصه أن يعمل وحده مع كل تغيير دون أن يتذكر أحد تشغيله، وأن يبني ويختبر قبل أن ينشر. وهذا بالضبط ما يسمى خط CI/CD. وفي هذا المقال نشرح المفهوم من البداية، ثم نبني خطاً حقيقياً على جهازك بـ Gitea وGitea Runner، يختبر كل Push، وينشر إلى بيئة staging عندما تنجح الاختبارات على main، ويتحقق من أن الخدمة تعمل بعد النشر. وقبل أن تبدأ تأكد أنك تقرأ ملفات YAML بثقة، فخط CI ملف YAML قبل كل شيء، وقد شرحناها في YAML للمبتدئين. وسوف نناقش في هذا المقال ما يلي:

  • من أين جاء التكامل المستمر، وما قواعده الأساسية، وما الفرق بين التسليم المستمر والنشر المستمر Continuous Deployment.
  • مكونات أي خط CI/CD: الحدث، وملف الخط، والمهام والخطوات، والـ Runner، والأسرار.
  • تجربة كاملة: Gitea 28.3.0 مع Runner 5.3.0، وخط بمهمتين test وdeploy، ومشكلتان حقيقيتان ظهرتا في أول تشغيل وكيف حللناهما.
  • ماذا يحدث عندما يفشل اختبار، وعندما ينجح الاختبار ويفشل النشر، وعندما يأتي التغيير من طلب دمج.
  • صفات الخط الجيد، والأدوات المشهورة، وأخطاء تجعل الفريق يتجاهل اللون الأحمر.

من أين جاء التكامل المستمر؟ Continuous Integration

قبل التكامل المستمر Continuous Integration كانت الفرق تعمل أسابيع على فروع منفصلة، ثم تأتي مرحلة اسمها «التكامل» يجمع فيها الجميع عملهم، وكانت هذه المرحلة مشهورة بأنها لا يعرف أحد كم تستغرق، فقد تأخذ يوماً وقد تأخذ أسابيع، لأن كل فرع تغير بعيداً عن الآخرين، والتعارضات بينها لا تظهر إلا عند الجمع. وكان الناس يسمونها «جحيم التكامل Integration Hell».

وجاءت الفكرة المعاكسة من ممارسات البرمجة القصوى Extreme Programming في التسعينيات، كما يذكر Martin Fowler في مقاله المرجعي Continuous Integration: إذا كان التكامل مؤلماً فافعله أكثر، أي أن يدمج كل مطور عمله في الفرع الرئيسي Mainline مرة في اليوم على الأقل، وأن يتحقق نظام آلي بعد كل دمج أن المشروع ما زال يبنى وتنجح اختباراته. فبدلاً من مرحلة تكامل كبيرة كل شهر تصبح عندك مئات التكاملات الصغيرة، وكل واحدة منها إذا فشلت فأنت تعرف بالضبط أي تغيير سببها، لأنه التغيير الوحيد منذ آخر نجاح.

ولاحظ أن التكامل المستمر في أصله ممارسة وليس أداة، فالأداة التي تبني وتختبر بعد كل دفع، ويسميها الناس أحياناً «سيرفر CI»، لا تفيد إذا بقي كل مطور على فرعه أسبوعين، لأنك تختبر باستمرار شيئاً لا يتكامل. ولذلك ترتبط هذه الممارسة مباشرة بالفروع القصيرة التي شرحناها في التطوير على الفرع الرئيسي Trunk-Based، وبطلبات الدمج الصغيرة التي شرحناها في مراجعة الكود Code Review.

قواعد التكامل المستمر CI Practices

يجمع مقال Fowler وصفحة التكامل المستمر في أبحاث DORA مجموعة قواعد، وأهمها لفريق يبدأ:

  • كل الكود في مستودع واحد، وكل شخص يدمج في الفرع الرئيسي يومياً: وإلا فلا يوجد تكامل لتختبره.
  • كل دفع يبني المشروع آلياً: بنفس الأوامر في كل مرة، على جهاز نظيف وليس على جهاز شخص.
  • البناء يختبر نفسه Self-testing Build: البناء الذي ينجح دون أن يشغل الاختبارات لا يقول شيئاً عن صحة الكود.
  • البناء سريع: يتحدث Fowler عن قاعدة العشر دقائق، والسبب أن المطور الذي ينتظر نتيجة تأتي بعد ساعة يكون قد بدأ عملاً آخر ونسي ما كتب.
  • الخط الأحمر يصلح فوراً: عندما يفشل البناء على الفرع الرئيسي يتوقف الجميع عن الدمج فوقه حتى يصلح، إما بإصلاح سريع أو بالتراجع عن التغيير الذي سببه.
  • النتيجة مرئية للجميع: كل شخص يعرف حالة الفرع الرئيسي الآن، وأي Commit كسر الاختبارات، دون أن يسأل.

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

أربعة صناديق تكبر من اليمين إلى اليسار على محور من بعد الكتابة مباشرة إلى بعد أيام أو أسابيع: على جهازك أخضر صغير ثوان تصلحه وحدك، ثم في خط CI أزرق دقائق ما زلت تتذكر ما كتبت، ثم في Staging برتقالي ساعات فريق الاختبار ينتظر، ثم في الإنتاج أحمر كبير عملاء متأثرون تراجع عاجل وتحقيق وثقة تضيع، وتحته خط CI/CD ينقل اكتشاف أغلب الأخطاء من اليسار إلى اليمين
الخطأ نفسه، وأربعة أثمان مختلفة بحسب المكان الذي يكتشف فيه

التسليم المستمر مقابل النشر المستمر Continuous Delivery

الحرفان CD في CI/CD يستخدمان لمعنيين مختلفين، وهذا سبب كثير من سوء الفهم في الفرق، والصورة التالية تبين الفرق على نفس المراحل:

صف من ست دوائر من اليمين: Push ثم بناء ثم اختبار ثم نسخة جاهزة خضراء ثم Staging بنفسجية ثم الإنتاج Production حمراء، وتحتها ثلاثة أشرطة: التكامل المستمر Continuous Integration يغطي من Push إلى نسخة جاهزة، كل Push يدمج ويبنى ويختبر آلياً خلال دقائق، ثم التسليم المستمر Continuous Delivery يغطي حتى Staging مع أيقونة أشخاص، كل نسخة نجحت جاهزة للإنتاج والنشر إليه بزر يضغطه إنسان، ثم النشر المستمر Continuous Deployment يغطي حتى الإنتاج، كل نسخة نجحت تصل إلى الإنتاج تلقائياً دون أي تدخل، وفي الأعلى الحرفان CD يستخدمان للمعنيين فاسأل دائماً من يضغط زر الإنتاج
الفرق بين المعنيين في سؤال واحد: من يضغط زر الإنتاج؟
  • التسليم المستمر Continuous Delivery: يعرفه Jez Humble في موقع Continuous Delivery بأنه القدرة على إيصال التغييرات من كل الأنواع إلى الإنتاج أو إلى المستخدمين بأمان وسرعة وبطريقة يمكن الاستمرار عليها. وعملياً يعني أن كل نسخة نجحت في الخط جاهزة للنشر في أي لحظة، وأن النشر إلى الإنتاج قرار عمل يتخذه إنسان بزر، وليس مشروعاً هندسياً يحتاج أسبوعاً.
  • النشر المستمر Continuous Deployment: خطوة أبعد، فكل نسخة نجحت تذهب إلى الإنتاج تلقائياً دون أن يضغط أحد شيئاً. وهذا يحتاج إلى ثقة كبيرة في الاختبارات والمراقبة والتراجع الآلي، ولا يناسب كل منتج.

وقد يتساءل البعض: أيهما يجب أن أطبق؟ والإجابة أن أغلب الفرق تبدأ بالتسليم المستمر، أي نشر آلي إلى staging مع كل دمج، ونشر إلى الإنتاج بزر، ثم تقرر بعد أن ترى ثبات الخط هل تحتاج إلى أكثر. وتشرح صفحة التسليم المستمر في DORA أن المقصود أن يكون النشر روتيناً منخفض المخاطر يمكن فعله في أي وقت، وليس حدثاً نادراً، وقد شرحنا البيئات dev وstaging والإنتاج وكيف تنقل النسخة بينها في البيئات ومعاينة الميزات وGitOps.

مكونات خط CI/CD Pipeline Anatomy

أياً كانت الأداة، Gitea Actions أو GitHub Actions أو GitLab CI أو Jenkins، فكل خط CI/CD يتكون من القطع نفسها، وأسماؤها تختلف قليلاً بين الأدوات:

القطعةما هيفي تجربتنا
الحدث Triggerما الذي يبدأ تشغيل الخطpush إلى main، وpull_request
ملف الخط Workflowملف YAML في المستودع يصف كل شيء.gitea/workflows/ci.yml
المهمة Jobمجموعة خطوات تعمل معاً على جهاز واحدtest ثم deploy
الخطوة Stepأمر واحد أو Action جاهزpython -m unittest -v
المنفذ Runnerالبرنامج الذي يستلم المهام من السيرفر وينفذهاGitea Runner v5.3.0
بيئة المهمةContainer تعمل فيه الخطوات، ويحدده الوسم Labelpython وdocker
الاعتماد Dependencyمهمة لا تبدأ إلا بعد نجاح غيرهاneeds: test
الأسرار Secretsكلمات المرور والمفاتيح التي يحتاجها الخط دون أن تكون في الكودلم نحتجها في التجربة المحلية

وأهم فكرة في الجدول أن الخط كله ملف في المستودع، أي أنه يتغير بطلب دمج ويراجع ويرجع إلى نسخة سابقة مثل الكود تماماً، وهذا ما يجعل البناء نفسه قابلاً للتكرار، فلا يوجد إعداد مخفي في واجهة أداة لا يعرف أحد من غيره.

والأحداث ليست الدفع وطلبات الدمج فقط، فأغلب الأدوات تقبل أحداثاً أخرى تفيدك لاحقاً: schedule لتشغيل الخط في وقت محدد مثل كل ليلة، وهو مناسب لاختبارات طويلة أو فحص الثغرات Vulnerabilities في الاعتماديات الذي قد يجد مشكلة جديدة في كود لم يتغير، وworkflow_dispatch لتشغيله بزر يدوي كما سوف نرى في النشر إلى الإنتاج، والدفع لوسم Tag مثل v1.4.0 لبناء إصدار رسمي له رقم. والقاعدة أن تختار لكل عمل الحدث الذي يناسب سرعته وتكلفته، فالاختبارات السريعة مع كل دفع، والبطيئة ليلاً، والإصدار مع الوسم، والإنتاج بقرار بشري.

من سكربت النشر إلى الخط From Script to Pipeline

قد يتساءل البعض: إذا كان عندي سكربت deploy.sh يعمل، فما الذي يضيفه الخط؟ والإجابة أن السكربت يحل مشكلة «كيف ننشر بالطريقة نفسها في كل مرة»، أما الخط فيحل ثلاث مشاكل أخرى لا يحلها السكربت: متى ينشر، وعلى أي جهاز، وماذا يحدث قبله. والجدول التالي يضع الاثنين بجانب بعضهما بحسب ما رأيناه في المقالين:

السؤالسكربت deploy.shخط CI/CD
من يبدأ النشر؟شخص يتذكر أن يشغلهالدفع إلى main نفسه
أين يعمل؟على جهاز من ينشر، بأدواته وإعدادهفي Container نظيف مبني من ملف في المستودع
هل تعمل الاختبارات قبله؟إذا تذكر من ينشر أن يشغلهادائماً، والنشر لا يبدأ إذا فشلت
من يرى النتيجة؟من شغل السكربت، وملف السجل على جهازهكل الفريق في تبويب Actions، مع سجل كل خطوة
ماذا عن طلبات الدمج؟لا علاقة له بهايختبر كل طلب قبل أن يراجعه أحد
كيف يتغير؟يعدله من يملكهبطلب دمج ومراجعة مثل أي كود

ولاحظ أن الخط لم يلغ فكرة السكربت، فخطوات Deploy to staging وSmoke test في المختبر هي نفسها ما كان يفعله السكربت: انسخ الإصدار المحدد، ثم تأكد أن الخدمة ترد به. والذي تغير هو المكان الذي تعمل فيه هذه الخطوات، والشرط الذي يسبقها. ولذلك فإذا كان فريقك اليوم بلا أي أتمتة فلا تقفز مباشرة إلى خط كامل، وإنما اكتب السكربت أولاً كما في تجربة مقال DevOps، ثم ضعه داخل خط عندما يستقر، فالسكربت الذي يعمل يدوياً سوف يعمل في الخط، أما الذي لا تفهمه يدوياً فسوف يفشل في الخط بطريقة أصعب في الفهم.

تجربة عملية: خط يختبر وينشر إلى staging

سوف نبني على جهازك خطاً لخدمة حاسبة الفواتير التي استخدمناها في مقال مراجعة الكود، وقد أضفنا إليها سيرفر HTTP صغيراً بمكتبة Python القياسية يعرض /health مع رقم الإصدار و/demo مع حساب فاتورة. والصورة التالية تبين شكل المختبر:

dvb-laptop على اليمين يدفع git push إلى dvb-gitea الذي يقرأ ملف الخط .gitea/workflows/ci.yml وينشئ المهام، ثم dvb-runner v5.3.0 يسأل عن مهمة ويستخدم docker.sock لتشغيل حاويات المهام على شبكة dvb-net: مهمة test في dvb-ci-python:3.13 تشغل python -m unittest، ثم مهمة deploy بعد نجاح test في docker:29.9.2-cli تبني وتشغل وتختبر، وتنشر إلى dvb-staging مع /health
المكونات الأربعة للمختبر، والأرقام بترتيب ما يحدث بعد كل دفع

تجهيز Gitea مع الـ Runner

نبدأ بـ Gitea مثل المقالات السابقة، ثم ننشئ رمز تسجيل Registration Token للـ Runner من سطر الأوامر، وهو الرمز الذي يثبت للسيرفر أن هذا الـ Runner مسموح له أن يأخذ المهام:

docker network create dvb-net
docker run -d --name dvb-gitea --network dvb-net -p 3471:3000 \
  -e GITEA__security__INSTALL_LOCK=true \
  -e GITEA__server__ROOT_URL=http://localhost:3471/ \
  -e GITEA__database__DB_TYPE=sqlite3 \
  -v dvb-gitea-data:/data gitea/gitea:28.3.0

docker exec -u git dvb-gitea gitea admin user create --admin \
  --username dev1 --password 'Lab-Pass-2026!' --email [email protected] --must-change-password=false
docker exec -u git dvb-gitea gitea actions generate-runner-token

ثم نكتب إعداد الـ Runner في الملف runner-config.yaml، وأهم ما فيه الوسوم Labels التي تربط ما يكتبه الخط في runs-on بالـ Image التي تعمل فيها المهمة، كما في توثيق Gitea Runner. وهذه هي النسخة النهائية بعد المشكلتين اللتين سوف نشرحهما بعد قليل:

log:
  level: info
runner:
  capacity: 1
  timeout: 30m
  labels:
    - "python:docker://dvb-ci-python:3.13"
    - "docker:docker://docker:29.9.2-cli"
container:
  network: dvb-net
  force_pull: false
  # keep the staging container that the deploy job starts (runner 5 removes it by default)
  sweep: false
docker run -d --name dvb-runner --network dvb-net \
  -e GITEA_INSTANCE_URL=http://dvb-gitea:3000 \
  -e GITEA_RUNNER_REGISTRATION_TOKEN="$TOKEN" \
  -e GITEA_RUNNER_NAME=runner-01 \
  -e CONFIG_FILE=/config/config.yaml \
  -v "$PWD/runner-config.yaml:/config/config.yaml:ro" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dvb-runner-data:/data gitea/runner:5.3.0
docker logs dvb-runner
level=info msg="Registering runner, arch=amd64, os=linux, version=v5.3.0."
level=info msg="Runner registered successfully."
SUCCESS
level=info msg="Starting runner daemon"
level=info msg="runner: runner-01, with version: v5.3.0, with labels: [python docker], declare successfully"

في الإعداد أعلاه لاحظ التالي:

  • capacity: 1 يعني مهمة واحدة في الوقت نفسه، وهذا مناسب لجهاز واحد، وtimeout: 30m يوقف أي مهمة علقت بدلاً من أن تحجز الـ Runner إلى الأبد.
  • network: dvb-net يضع حاويات المهام على شبكة المختبر، فتصل إلى Gitea بالاسم dvb-gitea وإلى بيئة staging بالاسم dvb-staging.
  • ربط /var/run/docker.sock يجعل المهام تعمل على Docker جهازك مباشرة، وهو الأبسط في مختبر، ولكنه يعني أن أي خط يستطيع أن يتحكم في كل Containers الجهاز، ولذلك فقد اخترنا في دليل Gitea Actions النوع المعزول dind لسيرفر الفريق، فاقرأ الفرق هناك قبل أن تشغل Runner على سيرفر حقيقي.

وبعد التسجيل يظهر الـ Runner في Site Administration ← Actions ← Runners بحالة Idle ووسميه:

صفحة Runners Management في إعدادات المدير في Gitea وفيها runner-01 بحالة Idle وID 1 والإصدار v5.3.0 والنوع Global والوسوم python وdocker وLast Online Time now
الـ Runner متصل وينتظر المهام، ووسماه هما ما يكتبه الخط في runs-on

ملف الخط Workflow سطراً سطراً

في المستودع ثلاثة ملفات للتطبيق: invoice.py وtest_invoice.py بالاختبارات الثلاثة التي كتبناها في مقال المراجعة، وapp.py للسيرفر، ومعها ملف Dockerfile صغير يبني Image التطبيق ويضع فيه رقم الإصدار:

FROM python:3.13-slim
WORKDIR /app
COPY invoice.py app.py ./
ARG APP_VERSION=dev
ENV APP_VERSION=$APP_VERSION
USER nobody
EXPOSE 8000
CMD ["python", "app.py"]

وهذا هو ملف الخط .gitea/workflows/ci.yml:

name: ci

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: python
    steps:
      - uses: builtin:checkout
      - name: Unit tests
        run: python -m unittest -v

  deploy:
    needs: test
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: docker
    defaults:
      run:
        shell: sh
    steps:
      - uses: builtin:checkout
      - name: Build image
        run: |
          TAG=$(echo "$GITHUB_SHA" | cut -c1-7)
          docker build --build-arg APP_VERSION=$TAG -t invoice-tool:$TAG .
          echo "TAG=$TAG" >> "$GITHUB_ENV"
      - name: Deploy to staging
        run: |
          docker rm -f dvb-staging || true
          docker run -d --name dvb-staging --network dvb-net invoice-tool:$TAG
      - name: Smoke test
        run: |
          sleep 2
          wget -qO- http://dvb-staging:8000/health
          wget -qO- http://dvb-staging:8000/health | grep -q "\"version\": \"$TAG\""

في الملف أعلاه لاحظ التالي:

  • الحدثان: push إلى main فقط، وpull_request لأي طلب دمج، فالفروع الأخرى لا تشغل الخط إلا عندما يفتح لها طلب.
  • needs: test يجعل deploy ينتظر نجاح test، فإذا فشل الاختبار لا يبدأ النشر أصلاً، وif يقصر النشر على الدفع إلى main، فطلبات الدمج تختبر ولا تنشر.
  • builtin:checkout ميزة في Runner منذ الإصدار 4 تنسخ المستودع دون تنزيل Action من الإنترنت، وهي بديل خفيف لـ actions/checkout الذي يحتاج Node داخل الـ Image.
  • الوسم TAG هو أول سبعة أحرف من هاش الـ Commit، فكل Image مربوطة بالكود الذي بنيت منه بالضبط، ونمرره إلى خطوة لاحقة بكتابته في الملف $GITHUB_ENV، لأن المتغيرات العادية لا تنتقل بين الخطوات.
  • خطوة Smoke test هي «التحقق بعد النشر» نفسه الذي كتبناه في سكربت deploy.sh، فهي لا تكتفي بأن السيرفر يرد، وإنما تتأكد أنه يرد بالإصدار الذي نشرناه للتو.

ماذا يحدث داخل الـ Runner؟ How a Runner Works

قبل أن نرى النتائج يفيدك أن تعرف ما الذي يحدث بين الدفع وأول سطر في السجل، لأن أغلب مشاكل الخطوط الأولى تأتي من هذه المسافة. فسيرفر Gitea لا يتصل بالـ Runner ولا يعرف عنوانه، وإنما الـ Runner هو الذي يسأل السيرفر كل ثانيتين تقريباً: هل عندك مهمة لوسومي؟ وإذا لم يجد يزيد الفاصل تدريجياً حتى خمس ثوان كما في الإعدادات الافتراضية fetch_interval وfetch_interval_max التي يولدها الأمر gitea-runner config generate. ولهذا يكفي أن يصل الـ Runner إلى Gitea، ولا يحتاج Gitea إلى الوصول إلى الـ Runner، فتستطيع أن تضعه خلف جدار ناري Firewall لا يقبل أي اتصال داخل.

وعندما يستلم الـ Runner مهمة يحدث ما رأيناه في أسطر التحضير في السجل، وقد حذفناها من المخرج السابق للاختصار:

image: python:3.13-slim
network: dvb-net
docker pull image=python:3.13-slim platform= username= forcePull=false
docker create image=python:3.13-slim platform= entrypoint=["sleep" "1800"] cmd=[] network="dvb-net"
docker run image=python:3.13-slim platform= entrypoint=["sleep" "1800"] cmd=[] network="dvb-net"
  • يتأكد أن الـ Image موجودة، ويسحبها إذا لم تكن، وforcePull=false يعني أنه لا يسحبها من جديد إذا وجدها على الجهاز، ولهذا كان أول تشغيل أبطأ من التالية.
  • ينشئ Container للمهمة بأمر بديل sleep 1800، أي أن الـ Container لا يفعل شيئاً بنفسه، وإنما يبقى حياً مدة المهمة، ثم ينفذ الـ Runner كل خطوة داخله واحدة بعد الأخرى، ولذلك تشترك الخطوات في الملفات نفسها داخل المهمة، ولا تشترك المهام المختلفة في شيء إلا بما تمرره صراحة.
  • ينسخ المستودع إلى مجلد العمل /workspace/dev1/invoice-tool، وهو المسار الذي ظهر في رسالة الاختبار الفاشل لاحقاً، ثم يعطي الخطوات متغيرات بيئة جاهزة مثل GITHUB_SHA وGITHUB_REF وGITHUB_EVENT_NAME، وتحمل الأسماء نفسها في Gitea لكي تعمل ملفات GitHub Actions دون تعديل كبير.
  • في النهاية يحذف Container المهمة وما شغلته المهمة، وهذا هو التنظيف الذي سبب لنا المشكلة الثانية.

وهذا الشكل، Container جديد ونظيف لكل مهمة، هو ما يجعل الخط قابلاً للتكرار: لا توجد ملفات بقيت من تشغيل سابق، ولا مكتبة ثبتها شخص على الجهاز يدوياً، فإذا نجح الخط مرة فسوف ينجح مرة ثانية على الكود نفسه.

المشكلة الأولى: builtin:checkout needs git on PATH

في النسخة الأولى من الإعداد كان الوسم python يشير إلى python:3.13-slim مباشرة، فلما دفعنا أول مرة فشلت مهمة test في ست ثوان، وتخطى Gitea مهمة deploy، وهذا ما ظهر في سجلها:

image: python:3.13-slim
Complete job name: test
builtin:checkout needs git on PATH
##[error]checkout: clone dev1/invoice-tool@refs/heads/main: Process completed with exit code 127.
Job failed

الرسالة واضحة: builtin:checkout يستنسخ المستودع بأداة git الموجودة داخل Image المهمة، وImage python:3.13-slim لا تحتوي على git لأنها مصغرة، ورمز الخروج 127 في الطرفية يعني «الأمر غير موجود». أما Image docker:29.9.2-cli فتأكدنا أن فيها git، فمهمة النشر لم تكن لتواجه المشكلة. والحل أن تكون للمهمة Image فيها ما تحتاجه، فبنينا Image صغيرة للخط فوق Python:

# Job image for the "python" runner label: Python plus git, which builtin:checkout needs.
FROM python:3.13-slim
RUN apt-get update \
 && apt-get install -y --no-install-recommends git ca-certificates \
 && rm -rf /var/lib/apt/lists/*
docker build -t dvb-ci-python:3.13 ci-image/

ثم غيرنا الوسم في الإعداد إلى dvb-ci-python:3.13، وأعدنا تشغيل الـ Runner، ثم ضغطنا إعادة التشغيل Re-run للخط. وهذا درس عام: كل ما تفترضه الخطوة يجب أن يكون داخل الـ Image، والـ Image المعدة لتشغيل التطبيق في الإنتاج غالباً ليست مناسبة كما هي لتشغيل الخط، ولذلك تملك أغلب الفرق Images خاصة للخط، مثبتة الإصدار ومبنية من ملف في المستودع.

المشكلة الثانية: النشر نجح ثم اختفت بيئة staging

بعد الإصلاح نجحت المهمتان، ورأينا في سجل خطوة Smoke test رد الخدمة بالإصدار الصحيح، ولكن عندما سألنا Docker عن Container بيئة staging لم نجده، وكانت آخر أسطر السجل تشرح السبب:

{"status": "ok", "version": "d9838fd"}
Cleaning up container for job deploy
removing container dvb-staging the job left behind
Job succeeded

الـ Runner في الإصدار 5 ينظف بعد كل مهمة الـ Containers التي شغلتها المهمة عبر Docker، حتى لا تتراكم بقايا الاختبارات على الجهاز، وهذا سلوك جيد لخطوات البناء والاختبار، ولكنه يحذف أيضاً ما نشرناه عمداً. وفي ملاحظات الإصدار 5.0.0 وجدنا الإعداد الذي يتحكم بذلك، وقد أضيف في طلب الدمج 1275: container.sweep: false يحتفظ بالخدمات التي تنشرها المهام على Docker الخاص بالـ Runner. فأضفناه وأعدنا التشغيل، فبقي الـ Container:

dvb-staging invoice-tool:d9838fd Up 9 seconds

وهذه المشكلة تكشف شيئاً أهم من الإعداد نفسه: النشر إلى نفس Docker الذي ينفذ المهام طريقة مختبر، فهو يخلط بين جهاز البناء وجهاز التشغيل. وفي الواقع يكون Runner على جهاز، وبيئة staging على سيرفر آخر، والنشر يتم بطلب إلى ذلك السيرفر، مثل webhook أو SSH أو تحديث مستودع إعداد يراقبه أداة GitOps، كما في طرق نشر التطبيقات. والإعداد sweep: false مناسب هنا لأننا نريد أن نرى الفكرة كاملة على جهاز واحد.

أول خط أخضر Green Pipeline

وهذا سجل مهمة test بعد الإصلاح، بعد حذف أسطر التحضير:

image: dvb-ci-python:3.13
network: dvb-net
Complete job name: test
From http://dvb-gitea:3000/dev1/invoice-tool
 * branch            d9838fd70a2797a8c4bec3bd5f34a44a1f6db78f -> FETCH_HEAD
python -m unittest -v
test_discount_before_vat (test_invoice.TotalTest.test_discount_before_vat) ... ok
test_discount_out_of_range (test_invoice.TotalTest.test_discount_out_of_range) ... ok
test_vat (test_invoice.TotalTest.test_vat) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK
Job succeeded

ثم مهمة deploy، وفيها بناء الـ Image بوسم الـ Commit، وتشغيلها، والتحقق منها:

#8 naming to docker.io/library/invoice-tool:d9838fd
docker rm -f dvb-staging || true
docker run -d --name dvb-staging --network dvb-net invoice-tool:$TAG
wget -qO- http://dvb-staging:8000/health
{"status": "ok", "version": "d9838fd"}
Job succeeded

وفي سجل البناء الكامل سطور كثيرة تبدأ بأرقام مثل #5 و#8، وهي مراحل البناء في BuildKit، وأهم ما تنظر إليه فيها كلمة CACHED بجانب سطر FROM python:3.13-slim، أي أن Docker لم يسحب الـ Image الأساسية ولم يعد بناءها لأنها موجودة، فلم يأخذ البناء إلا ثانية واحدة تقريباً. ولهذا رتبنا ملف Dockerfile بحيث تأتي الأسطر التي لا تتغير أولاً، والملفات التي تتغير مع كل Commit في الآخر، فلا يعاد إلا الجزء الأخير.

لاحظ أن الإصدار الذي ردت به الخدمة d9838fd هو نفسه هاش ال Commit الذي دفعناه، فمن يفتح staging يعرف بالضبط أي كود يراه، وهذا يغني عن سؤال «هل نشرتم آخر تعديل؟». وقد استغرق أول تشغيل ناجح قرابة دقيقتين لأنه تضمن تحضير الـ Images، أما التشغيلات التالية فكانت بين 16 و25 ثانية للمهمتين معاً على جهاز المختبر.

ماذا يحدث إذا فشل اختبار؟ What If

الآن نجرب السبب الذي من أجله يوجد الخط، فدفعنا إلى main تغييراً يبدو بريئاً، وهو تعديل ثابت الضريبة من 0.15 إلى 0.05، كأن شخصاً أخطأ في رقم:

sed -i "s/^VAT = 0.15/VAT = 0.05/" invoice.py
git commit -qam "Change VAT constant" && git push
test_discount_before_vat (test_invoice.TotalTest.test_discount_before_vat) ... FAIL
test_discount_out_of_range (test_invoice.TotalTest.test_discount_out_of_range) ... ok
test_vat (test_invoice.TotalTest.test_vat) ... FAIL

======================================================================
FAIL: test_discount_before_vat (test_invoice.TotalTest.test_discount_before_vat)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/workspace/dev1/invoice-tool/test_invoice.py", line 10, in test_discount_before_vat
    self.assertEqual(total([(100, 2)], discount=50), 172.5)
AssertionError: 157.5 != 172.5

======================================================================
FAIL: test_vat (test_invoice.TotalTest.test_vat)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/workspace/dev1/invoice-tool/test_invoice.py", line 7, in test_vat
    self.assertEqual(total([(100, 2), (50, 1)]), 287.5)
AssertionError: 262.5 != 287.5

----------------------------------------------------------------------
Ran 3 tests in 0.002s

FAILED (failures=2)
صفحة التشغيل Change VAT constant #2 في Gitea Actions: مهمة test بحالة Failure ومدتها 18s، وفيها Set up job وRun builtin:checkout ناجحتان وUnit tests وComplete job فاشلتان، ومهمة deploy بأيقونة التخطي ومدتها 0s، وزر Re-run failed jobs
الاختبار فشل، والنشر لم يبدأ أصلاً

في النتيجة أعلاه لاحظ التالي:

  • الاختبار لم يقل «هناك خطأ» فقط، وإنما قال أين وكم: 157.5 بدلاً من 172.5، و262.5 بدلاً من 287.5، فيعرف من دفع التغيير خلال دقيقة أن الضريبة هي المشكلة.
  • مهمة deploy تخطيت بسبب needs: test، وعندما سألنا staging بعد ذلك رد بالإصدار السابق {"status": "ok", "version": "d9838fd"}، أي أن الخطأ لم يصل إلى أي بيئة.
  • الاختبار test_discount_out_of_range نجح لأنه لا يعتمد على قيمة الضريبة، وهذا يبين لماذا تحتاج إلى أكثر من اختبار، فالاختبار الواحد يغطي جانباً واحداً.

والإصلاح الأسرع في مثل هذه الحالة هو التراجع عن التغيير بالأمر git revert وليس محاولة إصلاح سريع فوقه، والسبب أن الفرع الرئيسي يجب أن يعود أخضر بأسرع ما يمكن حتى لا يدمج أحد فوق خطأ:

git revert --no-edit HEAD
git push
[main 04ed0b1] Revert "Change VAT constant"
{"status": "ok", "version": "04ed0b1"}
{"total": 287.5}

دفعنا التراجع في الساعة 11:25:11، وانتهت مهمة deploy في 11:25:42 بتوقيت UTC، أي أن الكود وصل من جهاز المطور إلى staging مختبراً ومتحققاً منه خلال 31 ثانية، دون أن يلمس أحد السيرفر. وهذا هو زمن التغيير Change Lead Time الذي ذكرناه في مقاييس DORA، في أصغر صوره.

ماذا يحدث مع طلب دمج؟ Pull Request

بعد ذلك أنشأنا فرعاً يضيف اسم الخدمة إلى /health، ودفعناه وفتحنا له طلب دمج. فشغل Gitea الخط بحدث pull_request، ونجحت مهمة test، وتخطيت مهمة deploy بسبب شرط if، وبقي staging على 04ed0b1:

4 Add service name to health check pull_request success 63901b2
test success
deploy skipped
{"status": "ok", "version": "04ed0b1"}

وهذا ما تريده تماماً: كل طلب دمج يختبر قبل أن يراه المراجع، فلا يضيع وقته في كود لا تنجح اختباراته، ولا ينشر إلا ما دمج في main. وتستطيع في قاعدة حماية الفرع التي شرحناها في مقال المراجعة أن تجعل نجاح مهمة test شرطاً للدمج، فلا يدمج طلب أحمر حتى بموافقة.

ماذا لو نجح الاختبار وفشل النشر؟ What If

التجربة الأخيرة أهم من كل ما سبق، لأنها تبين ما لا يمسكه الخط. دفعنا تغييراً يجعل التطبيق يقرأ المنفذ من متغير البيئة PORT، ولكن القيمة الافتراضية كتبت 9000 بدلاً من 8000. والاختبارات لا تشغل السيرفر، وإنما تختبر دالة الحساب، فنجحت كلها، ثم بدأ النشر:

docker rm -f dvb-staging || true
docker run -d --name dvb-staging --network dvb-net invoice-tool:$TAG
dvb-staging
8c3a1cde92bd53ba384f86695d88cc182cc083a07cac0092e72b77bb2054c48f
wget -qO- http://dvb-staging:8000/health
wget: can't connect to remote host (192.168.96.6): Connection refused
##[error]Process completed with exit code 1.
Job failed

اختبار الدخان Smoke Test أمسك المشكلة وأفشل الخط باللون الأحمر، وهذا جيد، ولكن انظر إلى الترتيب: الخطوة السابقة حذفت Container الإصدار السليم ثم شغلت الجديد، وبعدها فقط تحقق الاختبار. فعندما سألنا staging بعد الفشل:

wget: can't connect to remote host (192.168.96.6): Connection refused
dvb-staging invoice-tool:2e6307f Up About a minute

بيئة staging كانت متوقفة عن الخدمة، والـ Container يعمل ولكن على منفذ آخر. ولو كانت هذه بيئة الإنتاج Production لكان العملاء يرون خطأ حتى يتراجع أحد. والدرس أن التحقق بعد النشر يخبرك بالمشكلة ولكنه لا يمنعها، والذي يمنعها هو ترتيب مختلف: شغل الإصدار الجديد بجانب القديم، وتحقق منه، ثم حول الحركة إليه، واحذف القديم في الآخر، وهذه فكرة النشر الأزرق والأخضر Blue-Green التي جربناها خلف Nginx في طرق نشر التطبيقات. والدرس الثاني أن الاختبارات التي لا تشغل التطبيق كما يشغل في الإنتاج لا تمسك أخطاء التشغيل، ولذلك تضيف الفرق اختبارات تكامل Integration Tests تشغل الـ Container فعلاً قبل النشر، كما في أنواع الاختبارات للمبتدئين.

وأصلحنا الموقف بنفس الطريقة: git revert ثم دفع، فعاد الخط أخضر وعاد staging بالإصدار 2516860. والصورة التالية تبين قائمة التشغيلات الست كما ظهرت في Gitea، وفيها القصة كاملة:

تبويب Actions في المستودع dev1/invoice-tool وفيه 6 workflow runs من الأحدث: Revert Read port from PORT env ناجح على main في 16s، وRead port from PORT env فاشل على main في 17s، وAdd service name to health check ناجح على طلب الدمج #1 في 4s، وRevert Change VAT constant ناجح على main في 25s، وChange VAT constant فاشل على main في 19s، وInvoice service with CI/CD pipeline ناجح على main في 1m54s
ستة تشغيلات: خطآن أمسكهما الخط، وتراجعان أعادا main إلى الأخضر
صفحة التشغيل Revert Change VAT constant #3 في Gitea: مهمة test ناجحة في 5s ومهمة deploy ناجحة في 19s، وخطوات deploy: Set up job وRun builtin:checkout وBuild image في 3s وDeploy to staging في 7s وSmoke test في 4s وComplete job، كلها بعلامة خضراء
مهمة النشر بخطواتها الأربع، وكل خطوة لها سجلها الخاص

التراجع إلى إصدار سابق Rollback

استخدمنا في المختبر git revert مرتين، وهو تراجع يمر بالخط كله: Commit جديد، ثم اختبار، ثم بناء، ثم نشر، وهذا أسلم طريق لأنه يترك أثراً في التاريخ ويمر بالفحوص نفسها. ولكن عندما تكون الخدمة متوقفة كما في التجربة الأخيرة فقد لا تريد أن تنتظر الخط كله، وهنا تظهر فائدة الوسم المربوط بالـ Commit، فقد بقيت على الجهاز Images الإصدارات السابقة بأسمائها:

04ed0b1 176MB
d9838fd 176MB

فالتراجع السريع هو أن تشغل Image الإصدار الأخير الذي تعرف أنه سليم، دون أي بناء، لأنها نفس الـ Image التي اختبرت ونشرت من قبل، ثم تصلح المشكلة في الكود وتتركها تمر بالخط بهدوء. ولاحظ أن الحجم 176MB لكل Image لا يعني أن كل واحدة تأخذ هذه المساحة على القرص، لأن الطبقات Layers المشتركة مثل Python تحفظ مرة واحدة، ولكن مع الوقت تتراكم الإصدارات، فاحتفظ بآخر عشرة مثلاً واحذف الأقدم بسياسة تنظيف في الـ Registry. وقد شرحنا الـ Registry ورفع الـ Images إليه من الخط في أول workflow يبني Image ويرفعها.

زر النشر إلى الإنتاج Manual Approval

توقفنا في المختبر عند staging، وهذا ما يسميه الناس التسليم المستمر. والخطوة التالية في فريق حقيقي أن تضيف مهمة ثالثة تنشر إلى الإنتاج، ولكنها لا تعمل مع كل دفع، وإنما عندما يطلبها إنسان. وأبسط طريقة لذلك في Gitea Actions وGitHub Actions هي الحدث workflow_dispatch، الذي يضيف زراً في تبويب Actions لتشغيل الخط يدوياً، ومعه مدخلات مثل رقم الإصدار الذي تريد نشره، فتكتب في ملف منفصل خطاً يأخذ وسم Image موجودة سلفاً، أي التي نجحت في staging، وينشرها إلى سيرفر الإنتاج دون أن يبنيها من جديد. وبهذا يبقى قرار النشر إلى الإنتاج قراراً بشرياً، ولكن تنفيذه آلي ومتكرر ومسجل: من ضغط الزر، ومتى، وأي إصدار.

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

التنظيف Cleanup

docker rm -f dvb-gitea dvb-runner dvb-laptop dvb-staging
docker volume rm dvb-gitea-data dvb-runner-data
docker network rm dvb-net
docker rmi $(docker images invoice-tool -q) dvb-ci-python:3.13

ماذا تعلمنا من تعطل شامل؟ Staged Rollout

الخط الآلي يجعل النشر سريعاً، وهذا يعني أيضاً أن الخطأ الذي يفلت من الاختبارات يصل بسرعة إلى الجميع، إلا إذا كان النشر نفسه متدرجاً.

📌
في 19 يوليو 2024 الساعة 04:09 بتوقيت UTC أرسلت CrowdStrike تحديث محتوى لمستشعر Windows في منتجها Falcon، فتعطلت أجهزة Windows التي استلمته وكانت متصلة حتى 05:27، بحسب المراجعة الأولية التي نشرتها الشركة. وذكرت المراجعة أن أداة التحقق من المحتوى Content Validator كان فيها خطأ برمجي جعل أحد قوالب التحديث يمر من الفحص رغم أن بياناته فيها مشكلة، وأن هذا النوع من التحديثات كان يرسل إلى كل الأجهزة دفعة واحدة. ومن أهم ما التزمت به الشركة بعد الحادثة أن تنشر هذا المحتوى بشكل متدرج Staggered Deployment، يبدأ بنشر تجريبي على مجموعة صغيرة Canary ثم يتوسع إلى أجزاء أكبر. والدرس أن الفحص الآلي نفسه قد يخطئ، وأن النشر المتدرج هو ما يجعل الخطأ الذي يفلت منه يصيب قليلاً من المستخدمين بدلاً من كلهم.

وفي فريق صغير لا تحتاج إلى نظام معقد لتطبيق الفكرة نفسها، فبيئة staging هي أول مرحلة، ثم سيرفر واحد من سيرفرات الإنتاج قبل الباقي، أو Feature Flag تفتح الميزة لنسبة صغيرة من المستخدمين كما شرحنا في مفهوم Feature Flags والإطلاق التدريجي، مع مراقبة تقول لك خلال دقائق هل زادت الأخطاء.

صفات الخط الجيد Pipeline Qualities

  • سريع: الخط الذي يستغرق ساعة لا يستخدمه أحد كما يجب، فالمطورون يجمعون تغييرات أكثر في كل دفع لكي ينتظروا مرات أقل، فتعود الدفعات الكبيرة. وابدأ بالأسرع: الفحص والاختبارات السريعة أولاً، والبطيئة بعدها أو بالتوازي.
  • موثوق: الاختبار الذي يفشل أحياناً دون سبب، أي الاختبار المتقلب Flaky Test، يعلم الفريق أن يضغط إعادة التشغيل دون أن يقرأ، فإذا جاء فشل حقيقي ضغطوا الزر نفسه، فأصلحه أو احذفه فوراً.
  • يبني مرة واحدة: الـ Image التي اختبرت في staging هي نفسها التي تذهب إلى الإنتاج بنفس الوسم، ولا يعاد البناء لكل بيئة، والسبب أن البناء الثاني قد يسحب مكتبة بإصدار مختلف، وقد شرحنا ذلك في ابن ال Docker Image مرة واحدة.
  • يحفظ الأسرار خارج الملف: كلمات المرور Passwords والرموز في أسرار المستودع Secrets وليس في ملف الخط، والخط يخفيها في السجلات، كما في الأسرار والمتغيرات في Gitea Actions.
  • يعمل على Runner معزول: الـ Runner ينفذ كوداً من المستودع، فمن يملك صلاحية الدفع يستطيع أن يشغل أي أمر عليه، ولذلك لا تشغله على سيرفر الإنتاج نفسه، ولا تمرر له مقبس Docker على سيرفر فيه خدمات أخرى، وثبت كل Action خارجية على هاش Commit.
  • يتحقق بعد النشر: رد الخدمة بالإصدار المتوقع، وليس فقط نجاح أمر النسخ أو التشغيل، كما رأيت في المختبر.

وإذا أردت أن تبني خطاً كاملاً بهذه الصفات، بفحص الاعتماديات والأسرار وتوقيع الـ Images، فقد شرحنا ذلك في خط CI/CD آمن من البداية للنهاية.

من يملك الخط؟ Pipeline Ownership

الخط ليس مشروعاً تبنيه مرة ثم تنساه، وإنما جزء من الكود يتغير معه، ولذلك يحتاج إلى من يملكه، وفي فريق صغير يملكه الجميع بقواعد بسيطة. فمن يكسر الخط على main يصلحه أو يتراجع عن تغييره قبل أن يبدأ أي عمل آخر، والسبب أن الخط الأحمر يوقف الفريق كله، فكل دمج فوقه يخلط خطأه بأخطاء جديدة. وملف الخط نفسه يتغير بطلب دمج ومراجعة مثل أي كود، بل بعناية أكبر، لأن تغييراً صغيراً فيه يغير ما يعمل على الـ Runner وما يصل إلى الإنتاج، وتستطيع في Gitea أن تجعل المجلد .gitea/workflows/ من الملفات المحمية في قاعدة حماية الفرع، فلا يتغير إلا بموافقة شخص محدد.

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

أدوات CI/CD المشهورة Tools

المفاهيم في هذا المقال لا تتغير بين الأدوات، والذي يتغير هو مكان الملف وبعض الأسماء، وهذه أشهر الخيارات:

الأداةمكان ملف الخطمتى تناسبك
Gitea Actions.gitea/workflows/*.ymlعندما يكون Gitea هو مستودعك، وصيغته قريبة جداً من GitHub Actions، والفروق في صفحة المقارنة
GitHub Actions.github/workflows/*.ymlعندما يكون الكود على GitHub، ومعه سوق كبير من Actions الجاهزة
GitLab CI.gitlab-ci.ymlعندما يكون الكود على GitLab، والخط فيه جزء من المنصة نفسها
JenkinsJenkinsfileعندما تحتاج مرونة كبيرة وإضافات كثيرة وتقبل إدارة سيرفر خاص به
Woodpecker CI.woodpecker/*.ymlعندما تريد أداة خفيفة مستقلة تعمل مع Gitea وغيره

ونصيحتنا لفريق يبدأ أن يستخدم الأداة المدمجة في منصة الكود التي يستخدمها، لأن الأسرار والصلاحيات Permissions وحالة الطلبات كلها في مكان واحد، وأن يؤجل المقارنة بين الأدوات حتى يعرف ما الذي ينقصه فعلاً.

أخطاء شائعة Common Mistakes

  • خط بلا اختبارات: يبني وينشر كل شيء، فيصبح طريقاً أسرع لإيصال الأخطاء إلى الإنتاج، فابدأ ولو باختبار واحد للجزء الأهم.
  • تجاهل الخط الأحمر: عندما يفشل الخط على main ويستمر الناس في الدمج فوقه، تختلط الأخطاء ولا يعرف أحد أي Commit سبب ماذا، فأوقف الدمج حتى يعود أخضر.
  • Image مهمة لا تحتوي على ما تحتاجه الخطوات: كما حدث معنا مع git، فاجعل Images الخط مبنية من ملف في المستودع ومثبتة الإصدار.
  • النشر قبل التحقق: حذف الإصدار القديم ثم تشغيل الجديد ثم الاختبار يترك الخدمة متوقفة إذا فشل الاختبار، فشغل الجديد بجانب القديم وتحقق قبل التحويل.
  • أسرار في ملف الخط أو في السجلات: أي شخص يقرأ المستودع أو سجلات التشغيل يراها، فاستخدم Secrets ولا تطبعها.
  • إعادة البناء لكل بيئة: ما اختبرته ليس ما نشرته، فابن مرة وانقل الـ Image نفسها.
  • كل شيء في مهمة واحدة طويلة: عندما يفشل الخط لا تعرف من النظرة الأولى هل فشل الاختبار أم البناء أم النشر، ولا تستطيع أن تعيد تشغيل الجزء الفاشل وحده، فقسم العمل إلى مهام صغيرة بأسماء واضحة واربطها بـ needs كما في المختبر، فيقول لك اسم المهمة الحمراء أين تبدأ البحث.
  • Runner بصلاحيات الإنتاج: يجعل كل من يدفع كوداً يملك الإنتاج، فاعزله.

قائمة تحقق Checklist

السؤالكيف تتأكد
هل يعمل الخط مع كل Push إلى main ومع كل طلب دمج؟تبويب Actions فيه تشغيل لكل دفع ولكل طلب
هل يشغل الاختبارات قبل أي نشر؟مهمة النشر فيها needs على مهمة الاختبار
هل يأخذ أقل من عشر دقائق؟مدة التشغيل في قائمة التشغيلات
هل تعرف أي Commit يعمل في staging؟الخدمة ترد بالإصدار أو هاش الـ Commit
هل يتحقق الخط من الخدمة بعد النشر؟خطوة Smoke Test تفشل الخط إذا لم ترد الخدمة بالإصدار الجديد
هل الإصدار القديم يعمل حتى يثبت الجديد نفسه؟طريقة النشر تشغل الجديد بجانب القديم قبل التحويل
هل الأسرار في Secrets وليست في الملف؟البحث في المستودع لا يجد كلمات مرور، والسجلات تعرض ***
هل الـ Runner معزول عن الإنتاج؟يعمل على جهاز منفصل أو بوضع dind، ولا يملك مفاتيح الإنتاج إلا عبر Secrets محددة

تدريب عملي Practice

بعد أن يعمل المختبر عندك، جرب هذه التمارين بالترتيب، فكل واحد منها يضيف قطعة من الخط الحقيقي:

  1. أضف إلى مهمة test خطوة قبل الاختبارات تشغل yamllint على ملف الخط نفسه، كما شرحنا في مقال YAML، ثم ادفع ملف workflow فيه خطأ إزاحة، ولاحظ أين يظهر الخطأ هذه المرة.
  2. غير خطوة النشر بحيث تشغل الإصدار الجديد باسم مؤقت مثل dvb-staging-new، وتتحقق منه، ثم تحذف القديم وتعيد تسمية الجديد، وكرر تجربة المنفذ 9000 لترى أن staging القديم بقي يعمل عندما فشل التحقق.
  3. أضف مهمة ثالثة integration تشغل Image التطبيق وتطلب /demo وتتأكد أن الناتج 287.5، واجعل deploy يعتمد عليها، ثم كرر تجربة المنفذ، ولاحظ أن الخطأ أصبح يمسك قبل النشر وليس بعده.
  4. فعل قاعدة حماية على main تشترط نجاح مهمة test، ثم افتح طلب دمج فيه اختبار فاشل، وحاول أن تدمجه.

وإذا أنهيت التمارين الأربعة فقد بنيت بيدك ما تسميه الفرق خطاً ناضجاً لمشروع صغير: فحص للملفات، واختبارات وحدة، واختبار تكامل يشغل التطبيق، ونشر لا يوقف الخدمة إذا فشل، وحماية تمنع دمج الأحمر.

ماذا تقرأ بعد ذلك؟ Next Steps

دليلGitea Actions: تشغيل CI/CD وبناء Docker Images على سيرفركاجعل سيرفرك يختبر الكود ويبني Docker Images تلقائياً مع كل push، دون أن يخرج كودك أو أسرارك إلى خدمة CI خارجية.دليلمن الفرع إلى الإنتاج: البيئات وGitOps للفرقكيف يختبر فريقك كل ميزة وحدها ويعرضها على العميل دون أن تصل ميزة غير جاهزة إلى الإنتاج.دليلخط CI/CD آمن من البداية للنهاية على Gitea Actionsكيف تجمع فحوص الأمن في خط واحد لا يستطيع طلب الدمج تجاوزه، ثم ترسل إلى الإنتاج نفس ال Docker Image الموقعة التي فحصتها.دليلطرق نشر التطبيقات من FTP إلى GitOps، وأين تقف أنتكيف تطور نشر التطبيقات عبر السنين، وما الذي يتعطل في كل طريقة، وكيف تعرف أين تقف وما خطوتك التالية.

إذا أردت أن تنقل هذا الخط إلى سيرفر فريقك بـ Runner معزول وRegistry للـ Images فاتبع Gitea Actions: تشغيل CI/CD على سيرفرك، وإذا أردت أن ترى كيف تنتقل النسخة نفسها من staging إلى الإنتاج بcommit في مستودع إعداد فاقرأ البيئات ومعاينة الميزات وGitOps.

الخلاصة Summary

  • التكامل المستمر ممارسة قبل أن يكون أداة: دمج يومي في الفرع الرئيسي، وبناء واختبار آلي سريع مع كل دفع، وإصلاح فوري عندما يصبح الخط أحمر.
  • التسليم المستمر يعني أن كل نسخة نجحت جاهزة للإنتاج بزر، والنشر المستمر يعني أنها تصل إليه تلقائياً، والفرق في من يضغط الزر.
  • في المختبر احتجنا إلى إصلاحين حقيقيين: Image للمهمة فيها git لأن builtin:checkout يحتاجه، وsweep: false لأن Runner 5 يحذف ما تشغله المهام.
  • أمسك الخط تغيير الضريبة الخاطئ قبل أي نشر، وأوصل التراجع إلى staging خلال 31 ثانية، واختبر طلب الدمج دون أن ينشره.
  • عندما نجحت الاختبارات وفشل التشغيل أمسك اختبار الدخان المشكلة ولكن بعد أن توقف staging، فالتحقق بعد النشر لا يكفي وحده، وإنما تحتاج إلى تشغيل الجديد بجانب القديم ونشر متدرج.

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة المقال واختبار الخط على Gitea 28.3.0 مع Gitea Runner v5.3.0 وdocker:29.9.2-cli وPython 3.13.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.