إذا كنت قد نسخت ملف docker-compose.yml من دليل على الإنترنت، ثم عدلت سطراً واحداً فيه، فظهرت لك رسالة مثل services.ports must be a mapping ولم تفهم أي قاموس تقصد، أو دفعت ملف workflow إلى المستودع فلم يعمل خط CI ولم يقل لك أحد لماذا، فأنت تعرف المشكلة التي يدور حولها هذا المقال. فملفات YAML تبدو بسيطة جداً حتى تخطئ فيها، فهي لا تحتوي على أقواس ولا فواصل كثيرة، وإنما أسماء ونقطتان ومسافات، ولذلك يظن الناس أنهم يفهمونها من أول نظرة، ثم يكتشفون أن مسافة واحدة نقلت مفتاحاً من مكان إلى آخر، أو أن رمز دولة تحول إلى قيمة منطقية.
وفي مرحلة DevOps والنشر المستمر سوف تقرأ ملفات YAML وتكتبها كل يوم، فخطوط CI/CD في Gitea Actions وGitHub Actions وGitLab CI مكتوبة بها، وكذلك ملفات Docker Compose وKubernetes وAnsible، ولذلك وضعنا هذا المقال قبل مقال CI/CD للمبتدئين، حتى تقرأ ملف الخط وأنت تفهم كل سطر فيه. وكل نتيجة في هذا المقال خرجت من تجربة حقيقية بـ PyYAML وyamllint وDocker Compose وGitea، وسوف ترى أن بعضها مفاجئ حتى لمن يستخدم YAML منذ سنوات. وسوف نناقش في هذا المقال ما يلي:
- ما هو YAML ومن أين جاء، وأين يستخدم، وكيف يختلف عن JSON وTOML.
- القواعد الأساسية: القاموس Mapping والقائمة Sequence والقيم Scalars، والمسافات، والنصوص متعددة الأسطر.
- الكتابة الضمنية للأنواع Implicit Typing: لماذا يقرأ المحلل
NOكقيمة منطقية و22:22كرقم 1342. - أخطاء المسافات، والمفاتيح المكررة، والمراسي Anchors التي تستبدل بدلاً من أن تدمج.
- الملفات متعددة المستندات، وخطر تحميل YAML من مصدر لا تثق به.
- الفحص قبل الدفع بـ yamllint وdocker compose config، وماذا يحدث عندما تدفع workflow فيه خطأ إلى Gitea.
لماذا يستخدم الجميع YAML؟ What is YAML
YAML لغة لكتابة البيانات بشكل يقرؤه الإنسان، أي أنها طريقة لكتابة القواميس والقوائم والقيم في ملف نصي، مثل JSON تماماً من حيث ما تمثله، ولكن بشكل أقرب إلى الملاحظات التي تكتبها بيدك. واسمها اختصار تكراري هو «YAML Ain't Markup Language»، أي أنها ليست لغة ترميز مثل HTML، وإنما لغة بيانات. وقد نشرت مواصفة YAML 1.1 سنة 2005، ثم YAML 1.2 سنة 2009 وكان هدفها الأساسي كما تقول المواصفة الحالية 1.2.2 أن تجعل YAML مجموعة شاملة لـ JSON بالكامل Superset، أي أن أي ملف JSON صحيح هو ملف YAML صحيح أيضاً. وهذا الفرق بين الإصدارين ليس تفصيلاً تاريخياً، وإنما سبب أغلب المفاجآت التي سوف نراها، لأن أدوات كثيرة ما زالت تقرأ YAML بقواعد 1.1.
وقد يتساءل البعض: لماذا اختارت أدوات DevOps لغة YAML بدلاً من JSON؟ والإجابة أن ملفات الإعداد يكتبها البشر ويقرؤونها ويراجعونها في طلبات الدمج أكثر مما تكتبها البرامج، وYAML تسمح بالتعليقات وهي ممنوعة في JSON، ولا تحتاج إلى علامات تنصيص حول كل نص ولا إلى أقواس وفواصل في نهاية كل سطر، فيصبح الملف أقصر وأوضح عند المراجعة. والصورة التالية تبين أين سوف تقابلها:

لاحظ الجملة في أعلى الصورة، فهي فكرة هذا المقال كله: الملف نص، والأداة لا ترى النص وإنما ما يحوله إليه المحلل Parser، أي البرنامج الذي يقرأ الملف ويحوله إلى قواميس وقوائم وقيم داخل الذاكرة. ومحلل Docker Compose مكتوب بلغة Go، ومحلل Ansible هو PyYAML في Python، ومحلل Kubernetes مكتوب بـ Go أيضاً، وكل منها قد يتبع إصداراً مختلفاً من المواصفة.
تجهيز المختبر Lab Setup
سوف نستخدم Container من Python 3.13 نثبت فيه PyYAML، وهو المحلل الأشهر في Python، والأداة yamllint التي تفحص ملفات YAML، ونربط به مجلداً فيه ملفات التجربة. ومعه سكربت صغير اسمه show.py يقرأ أي ملف YAML ويطبع لكل مفتاح القيمة التي وصلت إلى البرنامج ونوعها:
docker run -d --name dvb-yaml -v "$PWD:/lab" -w /lab python:3.13-slim sleep infinity
docker exec dvb-yaml pip install -q PyYAML==6.0.3 yamllint==1.38.0
docker exec dvb-yaml sh -c 'python --version; yamllint --version'Python 3.13.18
yamllint 1.38.0# Print what a YAML file becomes after parsing: the Python value and its type.
import sys, yaml
for path in sys.argv[1:]:
with open(path, encoding="utf-8") as f:
data = yaml.safe_load(f)
print(f"== {path}")
if isinstance(data, dict):
for k, v in data.items():
print(f"{k!r:17} -> {v!r:40} {type(v).__name__}")
else:
print(repr(data))ولاحظ أننا نستخدم yaml.safe_load وليس yaml.load، وسوف نشرح السبب في قسم الأمان.
القواعد الأساسية Syntax
كل ملف YAML يتكون من ثلاثة أنواع فقط من البيانات، وكل ما تراه في ملفات Compose وKubernetes وCI هو تركيب من هذه الثلاثة داخل بعضها، والصورة التالية تبينها على ملف صغير:

- القاموس Mapping: مفاتيح وقيم، كل سطر فيه مفتاح ثم نقطتان ثم مسافة ثم القيمة، مثل
replicas: 3، ويقابل الكائن Object في JSON والقاموس Dictionary في Python. - القائمة Sequence: عناصر مرتبة، كل عنصر في سطر يبدأ بشرطة ومسافة
- web، أو بين قوسين مربعين في سطر واحد[web, billing]، وتقابل المصفوفة Array في JSON. - القيمة المفردة Scalar: نص أو رقم أو قيمة منطقية أو
null، وهي أوراق الشجرة التي لا يتفرع منها شيء.
ولنرى كيف يقرأ المحلل ملفاً عادياً فيه كل هذه الأنواع:
name: invoice-tool
replicas: 3
vat: 0.15
debug: false
owner: null
tags: [web, billing]
db:
host: db
port: 5432docker exec dvb-yaml python show.py 01-types.yaml== 01-types.yaml
'name' -> 'invoice-tool' str
'replicas' -> 3 int
'vat' -> 0.15 float
'debug' -> False bool
'owner' -> None NoneType
'tags' -> ['web', 'billing'] list
'db' -> {'host': 'db', 'port': 5432} dictفي المخرج أعلاه لاحظ التالي:
- لم نكتب أي علامة تنصيص، ومع ذلك عرف المحلل أن
invoice-toolنص، و3رقم صحيح، و0.15رقم عشري، وfalseقيمة منطقية، وnullقيمة فارغة. وهذا ما يسمى الكتابة الضمنية للأنواع Implicit Typing، أي أن المحلل يخمن النوع من شكل القيمة، وهي مريحة جداً، وهي أيضاً مصدر أخطر المفاجآت كما سوف ترى. - المفتاح
dbقيمته قاموس كامل، والذي جعلhostوportداخله وليس بجانبه هو المسافتان في أول السطر فقط، فلا توجد أقواس ولا أي علامة أخرى. - القائمة المكتوبة بين قوسين مربعين
[web, billing]هي نفسها القائمة المكتوبة بالشرطات في سطرين، والاختيار بينهما للقراءة فقط.
ماذا يفعل المحلل من الداخل؟ How a Parser Works
لكي تقرأ رسائل الخطأ في هذا المقال وتعرف من أين جاءت، يفيدك أن تعرف أن المحلل لا يحول النص إلى بيانات في خطوة واحدة، وإنما في مراحل متتالية تصفها المواصفة في فصل المعالجة، ويتبعها PyYAML بأسماء واضحة:
- المسح Scanning: يقرأ النص حرفاً حرفاً ويقسمه إلى رموز Tokens: مفتاح، ونقطتان، وبداية قائمة، ونص، ونهاية مستوى إزاحة. وفي هذه المرحلة تظهر أخطاء الحروف التي لا يعرفها، مثل Tab و
@، ولذلك جاءت رسائلها باسمScannerError. - التحليل Parsing: يرتب الرموز في أحداث Events مثل «بدأ قاموس» و«انتهت قائمة»، وهنا تظهر أخطاء البنية مثل خطوة في غير مستواها، وهي رسالة Gitea التي رأيتها
error in parser. - التركيب Composing: يبني من الأحداث شجرة من العقد Nodes لكل مستند، ويربط الأسماء المستعارة بمراسيها، وهنا ظهر خطأ الملف متعدد المستندات
ComposerErrorلأن الدالة طلبت مستنداً واحداً. - البناء Constructing: يحول كل عقدة إلى قيمة في لغتك: نص أو رقم أو قائمة أو قاموس أو كائن، وهنا يقرر المحلل نوع كل قيمة دون تنصيص، وهنا أيضاً رفضت
safe_loadالوسم الخطير برسالةConstructorError.
والمرحلة الأخيرة هي التي تختلف فيها المحللات أكثر من غيرها، والسبب أن المواصفة 1.2 تعرف أكثر من مخطط Schema لتحديد الأنواع: مخطط Failsafe الذي لا يعرف إلا النصوص والقوائم والقواميس، ومخطط JSON الذي يقبل الأنواع بشكل JSON الصارم فقط، والمخطط الأساسي Core الذي يقبل أشكالاً أكثر مرونة مثل True بحرف كبير. ويختار كل محلل مخططه، وPyYAML ما زال يستخدم قواعد YAML 1.1 الأقدم والأوسع. وهذا يعني أن الملف نفسه يمر بالمراحل الثلاث الأولى في كل المحللات بالنتيجة نفسها تقريباً، ثم يتفرق في المرحلة الرابعة، فإذا رأيت أداتين تختلفان في فهم قيمة فابحث عن السبب في الأنواع وليس في المسافات.
المسافات هي البنية Indentation
القاعدة الأهم في YAML أن المسافات في بداية السطر هي ما يحدد من يتبع من، وفيها ثلاثة أشياء يجب أن تتذكرها:
- المسافات فقط، ولا يسمح بمفتاح Tab للإزاحة إطلاقاً، كما تنص المواصفة، والسبب أن المحررات تعرض Tab بأعراض مختلفة، فيبدو الملف صحيحاً عندك وخاطئاً عند غيرك.
- عدد المسافات ليس مهماً بحد ذاته، فاثنتان أو أربع مقبولتان، والمهم أن تكون كل العناصر في المستوى نفسه بالإزاحة نفسها تماماً، والعرف الشائع في ملفات DevOps مسافتان.
- عناصر القائمة تحت مفتاح يمكن أن تبدأ بنفس إزاحة المفتاح أو بإزاحة أكبر، وكلاهما صحيح، ولكن اختر شكلاً واحداً في المشروع.
وأفضل ما تفعله أن تضبط محررك ليحول Tab إلى مسافات في ملفات .yaml و.yml، وأن تفعل عرض المسافات المخفية، فأغلب محررات الكود مثل VS Code تفعل ذلك تلقائياً عندما تعرف نوع الملف، وقد شرحنا إعداد المحرر في بيئة البرمجة للمبتدئين.
التعليقات Comments
كل ما بعد العلامة # في السطر تعليق يتجاهله المحلل، بشرط أن تسبقها مسافة إذا جاءت بعد قيمة. وهذه الميزة وحدها سبب كاف لتفضيل YAML على JSON في ملفات الإعداد، فاكتب في التعليق لماذا اخترت القيمة وليس ما هي، مثل replicas: 3 # two are not enough during deploys، فمن يغيرها بعد سنة يعرف ما الذي يخاطر به. ولكن تذكر أن التعليقات تضيع عندما يقرأ برنامج الملف ثم يكتبه من جديد، كما سوف ترى في مخرج docker compose config.
النصوص متعددة الأسطر Multi-line Strings
في ملفات CI تكتب كثيراً أوامر من عدة أسطر، وفي Kubernetes ملفات إعداد كاملة داخل قيمة واحدة، ولذلك يوفر YAML طريقتين لكتابة النص على عدة أسطر، والفرق بينهما في ما يحدث لنهايات الأسطر:
literal: |
line one
line two
folded: >
a long sentence
split over lines
stripped: |-
no final newline== 03-strings.yaml
'literal' -> 'line one\nline two\n' str
'folded' -> 'a long sentence split over lines\n' str
'stripped' -> 'no final newline' str- العلامة
|تحفظ النص حرفياً Literal بنهايات أسطره\n، وهي ما تستخدمه فيrun:داخل خطوط CI، لأن كل سطر أمر منفصل يجب أن يبقى في سطره. - العلامة
>تطوي Folded الأسطر في سطر واحد وتضع مسافة مكان كل نهاية سطر، وهي مناسبة لنص طويل تريد أن تقسمه للقراءة فقط، مثل وصف. - العلامة
-بعد أي منهما تحذف نهاية السطر الأخيرة، ولاحظ أن الأولين انتهيا بـ\nوالثالث دونها، وهذا الفرق الصغير يهم عندما تكون القيمة مفتاحاً أو كلمة سر، لأنsecret\nليستsecret.
وفي خطوط CI استخدم | دائماً لأوامر عدة أسطر، فلو كتبت > بالخطأ فسوف تصبح الأوامر الثلاثة أمراً واحداً طويلاً، وتفشل الخطوة برسالة لا علاقة ظاهرة لها بالمشكلة.
عندما يقرأ المحلل غير ما كتبت Implicit Typing
الآن نصل إلى الجزء الذي يجعل YAML مشهورة بالمفاجآت. كتبنا الملف التالي بقيم عادية جداً، قائمة رموز دول، ورقم إصدار Python، ومنفذ SSH، وصلاحيات ملف، وجواب، ورمز بريدي:
countries: [SA, AE, NO]
python_version: 3.10
app_version: "3.10"
ssh_port: 22:22
file_mode: 0755
answer: yes
zip_code: 01234docker exec dvb-yaml python show.py 02-surprises.yaml== 02-surprises.yaml
'countries' -> ['SA', 'AE', False] list
'python_version' -> 3.1 float
'app_version' -> '3.10' str
'ssh_port' -> 1342 int
'file_mode' -> 493 int
'answer' -> True bool
'zip_code' -> 668 intست قيم من سبع لم تصل كما قصدناها، والصورة التالية تجمعها مع الطريقة الصحيحة لكتابة كل واحدة:
![ثلاثة أعمدة: ما كتبته في الملف، ثم سهم أحمر إلى ما وصل إلى البرنامج، ثم كيف تكتبه. countries: [SA, AE, NO] تصبح ['SA', 'AE', False] والصحيح [SA, AE, "NO"]، وpython_version: 3.10 تصبح 3.1 float والصحيح "3.10"، وssh_port: 22:22 تصبح 1342 base 60 والصحيح "22:22"، وfile_mode: 0755 تصبح 493 octal والصحيح "0755"، وzip_code: 01234 تصبح 668 octal والصحيح "01234"، وanswer: yes تصبح True والصحيح answer: true، وفي الأسفل القاعدة إذا كانت القيمة نصاً في ذهنك فضعها بين علامتي تنصيص](https://arabroot.io/content/images/2026/11/yaml-basics-03-surprises.webp)
وكل مفاجأة منها لها سبب في مواصفة YAML 1.1 التي يتبعها PyYAML:
- مشكلة النرويج Norway Problem: في YAML 1.1 تعتبر الكلمات
yesوnoوonوoffوyوnبكل أشكال حروفها قيماً منطقية، كما في جدول الأنواع المنطقية في YAML 1.1، فرمز النرويجNOأصبحFalse، وهكذا اشتهرت المشكلة بهذا الاسم. وتخيل أن هذه القائمة قائمة الدول المسموح الشحن إليها. - رقم الإصدار:
3.10رقم عشري يساوي3.1، فإذا كتبت إصدار Python أو Node في ملف CI دون تنصيص فقد تحصل على إصدار غير الذي طلبته، وقد تحصل على خطأ «الإصدار 3.1 غير موجود» يبدو بلا معنى. - الأرقام الستينية Sexagesimal: YAML 1.1 تقرأ الأرقام المفصولة بنقطتين كأرقام بالأساس 60 مثل الوقت، فـ
22:22تساوي 22 × 60 + 22 = 1342، وهذا بالضبط شكل ربط المنافذ في Docker Compose. - الأرقام الثمانية Octal: الرقم الذي يبدأ بصفر يقرأ بالأساس 8، فـ
0755تساوي 493 بالعشري، وهذا صحيح إذا كنت تقصد صلاحيات ملف وكانت الأداة تتوقع رقماً، ولكن الرمز البريدي01234أصبح 668 وضاع الصفر الأول.
وفي YAML 1.2 أزيلت أغلب هذه القواعد، فالقيم المنطقية أصبحت true وfalse فقط، والأرقام الثمانية تكتب بالبادئة 0o، ولا توجد أرقام ستينية. ولكن المهم ليس ما تقوله المواصفة الأحدث، وإنما ما يتبعه المحلل الذي سوف يقرأ ملفك، وهذا ما نراه في القسم التالي.
ملف واحد ومحللان: Compose مقابل PyYAML
كتبنا ملف Compose صغيراً لـ Gitea، فيه منفذان أحدهما دون تنصيص، ومتغيرا بيئة، ثم قرأناه بمحللين: Docker Compose نفسه، وPyYAML الذي تستخدمه أدوات Python مثل Ansible:
services:
git:
image: gitea/gitea:28.3.0
ports:
- 22:22
- "3000:3000"
environment:
USER_UID: 1000
GITEA__server__DISABLE_SSH: falsedocker compose -f 07-compose-ports.yaml -p dvb-yaml config
docker exec dvb-yaml python -c "import yaml;print(yaml.safe_load(open('07-compose-ports.yaml'))['services']['git'])"name: dvb-yaml
services:
git:
environment:
GITEA__server__DISABLE_SSH: "false"
USER_UID: "1000"
image: gitea/gitea:28.3.0
networks:
default: null
ports:
- mode: ingress
target: 22
published: "22"
protocol: tcp
- mode: ingress
target: 3000
published: "3000"
protocol: tcp
networks:
default:
name: dvb-yaml_default
{'image': 'gitea/gitea:28.3.0', 'ports': [1342, '3000:3000'], 'environment': {'USER_UID': 1000, 'GITEA__server__DISABLE_SSH': False}}في المخرج أعلاه لاحظ التالي:
- Docker Compose v5.5.1 فهم
22:22كربط للمنفذ 22 بالمنفذ 22، لأن محلله يتبع قواعد YAML 1.2 التي لا تعرف الأرقام الستينية، أما PyYAML فقرأ السطر نفسه كرقم 1342. فإذا استخدمت أداة Python تقرأ ملف Compose أو تعدله، مثل سكربت يفحص المنافذ أو Ansible يكتب الملف، فسوف ترى قيمة غير التي يراها Docker. - متغيرات البيئة في Compose نصوص دائماً، فحولها Compose إلى
"1000"و"false"، أما PyYAML فرأى رقماً وقيمة منطقية، وأي سكربت يكتب الملف من جديد قد يكتبهاFalseبحرف كبير، فيقرؤها التطبيق كنص لا يعرفه. - توثيق Compose نفسه يحذر من ذلك في قسم المنافذ ports، ويقول إن الصيغة HOST:CONTAINER يجب أن تكتب دائماً كنص بين علامتي تنصيص لتجنب التعارض مع الأرقام الستينية في YAML.
- الأمر
docker compose configيطبع الملف كما فهمه Compose بعد التحليل وتطبيق القيم الافتراضية، ولذلك فهو أفضل أداة لتعرف ماذا سوف يحدث فعلاً قبلdocker compose up، والتفاصيل في توثيق compose config. ولاحظ أن التعليقات وترتيب المفاتيح لم تبق في مخرجه.
والقاعدة العملية من كل ما سبق بسيطة: إذا كانت القيمة نصاً في ذهنك فضعها بين علامتي تنصيص، وخاصة المنافذ وأرقام الإصدارات والرموز والأرقام التي تبدأ بصفر، واكتب القيم المنطقية true وfalse فقط.
الرموز الخاصة وعلامات التنصيص Quoting
المفاجآت السابقة كانت في الأنواع، وهناك نوع آخر من الأخطاء يأتي من رموز لها معنى في YAML إذا ظهرت في قيمة دون تنصيص. وجربنا أربعة منها تظهر كثيراً في ملفات DevOps: باسورد فيه علامة #، وأمر فيه نقطتان، ونمط ملفات يبدأ بنجمة، ومسار Windows فيه شرطة مائلة عكسية:
password: abc #123
url: http://example.com/#top== 12-special-a.yaml
'password' -> 'abc' str
'url' -> 'http://example.com/#top' strالباسورد الذي وصل إلى البرنامج هو abc فقط، لأن المسافة ثم # تبدأ تعليقاً، فضاع نصف الباسورد دون أي خطأ، وسوف تقضي وقتاً طويلاً تبحث لماذا يرفض السيرفر الدخول. أما الرابط فبقي كاملاً لأن # فيه لا تسبقها مسافة. والأسطر الثلاثة التالية يرفضها المحلل كل واحد منها في ملف وحده:
command: echo key: value
pattern: *.log
mention: @teamyaml.scanner.ScannerError: mapping values are not allowed here
in "12-special-e.yaml", line 1, column 18
yaml.scanner.ScannerError: while scanning an alias
in "12-special-b.yaml", line 1, column 10
expected alphabetic or numeric character, but found '.'
yaml.scanner.ScannerError: while scanning for the next token
found character '@' that cannot start any token- النقطتان ثم مسافة داخل قيمة دون تنصيص تبدو للمحلل بداية قاموس جديد، فيعطي
mapping values are not allowed here، وهذه أشهر رسالة تراها في خطوط CI عندما يحتوي الأمر فيrunعلى نقطتين، والحل أن تضع الأمر بين علامتي تنصيص أو تستخدم|وتكتبه في السطر التالي. - النجمة في بداية القيمة تعني اسماً مستعاراً Alias لمرساة كما رأيت في قسم المراسي، فيبحث المحلل عن مرساة اسمها
.logويفشل. - العلامة
@محجوزة في المواصفة ولا تبدأ بها قيمة دون تنصيص، وكذلك العلامة`.
وأخيراً الفرق بين نوعي التنصيص، وهو يهم مع مسارات Windows والتعابير النمطية Regular Expressions:
double: "C:\new\table"
single: 'C:\new\table'== 12-special-d.yaml
'double' -> 'C:\new\table' str
'single' -> 'C:\\new\\table' strكتبنا المسار نفسه مرتين بشرطة مائلة عكسية واحدة قبل n وt، والتنصيص المزدوج يفسر الهروب Escape، فأصبحت \n نهاية سطر و\t مسافة Tab، أي أن المسار تحول إلى ثلاث قطع، ويظهر ذلك في المخرج كـ \n و\t داخل تمثيل Python. أما التنصيص المفرد فيأخذ النص حرفياً، فبقيت الشرطات المائلة كما هي، ويظهرها Python مضاعفة \\ لأنها شرطات حقيقية. والقاعدة: استخدم التنصيص المفرد للنصوص الحرفية مثل المسارات والتعابير النمطية، والمزدوج عندما تحتاج إلى \n أو إلى علامة تنصيص مفردة داخل النص.
قراءة ملف workflow سطراً سطراً Reading a Workflow
الآن نجمع كل ما سبق على الملف الذي سوف تكتبه في المقال التالي، وهو خط CI صغير في Gitea Actions، ونقرؤه كما يقرؤه المحلل:
name: ci
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
env:
PYTHON_VERSION: "3.13"
steps:
- uses: actions/checkout@v4
- name: Run tests
run: |
python -m unittest -v
echo "tests done: $PYTHON_VERSION"- المستوى الأعلى قاموس فيه ثلاثة مفاتيح:
nameوonوjobs. والمفتاحonكلمة منطقية في YAML 1.1، فإذا قرأت الملف بـ PyYAML فسوف يصبح المفتاحTrueوليس"on"، أما محلل Gitea المكتوب بـ Go فيقرؤه نصاً، وهذا سبب الخيارcheck-keys: falseفي إعداد yamllint. - قيمة
onقاموس فيه حدثان، وpull_request:دون قيمة يعنيnull، أي «هذا الحدث بإعداده الافتراضي»، وهذا شكل شائع في ملفات CI. jobsقاموس أسماء المهام، وكل مهمة قاموس فيهruns-onوsteps، وstepsقائمة، وكل عنصر فيها قاموس يبدأ بشرطة، فالخطوة الأولى قاموس بمفتاح واحدuses، والثانية قاموس بمفتاحين."3.13"بين علامتي تنصيص لكي لا يصبح الرقم 3.13 رقماً عشرياً، ولو كان الإصدار 3.10 لأصبح 3.1 كما رأيت.run: |يحفظ السطرين كما هما، فيعمل كل سطر كأمر، والنقطتان في"tests done: ..."لا تسببان خطأ لأنهما داخل نص حرفي بعد|وداخل علامتي تنصيص للطرفية.
ولاحظ أن التعابير مثل ${{ secrets.TOKEN }} التي سوف تراها في خطوط CI ليست جزءاً من YAML، وإنما نص عادي يقرؤه محلل YAML كما هو، ثم يستبدله Gitea بالقيمة عند التشغيل، ولذلك فهي تخضع لقواعد YAML نفسها أولاً، فإذا بدأت القيمة بـ { فضعها بين علامتي تنصيص حتى لا يظنها المحلل قاموساً في سطر واحد.
أخطاء المسافات Indentation Errors
أخطاء المسافات نوعان: نوع يوقف المحلل برسالة واضحة، ونوع أخطر لا يوقفه، وإنما ينتج بنية مختلفة عما قصدت. ولنبدأ بالأول، وهو ملف فيه Tab بدلاً من المسافات قبل ports:
services:
web:
image: nginx:1.29-alpine
ports:
- "8080:80"yaml.scanner.ScannerError: while scanning for the next token
found character '\t' that cannot start any token
in "04-tab.yaml", line 4, column 1المحلل يقول بالضبط أين المشكلة: السطر 4، العمود 1، والحرف '\t'، فاذهب إلى ذلك السطر واستبدل Tab بمسافات. والمشكلة أن Tab لا يظهر في أغلب المحررات إلا كفراغ، فإذا لم تر شيئاً غريباً في السطر فاعرض المسافات المخفية في المحرر.
أما النوع الثاني فأخطر، ففي الملف التالي أراد الكاتب أن تكون ports تابعة للخدمة web، ولكنه أزاحها بمسافتين فقط بدلاً من أربع:
services:
web:
image: nginx:1.29-alpine
environment:
APP_ENV: production
ports:
- "8080:80"هذا ملف YAML صحيح تماماً، ولا يعطي أي خطأ في المحلل، ولكن انظر كيف قرأه:
{
"services": {
"web": {
"image": "nginx:1.29-alpine",
"environment": {
"APP_ENV": "production"
}
},
"ports": [
"8080:80"
]
}
}أصبحت ports خدمة اسمها «ports» بجانب web، وليست منافذ لها. ومن حسن الحظ أن Docker Compose يتحقق من البنية بمخطط Schema، فرفض الملف:
docker compose -f 05-indent.yaml -p dvb-yaml configservices.ports must be a mappingوهذه هي الرسالة التي بدأنا بها المقال، ومعناها الآن واضح: Compose يرى تحت services مفتاحاً اسمه ports، ويتوقع أن تكون كل خدمة قاموساً، فوجد قائمة. فإذا رأيت رسالة تذكر مساراً مثل services.ports فاقرأها كعنوان في الشجرة، وابحث عن السطر الذي جعل هذا المفتاح في هذا المستوى. ولكن ليست كل الأدوات تتحقق بمخطط، فالخطأ نفسه في ملف إعداد لتطبيقك قد يمر بصمت، ويقرأ التطبيق القيمة الافتراضية لأن المفتاح ليس في مكانه.
المفتاح المكرر Duplicate Keys
الخطأ الصامت الثاني أن يتكرر المفتاح نفسه في القاموس نفسه، وهذا يحدث كثيراً في الملفات الطويلة عندما يضيف شخص قيمة في آخر القسم دون أن يرى أنها موجودة في أوله:
db:
host: db.internal
password: from-vault
host: localhost== 06-duplicate.yaml
'db' -> {'host': 'localhost', 'password': 'from-vault'} dictالمواصفة تقول إن المفاتيح يجب أن تكون فريدة، ولكن PyYAML لم يعط خطأ، وأخذ القيمة الأخيرة localhost بصمت، فالتطبيق في الإنتاج سوف يحاول الاتصال بقاعدة بيانات على نفسه. ومحللات أخرى تتصرف بشكل مختلف، فبعضها يأخذ الأول وبعضها يرفض الملف، وهذا سبب إضافي لكي لا تعتمد على سلوك المحلل وإنما تفحص الملف قبل أن يصل إليه، وهذا ما تفعله yamllint كما سوف نرى.
تجنب التكرار بالمراسي Anchors
عندما يكون عندك في ملف Compose عدة خدمات تشترك في الـ Image ومتغيرات البيئة وسياسة إعادة التشغيل، فلا تكرر هذه الأسطر في كل خدمة، وإنما عرفها مرة واحدة بمرساة Anchor بالعلامة &، ثم استدعها بالاسم المستعار Alias بالعلامة *، وادمجها في القاموس بمفتاح الدمج <<. ويسمح Compose بقسم في أعلى الملف يبدأ اسمه بـ x- لهذا الغرض بالضبط، فيتجاهله كخدمة، كما في توثيق الامتدادات Extensions وتوثيق المقاطع Fragments:
x-app: &app
image: invoice-tool:1.4.0
restart: unless-stopped
environment:
APP_ENV: production
VAT: "0.15"
services:
web:
<<: *app
command: ["gunicorn", "app:wsgi"]
worker:
<<: *app
command: ["python", "worker.py"]
environment:
QUEUE: invoicesأراد الكاتب أن يضيف إلى worker متغيراً ثالثاً QUEUE إلى جانب المتغيرين المشتركين، ولنر ماذا فهم Compose:
docker compose -f 08-anchors.yaml -p dvb-yaml configservices:
web:
command:
- gunicorn
- app:wsgi
environment:
APP_ENV: production
VAT: "0.15"
image: invoice-tool:1.4.0
...
worker:
command:
- python
- worker.py
environment:
QUEUE: invoices
image: invoice-tool:1.4.0
...الخدمة web أخذت كل شيء من القالب، أما worker فخسرت APP_ENV وVAT دون أي تحذير، والسبب أن مفتاح الدمج << يدمج المستوى الأول فقط Shallow Merge، فعندما كتبت environment في الخدمة استبدل القاموس كله ولم يدمج محتواه، والصورة التالية تبين ذلك:

والحل أن تجعل البيئة نفسها مرساة منفصلة وتدمجها داخل environment، أي environment: {<<: *app-env, QUEUE: invoices}، أو أن تضع المتغيرات المشتركة في ملف env_file واحد تستخدمه كل الخدمات. وفي كل الأحوال شغل docker compose config بعد أي تعديل على المراسي، لأنه الطريقة الوحيدة لترى الناتج النهائي. ولاحظ أيضاً أن مفتاح الدمج << كان جزءاً من أنواع YAML 1.1 وليس من مواصفة 1.2 الأساسية، ولكن أغلب المحللات المستخدمة في DevOps تدعمه، أما خطوط Gitea Actions وGitHub Actions فقد لا تدعم المراسي كلها بنفس الطريقة، فلا تعتمد عليها هناك قبل أن تجرب.
عدة مستندات في ملف واحد Multiple Documents
في Kubernetes ستجد ملفات فيها عدة كائنات مفصولة بثلاث شرطات ---، وكل جزء مستند Document مستقل، كما يشرح توثيق كائنات Kubernetes:
---
kind: Namespace
name: shop
---
kind: Deployment
name: webpython -c "import yaml;print(list(yaml.safe_load_all(open('10-multi.yaml'))))"
python -c "import yaml;yaml.safe_load(open('10-multi.yaml'))"[{'kind': 'Namespace', 'name': 'shop'}, {'kind': 'Deployment', 'name': 'web'}]
yaml.composer.ComposerError: expected a single document in the stream
in "10-multi.yaml", line 2, column 1
but found another document
in "10-multi.yaml", line 4, column 1الدالة safe_load_all تعيد قائمة بالمستندات، أما safe_load فتتوقع مستنداً واحداً وترفض الملف، فإذا كتبت سكربتاً يقرأ ملفات Kubernetes فاستخدم النسخة التي تقرأ الكل. والشرطات الثلاث في أول ملف واحد اختيارية، ولكن yamllint بإعداده الافتراضي يطلبها كما سوف ترى.
تحميل YAML من مصدر لا تثق به Safe Loading
YAML أقوى مما يحتاجه أغلب الناس، فالمواصفة تسمح بوسوم Tags تطلب من المحلل أن ينشئ كائناً من نوع معين، وPyYAML يدعم وسوماً خاصة بلغة Python تنشئ أي كائن، بل وتستدعي أي دالة. والملف التالي يبدو كملف إعداد عادي، ولكن قيمة run فيه طلب لتنفيذ أمر على النظام:
name: report
run: !!python/object/apply:os.system ["echo this command ran inside the parser"]python -c "import yaml;print(yaml.safe_load(open('09-untrusted.yaml')))"
python -c "import yaml;print(yaml.unsafe_load(open('09-untrusted.yaml')))"
python -c "import yaml;print(yaml.load(open('09-untrusted.yaml')))"yaml.constructor.ConstructorError: could not determine a constructor for the tag 'tag:yaml.org,2002:python/object/apply:os.system'
in "09-untrusted.yaml", line 2, column 6
this command ran inside the parser
{'name': 'report', 'run': 0}
TypeError: load() missing 1 required positional argument: 'Loader'في المخرج أعلاه لاحظ التالي:
safe_loadرفضت الوسم ولم تنفذ شيئاً، لأنها لا تعرف إلا الأنواع الأساسية: نصوص وأرقام وقوائم وقواميس.unsafe_loadنفذت الأمر أثناء قراءة الملف، فطبع السطر قبل أن يصل البرنامج إلى البيانات أصلاً، والقيمة0هي رمز خروج الأمر. وفي التجربة كان الأمرecho، ولو كان الملف من مهاجم لكان أي أمر آخر بصلاحيات برنامجك.loadدون تحديد Loader لم تعد مقبولة في PyYAML 6، وهذا تغيير مقصود بعد أن كانت في الإصدارات القديمة تعمل كـunsafe_load، كما يشرح إعلان إيقاف yaml.load وتوثيق PyYAML.
yaml.load في PyYAML قبل الإصدار 5.1 للسبب نفسه. والدرس أن قراءة YAML من مصدر لا تتحكم به، مثل ملف يرفعه مستخدم أو طلب من الإنترنت، يجب أن تكون بالدالة الآمنة دائماً.وهذا لا يعني أن ملفات Compose وCI خطرة بهذا الشكل، فأدواتها لا تنشئ كائنات من الوسوم، ولكن خطورتها من نوع آخر: ملف workflow يغيره شخص في طلب دمج يستطيع أن يشغل أي أمر على الـ Runner، ولذلك تراجع هذه الملفات في طلبات الدمج بعناية أكبر من غيرها، كما شرحنا في مراجعة الطلبات من خارج الفريق.
افحص قبل أن تدفع yamllint
كل الأخطاء الصامتة السابقة تمسكها أداة فحص Linter قبل أن تصل إلى أي محلل، وأشهرها لـ YAML الأداة yamllint. ولنشغلها بإعدادها الافتراضي على ملف المفاجآت وملف المفتاح المكرر:
yamllint 02-surprises.yaml
yamllint 06-duplicate.yaml02-surprises.yaml
1:1 warning missing document start "---" (document-start)
1:21 warning truthy value should be one of [false, true] (truthy)
6:9 warning truthy value should be one of [false, true] (truthy)
06-duplicate.yaml
1:1 warning missing document start "---" (document-start)
4:3 error duplication of key "host" in mapping (key-duplicates)أمسكت الأداة NO وyes والمفتاح المكرر، ولكنها لم تقل شيئاً عن 0755 و01234، لأن القاعدة octal-values مطفأة في الإعداد الافتراضي، وطلبت شرطات بداية المستند في كل ملف، وهذا غير معتاد في ملفات Compose وCI. لذلك نضع في المجلد الرئيسي للمستودع ملف .yamllint يناسبنا:
extends: default
rules:
document-start: disable
octal-values: enable
truthy:
check-keys: falseyamllint 02-surprises.yaml; echo "exit=$?"02-surprises.yaml
1:21 warning truthy value should be one of [false, true] (truthy)
5:16 error forbidden implicit octal value "0755" (octal-values)
6:9 warning truthy value should be one of [false, true] (truthy)
7:16 error forbidden implicit octal value "01234" (octal-values)
exit=1في الإعداد أعلاه لاحظ التالي:
- الخيار
check-keys: falseفي القاعدةtruthyمهم لملفات خطوط CI، والسبب أن مفتاح الأحداث فيها اسمهon، وهو قيمة منطقية في YAML 1.1، فبدونه سوف تشتكي الأداة من كل ملف workflow. - رمز الخروج 1 عند وجود error يجعل الأداة مناسبة لخط CI، فيفشل الطلب الذي فيه ملف خاطئ قبل الدمج، أما warning فلا يفشلها إلا بالخيار
--strict. - yamllint لا تعرف شيئاً عن معنى الملف، فهي لا تعرف أن
portsيجب أن تكون داخل الخدمة، ولذلك تحتاج معها إلى أداة الملف نفسه مثلdocker compose configالتي تتحقق من البنية.
ولكي يصبح الفحص عادة لا تعتمد على الذاكرة، ضع الأداتين في المكانين اللذين يمر بهما كل تغيير: على جهازك في خطاف pre-commit يعمل قبل كل Commit، وفي خط CI على كل طلب دمج. وفي خط CI يكفي سطران: yamllint . ثم docker compose config --quiet، والخيار --quiet يجعل الأمر لا يطبع الملف ويكتفي برمز الخروج، فيفشل الخط إذا رفض Compose البنية. وإذا كان محررك يدعم التحقق بمخطط JSON Schema لملفات YAML، كما تفعل إضافات YAML المعروفة في محررات الكود، فسوف ترى الخط الأحمر تحت ports في مكانها الخاطئ وأنت تكتب، قبل أي أداة أخرى.
ماذا يحدث إذا دفعت workflow فيه خطأ؟ What If
جربنا أخيراً ما يحدث في المكان الذي سوف تكتب فيه أغلب YAML في هذه المرحلة: ملف خط CI في Gitea. شغلنا Gitea 28.3.0 دون أي Runner، ودفعنا إلى مستودع ملف .gitea/workflows/ci.yml فيه خطوة إزاحتها أكبر من أختها بمسافة واحدة:
name: ci
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Run tests
run: python -m unittest
- name: Lint
run: yamllint .ولو فحصنا الملف قبل الدفع لعرفنا المشكلة مباشرة:
.gitea/workflows/ci.yml
9:8 error syntax error: expected <block end>, but found '<block sequence start>' (syntax)
10:9 warning wrong indentation: expected 9 but found 8 (indentation)ولكننا دفعناه كما هو لنرى ما يفعله Gitea، فظهر في تبويب Actions تشغيل فاشل بجانبه علامة تحذير على اسم الملف:

وعند فتح التشغيل يعرض Gitea سبب الفشل، وهو رسالة محلل YAML المكتوب بلغة Go:

في النتيجة أعلاه لاحظ التالي:
- الرسالة
did not find expected '-' indicatorمع الموضعL7.C7-L9.C8تعني أن المحلل كان يقرأ قائمة الخطوات التي بدأت في السطر 7 العمود 7، وتوقع في السطر 9 عنصراً جديداً يبدأ بشرطة في العمود نفسه، فوجد الشرطة في العمود 8. وهذه الرسالة تختلف في صياغتها عن رسالة yamllint، لأن كل محلل يصف الخطأ بطريقته، ولكن الاثنين يشيران إلى السطر 9. - التشغيل استغرق صفر ثوان ولم يحتج إلى Runner، فالتحقق من الملف يحدث على سيرفر Gitea عند الدفع، وهذا يعني أن خطأ YAML في ملف workflow يظهر فوراً، ولكنه يظهر بعد الدفع، أي بعد أن دخل الخطأ إلى المستودع.
وبعد أن أصلحنا الإزاحة بالأمر sed وتأكدنا بالأداة yamllint أن الملف سليم ودفعناه، ظهر التشغيل الثاني بحالة queued، أي أن Gitea قبل الملف وينتظر Runner ينفذه، وهذا بالضبط ما سوف نضيفه في مقال CI/CD للمبتدئين. والدرس أن الفحص قبل الدفع، على جهازك أو في خطاف pre-commit، يوفر عليك Commit إصلاح وتشغيلاً فاشلاً في سجل المستودع.
وعند الانتهاء احذف المختبر:
docker rm -f dvb-gitea dvb-yaml
docker volume rm dvb-gitea-data
docker network rm dvb-netمتى تختار غير YAML؟ JSON مع TOML
أنت لا تختار صيغة ملف Compose ولا ملف Gitea Actions، فالأداة هي التي تحددها، ولكنك تختار صيغة ملفات الإعداد في تطبيقك، والجدول التالي يضع الثلاثة بجانب بعضها:
| YAML | JSON | TOML | |
|---|---|---|---|
| التعليقات | مسموحة | غير مسموحة | مسموحة |
| البنية | بالمسافات | بالأقواس والفواصل | أقسام بين أقواس مربعة ومفاتيح |
| الأنواع الضمنية | كثيرة ومفاجئة في 1.1 | قليلة وواضحة | واضحة، والنص دائماً بين علامتي تنصيص |
| العمق | مريحة للبنى العميقة | مريحة للبرامج، متعبة للبشر | مريحة للإعداد المسطح، متعبة للعميق |
| أين تراها | Compose، CI، Kubernetes، Ansible | الواجهات البرمجية API، package.json | pyproject.toml، Cargo.toml |
والخلاصة العملية أن YAML مناسبة لملفات يكتبها البشر ويراجعونها وفيها تداخل كثير، وJSON مناسبة لما تكتبه البرامج وتقرؤه، وTOML مناسبة لإعداد تطبيق فيه أقسام قليلة. وإذا كان تطبيقك يقرأ إعداده من متغيرات البيئة كما ننصح في متغيرات البيئة Environment Variables، فقد لا تحتاج إلى ملف إعداد أصلاً.
أخطاء شائعة Common Mistakes
- Tab بدلاً من المسافات: المحلل يرفض الملف، فاضبط المحرر ليحول Tab إلى مسافات في ملفات YAML.
- إزاحة خاطئة لا تعطي خطأ: المفتاح ينتقل إلى مستوى آخر بصمت، فشغل أداة الملف نفسه مثل
docker compose configلترى البنية النهائية. - منافذ وإصدارات دون تنصيص:
22:22و3.10و0755لا تصل كما كتبتها في كل المحللات، فضعها بين علامتي تنصيص. yesوnoوonوoffكقيم: استخدمtrueوfalseفقط، وضع الرموز مثلNOبين علامتي تنصيص.- مفتاح مكرر في ملف طويل: القيمة الأخيرة تفوز بصمت في PyYAML، فشغل yamllint.
- الاعتماد على المراسي لدمج قواميس داخلية: الدمج سطحي، والقاموس الداخلي يستبدل.
>بدلاً من|في أوامر CI: الأسطر تصبح أمراً واحداً.yaml.loadأوunsafe_loadعلى ملف من مستخدم: استخدمsafe_loadدائماً.
قائمة تحقق Checklist
| قبل أن تدفع ملف YAML | كيف تتأكد |
|---|---|
| لا يوجد Tab والإزاحة متسقة | المحرر يعرض المسافات، وyamllint لا يشتكي من indentation |
| النصوص التي تشبه أرقاماً أو قيماً منطقية بين علامتي تنصيص | yamllint مع octal-values وtruthy لا يعطي خطأ |
| لا توجد مفاتيح مكررة | yamllint لا يعطي key-duplicates |
| البنية كما تقصد | docker compose config أو الأداة الخاصة بالملف تقبله وتعرض الناتج المتوقع |
أوامر CI متعددة الأسطر بالعلامة | | كل أمر في سطره داخل run |
| المراسي تعطي ما تقصد | الناتج بعد الدمج فيه كل المفاتيح المشتركة |
| الفحص آلي | yamllint يعمل في خطاف pre-commit أو في خط CI على كل طلب دمج |
ماذا تقرأ بعد ذلك؟ Next Steps
دليلGitea Actions: تشغيل CI/CD وبناء Docker Images على سيرفركاجعل سيرفرك يختبر الكود ويبني Docker Images تلقائياً مع كل push، دون أن يخرج كودك أو أسرارك إلى خدمة CI خارجية.
دليلبيئة تطوير محلية كاملة بملف Docker Compose واحدنبني بيئة تطوير فيها البريد وHTTPS والأسماء المحلية، ونكتب اختباراً آلياً لبريد استعادة كلمة المرور ثم نفتعل فيها الأعطال.
دليلمن الفرع إلى الإنتاج: البيئات وGitOps للفرقكيف يختبر فريقك كل ميزة وحدها ويعرضها على العميل دون أن تصل ميزة غير جاهزة إلى الإنتاج.
دليلمتغيرات البيئة Environment Variables: تطبيق واحد لكل البيئاتكيف يقرأ تطبيقك إعداده من الخارج ويتحقق منه عند التشغيل، فتنتقل Image واحدة بين كل البيئات دون أي سر في الكود.بعد أن أصبحت تقرأ YAML بثقة، فالخطوة التالية أن تكتب أول خط CI/CD كامل، وقد شرحنا تشغيله على سيرفرك في Gitea Actions، وإذا أردت أن ترى ملف Compose حقيقياً لبيئة تطوير كاملة فاقرأ بيئة تطوير محلية بملف Docker Compose واحد.
تدريب عملي Practice
أفضل طريقة لتثبيت ما قرأته أن تكسر الملفات بنفسك وتقرأ الرسائل، وهذه أربعة تمارين قصيرة على المختبر نفسه:
- افتح ملف Compose لأي مشروع عندك، وشغل عليه
docker compose config، وقارن الناتج بما كتبته: هل تغير أي منفذ أو متغير بيئة؟ ثم شغل عليه yamllint بالإعداد الذي في هذا المقال، وأصلح كل error قبل أي warning. - اكتب ملفاً فيه قائمة رموز الدول الخليجية
[SA, AE, KW, QA, BH, OM]وأضف إليهاNOوON، ثم اقرأه بـshow.pyوتوقع قبل التشغيل أي العناصر سوف يصبح قيمة منطقية، ثم صحح الملف بأقل عدد من علامات التنصيص. - أضف إلى ملف المراسي في المختبر مرساة ثانية للبيئة وحدها، واجعل الخدمة
workerتحتفظ بالمتغيرين المشتركين وتضيفQUEUE، ثم تأكد بالأمرdocker compose configأن المتغيرات الثلاثة ظهرت. - اكتب خطوة CI فيها أمر يحتوي نقطتين ومسافة، مثل
echo "build: ok"، مرة بعدrun:في السطر نفسه دون تنصيص خارجي، ومرة بالعلامة|، وشغل yamllint على الحالتين، واشرح لنفسك لماذا تنجح إحداهما فقط.
وإذا نجحت في هذه التمارين فأنت مستعد لقراءة أي ملف workflow أو Compose تقابله، ولمعرفة السطر الذي يسبب الخطأ من رسالة المحلل وحدها.
الخلاصة Summary
- YAML صيغة بيانات يقرؤها البشر، تتكون من قواميس وقوائم وقيم مفردة، والمسافات وحدها هي التي تحدد البنية، ولا يسمح فيها بـ Tab.
- المحلل يخمن نوع القيمة من شكلها، وفي YAML 1.1 التي يتبعها PyYAML أصبح
NOقيمة منطقية و3.10رقم 3.1 و22:22رقم 1342 و01234رقم 668، أما Compose فقرأ22:22كمنفذ، فالملف نفسه قد يعني شيئين لأداتين. - أخطر الأخطاء الصامتة: إزاحة تنقل مفتاحاً إلى مستوى آخر، ومفتاح مكرر تفوز فيه القيمة الأخيرة، ومرساة تستبدل القاموس الداخلي بدلاً من أن تدمجه.
- اقرأ YAML من مصدر لا تثق به بـ
safe_loadفقط، لأن الوسوم الخاصة قد تنفذ أوامر أثناء القراءة. - افحص قبل أن تدفع بـ yamllint مع إعداد يناسب ملفاتك، ومع أداة الملف نفسها مثل
docker compose config، لأن Gitea يرفض workflow فيه خطأ فقط بعد أن يصل إلى المستودع.
سجل التحديثات Changelog
- نوفمبر 2026: كتابة المقال واختبار كل الأمثلة على Python 3.13.18 مع PyYAML 6.0.3 وyamllint 1.38.0 وDocker Compose v5.5.1 وGitea 28.3.0.