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

YAML للمبتدئين: القواعد والأخطاء الشائعة في ملفات الإعداد

اقرأ ملفات Docker Compose وخطوط CI وKubernetes وأنت تفهم كل سطر فيها، وتعرف لماذا يتحول NO إلى false و3.10 إلى 3.1 وكيف تمسك هذه الأخطاء قبل أن تصل إلى السيرفر.

YAML للمبتدئين: القواعد والأخطاء الشائعة في ملفات الإعداد

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

ملف YAML في الوسط بعنوان ملف إعداد Configuration وفيه services وweb وimage app:1.4 وports مع 8080:80، وأسهم إلى أربع أدوات: Docker Compose مع compose.yaml، وخطوط CI/CD مع .gitea/workflows/ci.yml، وKubernetes مع deployment.yaml، وAnsible مع playbook.yml، وتحتها OpenAPI وPrometheus وHelm، وفوقها كل أداة تقرأ الملف بمحلل Parser خاص بها وقد يختلف محللان في فهم السطر نفسه
الصيغة واحدة، ولكن كل أداة تقرؤها بمحلل خاص بها

لاحظ الجملة في أعلى الصورة، فهي فكرة هذا المقال كله: الملف نص، والأداة لا ترى النص وإنما ما يحوله إليه المحلل 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 هو تركيب من هذه الثلاثة داخل بعضها، والصورة التالية تبينها على ملف صغير:

على اليمين ملف YAML بخلفية داكنة فيه db مع host: db وport: 5432 بإزاحة، ثم tags مع - web و- billing، ثم vat: 0.15 وdebug: false، وتحته المسافات تحدد من يتبع من. وعلى اليسار شجرة: قاموس Mapping في الأعلى، تحته db: Mapping وفيه "db" و5432، وtags: Sequence وفيه "web" و"billing"، وvat, debug وقيمتاهما 0.15 وfalse، وفي الأسفل القيم المفردة Scalars نص أو رقم أو قيمة منطقية أو null
كل ملف YAML شجرة من قواميس وقوائم، وأوراقها قيم مفردة
  • القاموس 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: 5432
docker 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 بأسماء واضحة:

  1. المسح Scanning: يقرأ النص حرفاً حرفاً ويقسمه إلى رموز Tokens: مفتاح، ونقطتان، وبداية قائمة، ونص، ونهاية مستوى إزاحة. وفي هذه المرحلة تظهر أخطاء الحروف التي لا يعرفها، مثل Tab و@، ولذلك جاءت رسائلها باسم ScannerError.
  2. التحليل Parsing: يرتب الرموز في أحداث Events مثل «بدأ قاموس» و«انتهت قائمة»، وهنا تظهر أخطاء البنية مثل خطوة في غير مستواها، وهي رسالة Gitea التي رأيتها error in parser.
  3. التركيب Composing: يبني من الأحداث شجرة من العقد Nodes لكل مستند، ويربط الأسماء المستعارة بمراسيها، وهنا ظهر خطأ الملف متعدد المستندات ComposerError لأن الدالة طلبت مستنداً واحداً.
  4. البناء 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: 01234
docker 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، وفي الأسفل القاعدة إذا كانت القيمة نصاً في ذهنك فضعها بين علامتي تنصيص
النتائج الحقيقية من PyYAML 6.0.3، والحل في كل حالة علامتا تنصيص

وكل مفاجأة منها لها سبب في مواصفة 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: false
docker 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: @team
yaml.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 config
services.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 config
services:
  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 في الخدمة استبدل القاموس كله ولم يدمج محتواه، والصورة التالية تبين ذلك:

على اليمين صندوق أصفر x-app: &app فيه image: invoice-tool:1.4.0 وrestart: unless-stopped وenvironment مع APP_ENV: production وVAT: "0.15" بعنوان القالب المشترك، وسهم أخضر <<: *app إلى صندوق أخضر web فيه image + restart وenvironment: APP_ENV, VAT وأخذ كل شيء من القالب، وسهم أحمر إلى صندوق أحمر worker فيه image + restart وenvironment: QUEUE مع كتب environment خاصاً به فاستبدل قاموس القالب كله فاختفى APP_ENV واختفى VAT دون أي تحذير
الدمج يحدث في المستوى الأول فقط، والقاموس الداخلي يستبدل كاملاً

والحل أن تجعل البيئة نفسها مرساة منفصلة وتدمجها داخل 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: web
python -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.
📌
في يناير 2013 سجلت ثغرة CVE-2013-0156 في Ruby on Rails، حيث كان إطار العمل يحول قيماً من طلبات XML إلى أنواع YAML تلقائياً، فاستطاع المهاجم أن يرسل طلباً واحداً ينشئ كائنات من اختياره على السيرفر وينفذ كوداً عليه، وأثرت على كل إصدارات Rails المدعومة حينها قبل 2.3.15 و3.0.19 و3.1.10 و3.2.11. وفي 2018 سجلت CVE-2017-18342 على الدالة yaml.load في PyYAML قبل الإصدار 5.1 للسبب نفسه. والدرس أن قراءة YAML من مصدر لا تتحكم به، مثل ملف يرفعه مستخدم أو طلب من الإنترنت، يجب أن تكون بالدالة الآمنة دائماً.

وهذا لا يعني أن ملفات Compose وCI خطرة بهذا الشكل، فأدواتها لا تنشئ كائنات من الوسوم، ولكن خطورتها من نوع آخر: ملف workflow يغيره شخص في طلب دمج يستطيع أن يشغل أي أمر على الـ Runner، ولذلك تراجع هذه الملفات في طلبات الدمج بعناية أكبر من غيرها، كما شرحنا في مراجعة الطلبات من خارج الفريق.

افحص قبل أن تدفع yamllint

كل الأخطاء الصامتة السابقة تمسكها أداة فحص Linter قبل أن تصل إلى أي محلل، وأشهرها لـ YAML الأداة yamllint. ولنشغلها بإعدادها الافتراضي على ملف المفاجآت وملف المفتاح المكرر:

yamllint 02-surprises.yaml
yamllint 06-duplicate.yaml
02-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: false
yamllint 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 تشغيل فاشل بجانبه علامة تحذير على اسم الملف:

تبويب Actions في المستودع dev1/invoice-tool على Gitea: في القائمة الجانبية All Workflows وci.yml مع مثلث تحذير أحمر، وفي الوسط 1 workflow run: ci: add workflow مع علامة X حمراء، ci.yml #1: Commit 94d0157777 pushed by dev1، وفرع main والمدة 0s
التشغيل فشل في صفر ثوان، أي قبل أن يبدأ أي شيء

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

صفحة التشغيل ci: add workflow #1 في Gitea بحالة Failure وTotal duration 0s، وتحت Job summaries صندوق ci.yml فيه Invalid workflow file: ci.yml ورسالة go-yaml load error in parser (while parsing a block collection) at L7.C7-L9.C8: did not find expected '-' indicator
Gitea يرفض الملف قبل أن يطلب أي Runner، ويعرض السطر والعمود

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

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

YAMLJSONTOML
التعليقاتمسموحةغير مسموحةمسموحة
البنيةبالمسافاتبالأقواس والفواصلأقسام بين أقواس مربعة ومفاتيح
الأنواع الضمنيةكثيرة ومفاجئة في 1.1قليلة وواضحةواضحة، والنص دائماً بين علامتي تنصيص
العمقمريحة للبنى العميقةمريحة للبرامج، متعبة للبشرمريحة للإعداد المسطح، متعبة للعميق
أين تراهاCompose، CI، Kubernetes، Ansibleالواجهات البرمجية API، package.jsonpyproject.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

أفضل طريقة لتثبيت ما قرأته أن تكسر الملفات بنفسك وتقرأ الرسائل، وهذه أربعة تمارين قصيرة على المختبر نفسه:

  1. افتح ملف Compose لأي مشروع عندك، وشغل عليه docker compose config، وقارن الناتج بما كتبته: هل تغير أي منفذ أو متغير بيئة؟ ثم شغل عليه yamllint بالإعداد الذي في هذا المقال، وأصلح كل error قبل أي warning.
  2. اكتب ملفاً فيه قائمة رموز الدول الخليجية [SA, AE, KW, QA, BH, OM] وأضف إليها NO وON، ثم اقرأه بـ show.py وتوقع قبل التشغيل أي العناصر سوف يصبح قيمة منطقية، ثم صحح الملف بأقل عدد من علامات التنصيص.
  3. أضف إلى ملف المراسي في المختبر مرساة ثانية للبيئة وحدها، واجعل الخدمة worker تحتفظ بالمتغيرين المشتركين وتضيف QUEUE، ثم تأكد بالأمر docker compose config أن المتغيرات الثلاثة ظهرت.
  4. اكتب خطوة 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.
نشرة عرب رووت | ArabRoot

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

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

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

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