الفصل الرابع: مقدمة إلى YAML

قبل أن نتعلم GitHub Actions فعلياً، يجب أن نفهم YAML بشكل عميق.

وهنا يقع أكبر خطأ عند المبتدئين:

يعتقد أن GitHub Actions هو الشيء الصعب.

بينما الحقيقة أن أغلب الأخطاء تأتي من YAML نفسه.

أحياناً تضيف مسافتين زيادة أو تنقص مسافتين فقط فتفشل الـ Workflow بالكامل.

لهذا سنفهم YAML من الصفر وحتى المستوى الاحترافي.

---

ما هو YAML؟

YAML اختصار لـ:

YAML Ain't Markup Language

أي:

YAML ليست لغة Markup

مثل:

• HTML
• XML

بل هي لغة لوصف البيانات (Data Serialization Language).

---

ماذا يعني ذلك؟

تخيل أن لديك بيانات:

اسم المشروع
الإصدار
اللغة
البيئة

تحتاج طريقة لكتابتها بشكل منظم.

يمكن كتابتها هكذا:

{
  "project": "Laravel App",
  "version": "1.0"
}

أو:

<project>
  <name>Laravel App</name>
</project>

لكن هذه الطرق مليئة بالأقواس والرموز.

---

فجاء YAML ليجعلها أسهل:

project: Laravel App
version: 1.0

أبسط بكثير.

---

لماذا تم إنشاء YAML؟

قبل YAML كانت الأدوات تعتمد على:

XML

مثال:

<server>
    <host>localhost</host>
</server>

---

أو JSON:

{
  "host": "localhost"
}

---

فقرر المطورون إنشاء تنسيق أكثر سهولة للبشر.

---

النتيجة:

host: localhost

---

لماذا يستخدم GitHub Actions YAML؟

لأن GitHub يحتاج طريقة لوصف Workflow.

مثلاً:

نريد أن نقول:

عند Push
شغل Job
نفذ أمر

---

يمكن كتابتها نظرياً:

{
 "event":"push"
}

لكن تصبح معقدة بسرعة.

---

لذلك اختارت GitHub YAML.

---

مثال:

on:
  push:

---

GitHub يقرأ YAML.

ثم يحوله داخلياً إلى أوامر تنفيذ.

---

كيف يفكر GitHub عند قراءة YAML؟

مثلاً:

name: Laravel CI

on:
  push:

GitHub يقرأها كالتالي:

Workflow Name = Laravel CI

Trigger = Push

---

ثم:

jobs:

يفهم:

هناك Jobs قادمة

---

ثم:

test:

يفهم:

اسم Job هو test

---

إذاً YAML ليس كوداً تنفيذياً.

هو مجرد:

وصف Configuration

---

أهم قاعدة في YAML

احفظها جيداً:

المسافات أهم من الأقواس

في JSON نستخدم:

{
}

---

في YAML نستخدم:

key:
  child:

---

كل شيء يعتمد على المسافات.

---

قواعد كتابة YAML

---

أولاً: Key-Value

أبسط شيء في YAML.

---

الصيغة:

key: value

---

مثال:

name: Laravel CI

---

هنا:

key = name
value = Laravel CI

---

مثال آخر:

version: 1.0

---

مثال:

environment: production

---

مثل القاموس:

name → Laravel CI

version → 1.0

environment → production

---

ماذا يحدث داخلياً؟

GitHub يقرأ:

name: Laravel CI

ويحولها إلى:

{
  "name": "Laravel CI"
}

---

ثانياً: Indentation

وهذا أهم موضوع في YAML بالكامل.

---

ما معنى Indentation؟

المسافات البادئة.

---

مثال:

name: Laravel CI

on:
  push:

---

لاحظ:

push:

داخل:

on:

بسبب المسافتين.

---

YAML يفهم:

push تابع لـ on

---

مثال بصري

on
└── push

---

---

مثال آخر:

jobs:
  test:

---

معناها:

jobs
└── test

---

مثال أكبر

jobs:
  test:
    runs-on: ubuntu-latest

---

تصبح:

jobs
└── test
    └── runs-on

---

خطأ شائع جداً

jobs:
test:
runs-on: ubuntu-latest

---

هنا YAML ينهار بالكامل.

لأنه لا يعرف العلاقات.

---

قاعدة ذهبية

كل مستوى جديد:

+2 Spaces

---

مثال:

jobs:
  test:
    steps:
      - run: php artisan test

---

المستويات:

jobs
  test
    steps
      run

---

ثالثاً: Lists

القوائم.

---

في YAML القوائم تبدأ بـ:

-

---

مثال:

branches:
  - main
  - develop
  - staging

---

تمثيلها:

branches
├── main
├── develop
└── staging

---

JSON:

{
  "branches": [
    "main",
    "develop",
    "staging"
  ]
}

---

مثال عملي في GitHub Actions

steps:
  - run: composer install

  - run: php artisan test

  - run: phpstan analyse

---

هنا:

steps
├── composer install
├── php artisan test
└── phpstan analyse

---

رابعاً: Objects

الكائنات.

---

مثال:

database:
  host: localhost
  port: 3306

---

تمثيلها:

database
├── host
└── port

---

JSON:

{
  "database": {
    "host": "localhost",
    "port": 3306
  }
}

---

مثال أكبر

server:
  host: localhost
  port: 80
  ssl: true

---

تصبح:

server
├── host
├── port
└── ssl

---

خامساً: List of Objects

مهم جداً في GitHub Actions.

---

مثال:

users:
  - name: Ahmed
    age: 25

  - name: Ali
    age: 30

---

تمثيلها:

users
├── Ahmed
│   └── 25
│
└── Ali
    └── 30

---

وهذا النوع ستراه كثيراً في:

steps:

---

مثال:

steps:
  - name: Install
    run: composer install

  - name: Test
    run: php artisan test

---

كل Step عبارة عن Object.

---

سادساً: Multiline Strings

من أهم الأشياء في GitHub Actions.

---

أحياناً نحتاج أكثر من سطر.

---

مثال:

run: |
  composer install
  php artisan config:cache
  php artisan test

---

الرمز:

|

يعني:

احتفظ بجميع الأسطر كما هي

---

GitHub ينفذ:

composer install

php artisan config:cache

php artisan test

---

لماذا نستخدمه؟

بدلاً من:

- run: composer install

- run: php artisan test

يمكن جمعها.

---

مثال احترافي:

run: |
  docker build -t app .

  docker tag app latest

  docker push app

---

الفرق بين | و >

هذه نقطة احترافية.

---

|

يحافظ على الأسطر.

message: |
  Hello
  World

---

الناتج:

Hello
World

---

>

يدمج الأسطر.

message: >
  Hello
  World

---

الناتج:

Hello World

---

في GitHub Actions غالباً نستخدم:

|

---

سابعاً: Comments

التعليقات.

---

مثل أي لغة.

---

الصيغة:

# Comment

---

مثال:

# Workflow Name
name: Laravel CI

---

مثال:

jobs:
  test:

    # Run Laravel Tests
    steps:

---

GitHub يتجاهل التعليقات.

---

أكثر الأخطاء شيوعاً للمبتدئين

الخطأ 1

نسيان المسافات

❌

jobs:
test:

---

✅

jobs:
  test:

---

الخطأ 2

خلط Tabs مع Spaces

❌

jobs:
<TAB>test:

---

YAML يكره Tabs.

استخدم Spaces فقط.

---

الخطأ 3

نسيان النقطتين

❌

name Laravel CI

---

✅

name: Laravel CI

---

الخطأ 4

كسر مستوى الـ Indentation

❌

jobs:
  test:
      runs-on:
    ubuntu-latest

---

YAML سيفشل.

---

كيف تقرأ أي ملف YAML؟

مثال:

name: Laravel CI

on:
  push:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - run: composer install

      - run: php artisan test

اقرأه بهذه الطريقة:

Workflow Name
│
└── Laravel CI

Event
│
└── Push

Jobs
│
└── Test
    │
    ├── Ubuntu Runner
    │
    ├── Composer Install
    │
    └── PHPUnit

هذه هي العقلية الصحيحة لفهم YAML.

لا تحفظه كسطور نصية، بل اقرأه كشجرة (Tree Structure).

وفي الفصل القادم سنبدأ تعلم YAML عملياً بالتفصيل داخل GitHub Actions وسنفكك أول Workflow حقيقي سطراً سطراً ونفهم لماذا كتب بهذه الطريقة وكيف يقرأه GitHub داخلياً.