> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# مفهوم CI/CD للمبتدئين: من كل Push إلى سيرفر يعمل
- URL: https://arabroot.io/articles/مفهوم-ci-cd-للمبتدئين-من-كل-push-الى-سيرفر-يعمل/
- Published: 2026-11-03T11:36:36.000Z
- Updated: 2026-11-03T12:36:01.000Z
- Description: ما الذي يعنيه التكامل المستمر والتسليم المستمر فعلاً، وكيف تبني خطاً صغيراً يختبر كل Push وينشر إلى staging ويتحقق منه، مع الأخطاء الحقيقية التي يكشفها وتلك التي لا يكشفها.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, DevOps والتشغيل, DevOps وCI/CD, الاستضافة الذاتية, Gitea

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

وفي [ما هو DevOps؟](https://arabroot.io/articles/%D9%85%D8%A7-%D9%87%D9%88-devops-%D8%A7%D9%84%D8%AB%D9%82%D8%A7%D9%81%D8%A9-%D9%88%D8%A7%D9%84%D9%85%D9%85%D8%A7%D8%B1%D8%B3%D8%A7%D8%AA-%D9%82%D8%A8%D9%84-%D8%A7%D9%84%D8%A7%D8%AF%D9%88%D8%A7%D8%AA/) رأينا نشراً يدوياً نسي سيرفراً واحداً، ثم سكربتاً ينشر من وسم Git ويتحقق من كل سيرفر، وقلنا إن ما ينقصه أن يعمل وحده مع كل تغيير دون أن يتذكر أحد تشغيله، وأن يبني ويختبر قبل أن ينشر. وهذا بالضبط ما يسمى خط CI/CD. وفي هذا المقال نشرح المفهوم من البداية، ثم نبني خطاً حقيقياً على جهازك بـ Gitea وGitea Runner، يختبر كل Push، وينشر إلى بيئة staging عندما تنجح الاختبارات على `main`، ويتحقق من أن الخدمة تعمل بعد النشر. وقبل أن تبدأ تأكد أنك تقرأ ملفات YAML بثقة، فخط CI ملف YAML قبل كل شيء، وقد شرحناها في [YAML للمبتدئين](https://arabroot.io/articles/yaml-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86-%D8%A7%D9%84%D9%82%D9%88%D8%A7%D8%B9%D8%AF-%D9%88%D8%A7%D9%84%D8%A7%D8%AE%D8%B7%D8%A7%D8%A1-%D8%A7%D9%84%D8%B4%D8%A7%D8%A6%D8%B9%D8%A9-%D9%81%D9%8A-%D9%85%D9%84%D9%81%D8%A7%D8%AA-%D8%A7%D9%84%D8%A7%D8%B9%D8%AF%D8%A7%D8%AF/). وسوف نناقش في هذا المقال ما يلي:

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

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

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

وجاءت الفكرة المعاكسة من ممارسات البرمجة القصوى Extreme Programming في التسعينيات، كما يذكر Martin Fowler في مقاله المرجعي [Continuous Integration](https://martinfowler.com/articles/continuousIntegration.html?ref=arabroot.io): إذا كان التكامل مؤلماً فافعله أكثر، أي أن يدمج كل مطور عمله في الفرع الرئيسي Mainline مرة في اليوم على الأقل، وأن يتحقق نظام آلي بعد كل دمج أن المشروع ما زال يبنى وتنجح اختباراته. فبدلاً من مرحلة تكامل كبيرة كل شهر تصبح عندك مئات التكاملات الصغيرة، وكل واحدة منها إذا فشلت فأنت تعرف بالضبط أي تغيير سببها، لأنه التغيير الوحيد منذ آخر نجاح.

ولاحظ أن التكامل المستمر في أصله ممارسة وليس أداة، فالأداة التي تبني وتختبر بعد كل دفع، ويسميها الناس أحياناً «سيرفر CI»، لا تفيد إذا بقي كل مطور على فرعه أسبوعين، لأنك تختبر باستمرار شيئاً لا يتكامل. ولذلك ترتبط هذه الممارسة مباشرة بالفروع القصيرة التي شرحناها في [التطوير على الفرع الرئيسي Trunk-Based](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1-%D8%B9%D9%84%D9%89-%D8%A7%D9%84%D9%81%D8%B1%D8%B9-%D8%A7%D9%84%D8%B1%D8%A6%D9%8A%D8%B3%D9%8A-trunk-based/)، وبطلبات الدمج الصغيرة التي شرحناها في [مراجعة الكود Code Review](https://arabroot.io/articles/%D9%85%D8%B1%D8%A7%D8%AC%D8%B9%D8%A9-%D8%A7%D9%84%D9%83%D9%88%D8%AF-code-review-%D9%83%D9%8A%D9%81-%D8%AA%D8%B1%D8%A7%D8%AC%D8%B9-pull-request-%D8%A8%D9%81%D8%A7%D8%A6%D8%AF%D8%A9/).

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

يجمع مقال Fowler وصفحة [التكامل المستمر في أبحاث DORA](https://dora.dev/capabilities/continuous-integration/?ref=arabroot.io) مجموعة قواعد، وأهمها لفريق يبدأ:

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

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

![أربعة صناديق تكبر من اليمين إلى اليسار على محور من بعد الكتابة مباشرة إلى بعد أيام أو أسابيع: على جهازك أخضر صغير ثوان تصلحه وحدك، ثم في خط CI أزرق دقائق ما زلت تتذكر ما كتبت، ثم في Staging برتقالي ساعات فريق الاختبار ينتظر، ثم في الإنتاج أحمر كبير عملاء متأثرون تراجع عاجل وتحقيق وثقة تضيع، وتحته خط CI/CD ينقل اكتشاف أغلب الأخطاء من اليسار إلى اليمين](https://arabroot.io/content/images/2026/11/ci-cd-basics-07-feedback-cost.webp)

الخطأ نفسه، وأربعة أثمان مختلفة بحسب المكان الذي يكتشف فيه

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

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

![صف من ست دوائر من اليمين: Push ثم بناء ثم اختبار ثم نسخة جاهزة خضراء ثم Staging بنفسجية ثم الإنتاج Production حمراء، وتحتها ثلاثة أشرطة: التكامل المستمر Continuous Integration يغطي من Push إلى نسخة جاهزة، كل Push يدمج ويبنى ويختبر آلياً خلال دقائق، ثم التسليم المستمر Continuous Delivery يغطي حتى Staging مع أيقونة أشخاص، كل نسخة نجحت جاهزة للإنتاج والنشر إليه بزر يضغطه إنسان، ثم النشر المستمر Continuous Deployment يغطي حتى الإنتاج، كل نسخة نجحت تصل إلى الإنتاج تلقائياً دون أي تدخل، وفي الأعلى الحرفان CD يستخدمان للمعنيين فاسأل دائماً من يضغط زر الإنتاج](https://arabroot.io/content/images/2026/11/ci-cd-basics-01-ci-cd-terms.webp)

الفرق بين المعنيين في سؤال واحد: من يضغط زر الإنتاج؟

- **التسليم المستمر Continuous Delivery:** يعرفه Jez Humble في [موقع Continuous Delivery](https://continuousdelivery.com/?ref=arabroot.io) بأنه القدرة على إيصال التغييرات من كل الأنواع إلى الإنتاج أو إلى المستخدمين بأمان وسرعة وبطريقة يمكن الاستمرار عليها. وعملياً يعني أن كل نسخة نجحت في الخط جاهزة للنشر في أي لحظة، وأن النشر إلى الإنتاج قرار عمل يتخذه إنسان بزر، وليس مشروعاً هندسياً يحتاج أسبوعاً.
- **النشر المستمر Continuous Deployment:** خطوة أبعد، فكل نسخة نجحت تذهب إلى الإنتاج تلقائياً دون أن يضغط أحد شيئاً. وهذا يحتاج إلى ثقة كبيرة في الاختبارات والمراقبة والتراجع الآلي، ولا يناسب كل منتج.

وقد يتساءل البعض: أيهما يجب أن أطبق؟ والإجابة أن أغلب الفرق تبدأ بالتسليم المستمر، أي نشر آلي إلى staging مع كل دمج، ونشر إلى الإنتاج بزر، ثم تقرر بعد أن ترى ثبات الخط هل تحتاج إلى أكثر. وتشرح صفحة [التسليم المستمر في DORA](https://dora.dev/capabilities/continuous-delivery/?ref=arabroot.io) أن المقصود أن يكون النشر روتيناً منخفض المخاطر يمكن فعله في أي وقت، وليس حدثاً نادراً، وقد شرحنا البيئات dev وstaging والإنتاج وكيف تنقل النسخة بينها في [البيئات ومعاينة الميزات وGitOps](https://arabroot.io/articles/%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A7%D8%AA-%D9%88%D9%85%D8%B9%D8%A7%D9%8A%D9%86%D8%A9-%D8%A7%D9%84%D9%85%D9%8A%D8%B2%D8%A7%D8%AA-%D9%88-gitops-%D9%84%D9%84%D9%81%D8%B1%D9%82/).

## مكونات خط 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 تعمل فيه الخطوات، ويحدده الوسم Label                | python وdocker                |
| الاعتماد Dependency | مهمة لا تبدأ إلا بعد نجاح غيرها                               | needs: test                   |
| الأسرار Secrets     | كلمات المرور والمفاتيح التي يحتاجها الخط دون أن تكون في الكود | لم نحتجها في التجربة المحلية  |

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

والأحداث ليست الدفع وطلبات الدمج فقط، فأغلب الأدوات تقبل أحداثاً أخرى تفيدك لاحقاً: `schedule` لتشغيل الخط في وقت محدد مثل كل ليلة، وهو مناسب لاختبارات طويلة أو فحص الثغرات في الاعتماديات الذي قد يجد مشكلة جديدة في كود لم يتغير، و`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](https://arabroot.io/articles/%D9%85%D8%A7-%D9%87%D9%88-devops-%D8%A7%D9%84%D8%AB%D9%82%D8%A7%D9%81%D8%A9-%D9%88%D8%A7%D9%84%D9%85%D9%85%D8%A7%D8%B1%D8%B3%D8%A7%D8%AA-%D9%82%D8%A8%D9%84-%D8%A7%D9%84%D8%A7%D8%AF%D9%88%D8%A7%D8%AA/#lab-script)، ثم ضعه داخل خط عندما يستقر، فالسكربت الذي يعمل يدوياً سوف يعمل في الخط، أما الذي لا تفهمه يدوياً فسوف يفشل في الخط بطريقة أصعب في الفهم.

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

سوف نبني على جهازك خطاً لخدمة حاسبة الفواتير التي استخدمناها في [مقال مراجعة الكود](https://arabroot.io/articles/%D9%85%D8%B1%D8%A7%D8%AC%D8%B9%D8%A9-%D8%A7%D9%84%D9%83%D9%88%D8%AF-code-review-%D9%83%D9%8A%D9%81-%D8%AA%D8%B1%D8%A7%D8%AC%D8%B9-pull-request-%D8%A8%D9%81%D8%A7%D8%A6%D8%AF%D8%A9/)، وقد أضفنا إليها سيرفر 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](https://arabroot.io/content/images/2026/11/ci-cd-basics-02-lab-map.webp)

المكونات الأربعة للمختبر، والأرقام بترتيب ما يحدث بعد كل دفع

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

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

```bash
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 dev1@example.com --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](https://docs.gitea.com/runner/?ref=arabroot.io). وهذه هي النسخة النهائية بعد المشكلتين اللتين سوف نشرحهما بعد قليل:

```yaml
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
```

```bash
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
```

```text
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](https://arabroot.io/articles/gitea-actions-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-ci-cd-%D8%B9%D9%84%D9%89-%D8%AE%D8%A7%D8%AF%D9%85%D9%83/) النوع المعزول 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](https://arabroot.io/content/images/2026/11/ci-cd-basics-03-runner-idle.webp)

الـ Runner متصل وينتظر المهام، ووسماه هما ما يكتبه الخط في runs-on

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

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

```dockerfile
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`:

```yaml
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 مهمة يحدث ما رأيناه في أسطر التحضير في السجل، وقد حذفناها من المخرج السابق للاختصار:

```text
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`، وهذا ما ظهر في سجلها:

```text
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:

```dockerfile
# 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/*
```

```bash
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 لم نجده، وكانت آخر أسطر السجل تشرح السبب:

```text
{"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](https://gitea.com/gitea/runner/releases/tag/v5.0.0?ref=arabroot.io) وجدنا الإعداد الذي يتحكم بذلك، وقد أضيف في [طلب الدمج 1275](https://gitea.com/gitea/runner/pulls/1275?ref=arabroot.io): `container.sweep: false` يحتفظ بالخدمات التي تنشرها المهام على Docker الخاص بالـ Runner. فأضفناه وأعدنا التشغيل، فبقي الـ Container:

```text
dvb-staging invoice-tool:d9838fd Up 9 seconds
```

وهذه المشكلة تكشف شيئاً أهم من الإعداد نفسه: النشر إلى نفس Docker الذي ينفذ المهام طريقة مختبر، فهو يخلط بين جهاز البناء وجهاز التشغيل. وفي الواقع يكون Runner على جهاز، وبيئة staging على سيرفر آخر، والنشر يتم بطلب إلى ذلك السيرفر، مثل webhook أو SSH أو تحديث مستودع إعداد يراقبه أداة GitOps، كما في [طرق نشر التطبيقات](https://arabroot.io/articles/%D8%B7%D8%B1%D9%82-%D9%86%D8%B4%D8%B1-%D8%A7%D9%84%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-%D9%85%D9%86-ftp-%D8%A7%D9%84%D9%89-gitops/). والإعداد `sweep: false` مناسب هنا لأننا نريد أن نرى الفكرة كاملة على جهاز واحد.

### أول خط أخضر Green Pipeline

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

```text
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، وتشغيلها، والتحقق منها:

```text
#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`، كأن شخصاً أخطأ في رقم:

```bash
sed -i "s/^VAT = 0.15/VAT = 0.05/" invoice.py
git commit -qam "Change VAT constant" && git push
```

```text
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](https://arabroot.io/content/images/2026/11/ci-cd-basics-05-test-failed.webp)

الاختبار فشل، والنشر لم يبدأ أصلاً

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

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

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

```bash
git revert --no-edit HEAD
git push
```

```text
[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`:

```text
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\. والاختبارات لا تشغل السيرفر، وإنما تختبر دالة الحساب، فنجحت كلها، ثم بدأ النشر:

```text
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 بعد الفشل:

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

بيئة staging كانت متوقفة عن الخدمة، والـ Container يعمل ولكن على منفذ آخر. ولو كانت هذه بيئة الإنتاج لكان العملاء يرون خطأ حتى يتراجع أحد. والدرس أن التحقق بعد النشر يخبرك بالمشكلة ولكنه لا يمنعها، والذي يمنعها هو ترتيب مختلف: شغل الإصدار الجديد بجانب القديم، وتحقق منه، ثم حول الحركة إليه، واحذف القديم في الآخر، وهذه فكرة النشر الأزرق والأخضر Blue-Green التي جربناها خلف Nginx في [طرق نشر التطبيقات](https://arabroot.io/articles/%D8%B7%D8%B1%D9%82-%D9%86%D8%B4%D8%B1-%D8%A7%D9%84%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-%D9%85%D9%86-ftp-%D8%A7%D9%84%D9%89-gitops/#lab-blue-green). والدرس الثاني أن الاختبارات التي لا تشغل التطبيق كما يشغل في الإنتاج لا تمسك أخطاء التشغيل، ولذلك تضيف الفرق اختبارات تكامل Integration Tests تشغل الـ Container فعلاً قبل النشر، كما في [أنواع الاختبارات للمبتدئين](https://arabroot.io/articles/%D8%A7%D9%86%D9%88%D8%A7%D8%B9-%D8%A7%D9%84%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1%D8%A7%D8%AA-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86-unit-%D9%88-integration-%D9%88-e2e/).

وأصلحنا الموقف بنفس الطريقة: `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](https://arabroot.io/content/images/2026/11/ci-cd-basics-04-runs-list.webp)

ستة تشغيلات: خطآن أمسكهما الخط، وتراجعان أعادا 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، كلها بعلامة خضراء](https://arabroot.io/content/images/2026/11/ci-cd-basics-06-deploy-success.webp)

مهمة النشر بخطواتها الأربع، وكل خطوة لها سجلها الخاص

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

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

```text
04ed0b1 176MB
d9838fd 176MB
```

فالتراجع السريع هو أن تشغل Image الإصدار الأخير الذي تعرف أنه سليم، دون أي بناء، لأنها نفس الـ Image التي اختبرت ونشرت من قبل، ثم تصلح المشكلة في الكود وتتركها تمر بالخط بهدوء. ولاحظ أن الحجم 176MB لكل Image لا يعني أن كل واحدة تأخذ هذه المساحة على القرص، لأن الطبقات Layers المشتركة مثل Python تحفظ مرة واحدة، ولكن مع الوقت تتراكم الإصدارات، فاحتفظ بآخر عشرة مثلاً واحذف الأقدم بسياسة تنظيف في الـ Registry. وقد شرحنا الـ Registry ورفع الـ Images إليه من الخط في [أول workflow يبني Image ويرفعها](https://arabroot.io/articles/gitea-actions-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-ci-cd-%D8%B9%D9%84%D9%89-%D8%AE%D8%A7%D8%AF%D9%85%D9%83/#workflow).

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

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

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

### التنظيف Cleanup

```bash
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، بحسب [المراجعة الأولية التي نشرتها الشركة](https://www.crowdstrike.com/en-us/blog/falcon-content-update-preliminary-post-incident-report/?ref=arabroot.io). وذكرت المراجعة أن أداة التحقق من المحتوى Content Validator كان فيها خطأ برمجي جعل أحد قوالب التحديث يمر من الفحص رغم أن بياناته فيها مشكلة، وأن هذا النوع من التحديثات كان يرسل إلى كل الأجهزة دفعة واحدة. ومن أهم ما التزمت به الشركة بعد الحادثة أن تنشر هذا المحتوى بشكل متدرج Staggered Deployment، يبدأ بنشر تجريبي على مجموعة صغيرة Canary ثم يتوسع إلى أجزاء أكبر. والدرس أن الفحص الآلي نفسه قد يخطئ، وأن النشر المتدرج هو ما يجعل الخطأ الذي يفلت منه يصيب قليلاً من المستخدمين بدلاً من كلهم.

وفي فريق صغير لا تحتاج إلى نظام معقد لتطبيق الفكرة نفسها، فبيئة staging هي أول مرحلة، ثم سيرفر واحد من سيرفرات الإنتاج قبل الباقي، أو Feature Flag تفتح الميزة لنسبة صغيرة من المستخدمين كما شرحنا في [مفهوم Feature Flags والإطلاق التدريجي](https://arabroot.io/articles/%D9%85%D9%81%D9%87%D9%88%D9%85-feature-flags-%D9%88%D8%A7%D9%84%D8%A7%D8%B7%D9%84%D8%A7%D9%82-%D8%A7%D9%84%D8%AA%D8%AF%D8%B1%D9%8A%D8%AC%D9%8A-gradual-rollout/)، مع مراقبة تقول لك خلال دقائق هل زادت الأخطاء.

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

- **سريع:** الخط الذي يستغرق ساعة لا يستخدمه أحد كما يجب، فالمطورون يجمعون تغييرات أكثر في كل دفع لكي ينتظروا مرات أقل، فتعود الدفعات الكبيرة. وابدأ بالأسرع: الفحص والاختبارات السريعة أولاً، والبطيئة بعدها أو بالتوازي.
- **موثوق:** الاختبار الذي يفشل أحياناً دون سبب، أي الاختبار المتقلب Flaky Test، يعلم الفريق أن يضغط إعادة التشغيل دون أن يقرأ، فإذا جاء فشل حقيقي ضغطوا الزر نفسه، فأصلحه أو احذفه فوراً.
- **يبني مرة واحدة:** الـ Image التي اختبرت في staging هي نفسها التي تذهب إلى الإنتاج بنفس الوسم، ولا يعاد البناء لكل بيئة، والسبب أن البناء الثاني قد يسحب مكتبة بإصدار مختلف، وقد شرحنا ذلك في [ابن ال Docker Image مرة واحدة](https://arabroot.io/articles/%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A7%D8%AA-%D9%88%D9%85%D8%B9%D8%A7%D9%8A%D9%86%D8%A9-%D8%A7%D9%84%D9%85%D9%8A%D8%B2%D8%A7%D8%AA-%D9%88-gitops-%D9%84%D9%84%D9%81%D8%B1%D9%82/#build-once).
- **يحفظ الأسرار خارج الملف:** كلمات المرور والرموز في أسرار المستودع Secrets وليس في ملف الخط، والخط يخفيها في السجلات، كما في [الأسرار والمتغيرات في Gitea Actions](https://arabroot.io/articles/gitea-actions-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-ci-cd-%D8%B9%D9%84%D9%89-%D8%AE%D8%A7%D8%AF%D9%85%D9%83/#secrets).
- **يعمل على Runner معزول:** الـ Runner ينفذ كوداً من المستودع، فمن يملك صلاحية الدفع يستطيع أن يشغل أي أمر عليه، ولذلك لا تشغله على سيرفر الإنتاج نفسه، ولا تمرر له مقبس Docker على سيرفر فيه خدمات أخرى، وثبت كل Action خارجية على هاش Commit.
- **يتحقق بعد النشر:** رد الخدمة بالإصدار المتوقع، وليس فقط نجاح أمر النسخ أو التشغيل، كما رأيت في المختبر.

وإذا أردت أن تبني خطاً كاملاً بهذه الصفات، بفحص الاعتماديات والأسرار وتوقيع الـ Images، فقد شرحنا ذلك في [خط CI/CD آمن من البداية للنهاية](https://arabroot.io/articles/%D8%AE%D8%B7-ci-cd-%D8%A7%D9%85%D9%86-%D9%85%D9%86-%D8%A7%D9%84%D8%A8%D8%AF%D8%A7%D9%8A%D8%A9-%D9%84%D9%84%D9%86%D9%87%D8%A7%D9%8A%D8%A9/).

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

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

وراقب الخط نفسه كما تراقب أي خدمة: كم يستغرق، وكم مرة يفشل، وأي اختبار يفشل أكثر من غيره. فالخط الذي كان يأخذ خمس دقائق وأصبح يأخذ عشرين لم يتغير فجأة، وإنما زاد دقيقة كل أسبوع دون أن ينتبه أحد، حتى بدأ المطورون يدفعون أقل لكي ينتظروا أقل. وإذا رأيت أن الناس يضغطون إعادة التشغيل كثيراً فهذا مؤشر على اختبار متقلب يجب إصلاحه، وقد خصصنا لتشغيل الاختبارات في الخط وسرعتها وتقلبها مقالاً في [مرحلة ضمان الجودة QA](https://arabroot.io/start/#stage-qa).

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

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

| الأداة         | مكان ملف الخط            | متى تناسبك                                                                                                                                                    |
| -------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Gitea Actions  | .gitea/workflows/\*.yml  | عندما يكون Gitea هو مستودعك، وصيغته قريبة جداً من GitHub Actions، والفروق في [صفحة المقارنة](https://docs.gitea.com/usage/actions/comparison?ref=arabroot.io) |
| GitHub Actions | .github/workflows/\*.yml | عندما يكون الكود على GitHub، ومعه سوق كبير من Actions الجاهزة                                                                                                 |
| GitLab CI      | .gitlab-ci.yml           | عندما يكون الكود على GitLab، والخط فيه جزء من المنصة نفسها                                                                                                    |
| Jenkins        | Jenkinsfile              | عندما تحتاج مرونة كبيرة وإضافات كثيرة وتقبل إدارة سيرفر خاص به                                                                                                |
| Woodpecker CI  | .woodpecker/\*.yml       | عندما تريد أداة خفيفة مستقلة تعمل مع Gitea وغيره                                                                                                              |

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

## أخطاء شائعة 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

[![](https://arabroot.io/content/images/2026/10/gitea-actions-cover-cover-2.webp)دليلGitea Actions: تشغيل CI/CD وبناء Docker Images على سيرفركاجعل سيرفرك يختبر الكود ويبني Docker Images تلقائياً مع كل push، دون أن يخرج كودك أو أسرارك إلى خدمة CI خارجية.](https://arabroot.io/articles/gitea-actions-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-ci-cd-%D8%B9%D9%84%D9%89-%D8%AE%D8%A7%D8%AF%D9%85%D9%83/)[![](https://arabroot.io/content/images/2026/10/environments-gitops-cover-cover.webp)دليلمن الفرع إلى الإنتاج: البيئات وGitOps للفرقكيف يختبر فريقك كل ميزة وحدها ويعرضها على العميل دون أن تصل ميزة غير جاهزة إلى الإنتاج.](https://arabroot.io/articles/%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A7%D8%AA-%D9%88%D9%85%D8%B9%D8%A7%D9%8A%D9%86%D8%A9-%D8%A7%D9%84%D9%85%D9%8A%D8%B2%D8%A7%D8%AA-%D9%88-gitops-%D9%84%D9%84%D9%81%D8%B1%D9%82/)[![](https://arabroot.io/content/images/2026/10/secure-pipeline-cover-cover.webp)دليلخط CI/CD آمن من البداية للنهاية على Gitea Actionsكيف تجمع فحوص الأمن في خط واحد لا يستطيع طلب الدمج تجاوزه، ثم ترسل إلى الإنتاج نفس ال Docker Image الموقعة التي فحصتها.](https://arabroot.io/articles/%D8%AE%D8%B7-ci-cd-%D8%A7%D9%85%D9%86-%D9%85%D9%86-%D8%A7%D9%84%D8%A8%D8%AF%D8%A7%D9%8A%D8%A9-%D9%84%D9%84%D9%86%D9%87%D8%A7%D9%8A%D8%A9/)[![](https://arabroot.io/content/images/2026/10/deployment-history-cover-cover.webp)دليلطرق نشر التطبيقات من FTP إلى GitOps، وأين تقف أنتكيف تطور نشر التطبيقات عبر السنين، وما الذي يتعطل في كل طريقة، وكيف تعرف أين تقف وما خطوتك التالية.](https://arabroot.io/articles/%D8%B7%D8%B1%D9%82-%D9%86%D8%B4%D8%B1-%D8%A7%D9%84%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-%D9%85%D9%86-ftp-%D8%A7%D9%84%D9%89-gitops/)

إذا أردت أن تنقل هذا الخط إلى سيرفر فريقك بـ Runner معزول وRegistry للـ Images فاتبع [Gitea Actions: تشغيل CI/CD على سيرفرك](https://arabroot.io/articles/gitea-actions-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-ci-cd-%D8%B9%D9%84%D9%89-%D8%AE%D8%A7%D8%AF%D9%85%D9%83/)، وإذا أردت أن ترى كيف تنتقل النسخة نفسها من staging إلى الإنتاج بcommit في مستودع إعداد فاقرأ [البيئات ومعاينة الميزات وGitOps](https://arabroot.io/articles/%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A7%D8%AA-%D9%88%D9%85%D8%B9%D8%A7%D9%8A%D9%86%D8%A9-%D8%A7%D9%84%D9%85%D9%8A%D8%B2%D8%A7%D8%AA-%D9%88-gitops-%D9%84%D9%84%D9%81%D8%B1%D9%82/).

## الخلاصة 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.