من طلب الدمج إلى تغيير معتمد في SecureTransport.

1. ما تقوم به السلسلة

لا يتصل هذا الموقع بخادم GitLab الخاص بك ولا بـ SecureTransport: تعمل السلسلة على مشغّلاتك (runners) مع خزنة أسرارك.

تُنفَّذ أربع مهام (jobs) بهذا الترتيب:

quality

على طلب الدمج (merge request) وعلى main: فحص دون اتصال للملفات المعدّلة داخل ⁦flows/⁩ (المخطط وقواعد النمذجة والحوكمة والأسرار المكتوبة كنص صريح)، دون ملف تعريف ودون اتصال بـ SecureTransport.

<target>:plan

بعد الدمج في main: تخطّط باستخدام flow_plan لكل ملف مضاف أو معدّل داخل مجلد الهدف ⁦flows/<target>/⁩ وتنشر ملخصًا للمراجعة. أما خط التنفيذ الذي يُشغَّل يدويًا على main (Build > Pipelines > Run pipeline) فيخطّط لكل ملفات كل هدف، وتعطي الملفات التي لم تتغير النتيجة noop.

<target>:apply

مهمة يدوية: ينقر معتمِد مخوَّل على ▶ في GitLab لتشغيلها. هذه النقرة هي الموافقة، ولا توجد موافقة غيرها. قبل استدعاء flow_apply يعيد helixflow-ci التحقق من سياق المهمة، ومن العضوية الحالية للمعتمِد في مجموعة الهدف، ومن بصمات الملفات.

<target>:verify

تقارن الهدف بالمستودع بعد التطبيق باستخدام flow_diff، وأي انحراف يُفشل المهمة ويسرد الحقول المختلفة.

تنشر كل مهمة الملفين helixflow-report.json وhelixflow-report.md كمخرجات (artifacts) لمدة 30 يومًا، حتى عند الفشل. لا يحتوي التقرير أبدًا على قيمة سرية.

2. المتطلبات المسبقة

• خادم GitLab مُدار ذاتيًا. اعتُمدت السلسلة على GitLab CE 19.4.1، ولا تشمل هذه النسخة الأولى GitLab.com ولا ميزات Premium.
• جهاز Linux يصل إلى SecureTransport، عليه GitLab Runner بمنفّذ shell: مشغّل quality غير محمي ودون أسرار (الوسم helixflow-quality)، ومشغّل محمي لكل هدف (الوسمان helixflow-nonprod وhelixflow-prod في قالب خط التنفيذ). النظام المعتمد الوحيد هو Ubuntu 24.04 LTS بمعمارية amd64، أما نسخة arm64 فمتوفرة لكنها غير معتمدة.
• حساب نظام مخصص لكل هدف على هذا الجهاز (مثل helixflow-prod): يشغّل مشغّل الهدف ويملك ملف cible.yaml الخاص به ومجلدات HelixFlow للإعداد والحالة والترخيص. لا يقرأ أي حساب هدف ملفات حساب آخر.
• خادم OpenBao، أو خزنة قائمة متوافقة مع واجهة Vault البرمجية، يمكن الوصول إليها من هذا الجهاز.
• مشروعان في GitLab: مشروع flows الذي تحفظ فيه الفرق ملفاتها داخل مجلد كل هدف، ومشروع إدارة منفصل يحتوي ملف خط التنفيذ.
• مجموعة معتمِدين في GitLab لكل هدف، وحساب خدمة في GitLab يقرأ رمزُه read_api، المحفوظ في OpenBao، العضويةَ في هذه المجموعات.

3. تثبيت الملفات التنفيذية على جهاز المشغّلات

نزّل ملف HelixFlow التنفيذي لنظام Linux، وتحقق من بصمته SHA-256 مقابل القيمة المنشورة، ثم ثبّته في موقع ثابت سيشير إليه cible.yaml. التنزيلات

sha256sum helixflow-linux-amd64
sudo install -d -m 0755 /opt/helixflow/bin
sudo install -m 0755 helixflow-linux-amd64 /opt/helixflow/bin/helixflow

على ARM64، استبدل amd64 بـ arm64 في أسماء الملفات.

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

export HELIXFLOW_LICENSE_DIR=/var/lib/helixflow-prod/licenses
/opt/helixflow/bin/helixflow license request --output request.json

بعد الإصدار، انسخ الملف helixflow.lic نفسه إلى كل حساب هدف (خارج license_dir الخاص به، ويملكه ذلك الحساب)، ثم استورده باسم ذلك الحساب (يكتبه الاستيراد في license_dir)، وتحقق منه، ثم احذف النسخة. كرّر ذلك لكل هدف (مثل helixflow-nonprod):

sudo install -o helixflow-prod -g helixflow-prod -m 0600 helixflow.lic /var/lib/helixflow-prod/helixflow.lic
sudo -u helixflow-prod env HELIXFLOW_LICENSE_DIR=/var/lib/helixflow-prod/licenses /opt/helixflow/bin/helixflow license import /var/lib/helixflow-prod/helixflow.lic
sudo rm /var/lib/helixflow-prod/helixflow.lic
sudo -u helixflow-prod env HELIXFLOW_LICENSE_DIR=/var/lib/helixflow-prod/licenses /opt/helixflow/bin/helixflow license status

لا يُنشر helixflow-ci في صفحة التنزيلات: يقدّمه الناشر عند الطلب لنظام Linux بمعماريتي amd64 أو arm64، مع بصمته SHA-256 وقالب خط التنفيذ pipeline.yml. اطلب الإصدار المطابق لإصدار helixflow المثبت. تحقق من البصمة، ثم ضعه في مجلد ضمن PATH لحسابات المشغّلات، لأن خط التنفيذ يستدعيه باسمه. طلب helixflow-ci

sha256sum helixflow-ci-linux-amd64
sudo install -m 0755 helixflow-ci-linux-amd64 /usr/local/bin/helixflow-ci

لا يحتاج helixflow-ci إلى ترخيص، إذ يستخدم MCP الذي يشغّله ترخيصَ حساب الهدف. يرفض helixflow-ci أي MCP لا يعلن القدرات المتوقعة، لذا حدّث الاثنين معًا دائمًا.

4. ضبط GitLab

هذه الإعدادات إلزامية. تشير عبارة «يتحقق منه doctor» إلى ما يتحقق منه helixflow-ci doctor عبر الواجهة البرمجية (الخطوة 8 من هذا القسم)، وتحقق من الباقي بنفسك في GitLab.

• تكون الفرق بدور Developer في مجموعة مشروع flows ويمكنها الدمج في main. يُحجز دور Maintainer للمسؤولين، لأن Maintainer يستطيع تعريف متغيرات CI (مثل BASH_ENV وLD_PRELOAD) تُنفَّذ قبل نص المهمة في الحساب الذي يحصل على الأسرار.
• الحد الأدنى من الدور لتجاوز متغيرات خط التنفيذ: لا أحد. يتحقق منه doctor.
• الفرع main محمي: لا دفع مباشر، والدمج عبر طلبات الدمج فقط. يتحقق منه doctor.
• في Settings > Merge requests: فعّل «Pipelines must succeed». من دونه يبقى طلب الدمج الذي فشلت فيه مهمة quality قابلًا للدمج. يتحقق منه doctor.
• في الصفحة نفسها: ألغِ تفعيل «Skipped pipelines are considered successful»، وإلا دُمج طلب تجاوز خطُّ تنفيذه (التزام ⁦[skip ci]⁩) دون تشغيل quality. يتحقق منه doctor.
• في Settings > CI/CD > CI/CD configuration file لمشروع flows: ملف خط التنفيذ الموجود في مشروع الإدارة (الخطوة 7 من هذا القسم). يتحقق منه doctor.
• يُشارَك مشروع الإدارة مع مجموعة مشروع flows بمستوى Reporter تحديدًا. إن كان أدنى فشل كل خط تنفيذ بالخطأ config_error دون رسالة، وإن كان أعلى استطاعت الفرق التصرف في مشروع الإدارة. يتحقق منه doctor عند تعيين pipeline_config.
• مجموعة معتمِدين لكل هدف، وهي المجموعة التي تتحقق منها مهمة apply للهدف عند النقر. يتحقق منه doctor (وجود المجموعة).
• يكون حساب الخدمة صاحب رمز read_api بدور Guest في كل مجموعة معتمِدين وغير عضو في مجموعة التدفقات: يقرأ عضوية المعتمِدين ولا يشغّل أي مهمة.
• مشغّلات الأهداف محمية ومقفلة على مشروع flows، بوسومها المخصصة ومنفّذ shell، ومشغّل quality غير محمي ولا يصل إلى ملفات أي هدف ولا إلى دوره في OpenBao. لا يتحقق منه doctor.

5. تجهيز OpenBao

تُعلن كل مهمة هدف رمز OIDC من GitLab باسم HELIXFLOW_CI_ID_TOKEN وجمهوره helixflow-ci. يستبدله helixflow-ci برمز خزنة صالح لبضع دقائق عبر طريقة المصادقة JWT في OpenBao. لا تُعلن مهمة quality أي رمز ولا تتواصل مع الخزنة أبدًا.

طريقة JWT

مفعّلة على نقطة التركيب auth_mount المحددة في cible.yaml (jwt-gitlab في المثال) ومضبوطة لقبول الرموز التي يصدرها GitLab الخاص بك.

دور الهدف

دور لكل هدف (القيمة role في cible.yaml) مع bound_audiences: helixflow-ci وقيود bound_claims يجب أن تتطابق كلها: project_id لمشروع flows، و⁦ref: main⁩، و⁦ref_type: branch⁩، و⁦ref_protected: "true"⁩، وenvironment مساويًا لاسم الهدف، وci_config_ref_uri. يبني GitLab هذه الأخيرة من مشروع flows ومن إعداده CI/CD configuration file، مثلًا:

gitlab.example.test/teams/flows//pipeline.yml@helixflow-admin/admin@refs/heads/main

لذلك فإن تغيير ملف إعداد CI/CD لمشروع flows يغلق الوصول إلى الخزنة إلى أن يُحدَّث الدور.

السياسة

قراءة فقط لأسرار الهدف، ولا وصول أبدًا إلى أسرار هدف آخر.

path "helixflow/data/prod/*" { capabilities = ["read"] }

مسارات KV v2

تحت نقطة التركيب kv_mount (helixflow في المثال):

• helixflow/<target>/st — بيانات اعتماد SecureTransport (الحقلان login وpassword)؛
• helixflow/<target>/gitlab — رمز read_api لحساب الخدمة (الحقل token)؛
• helixflow/<target>/flows/ — الأسرار التي تشير إليها التدفقات (الخطوة 9 من هذا القسم).

أدخل هذه الأسرار في OpenBao بنفسك. لا تضع أبدًا بيانات اعتماد SecureTransport أو رمزًا أو كلمة مرور في المستودع أو في متغير CI/CD في GitLab أو في cible.yaml أو في هذا الموقع أو في محادثة.

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

6. وصف الهدف: cible.yaml

ملف واحد لكل هدف، يملكه حساب نظام الهدف وبالصلاحيات 0600 (وإلا رُفض). لا يحتوي أي سر، بل مراجع ومسارات مطلقة فقط.

الموقع الافتراضي، والخيار الذي يحدد موقعًا آخر: /etc/helixflow-ci/<target>/cible.yaml · --config

target: prod
flows_dir: flows/prod
gitlab:
  url: https://gitlab.example.test
  ca_path: /etc/helixflow-ci/prod/gitlab-ca.pem
  branch: main
  flows_project_id: 42
  approver_group_id: 7
  pipeline_config: pipeline.yml@helixflow-admin/admin
helixflow:
  binary: /opt/helixflow/bin/helixflow
  profile: st-prod
  config_dir: /var/lib/helixflow-prod/config
  state_dir: /var/lib/helixflow-prod/state
  license_dir: /var/lib/helixflow-prod/licenses
approval_window: 60m
openbao:
  address: https://openbao.example.test:8200
  ca_path: /etc/helixflow-ci/prod/openbao-ca.pem
  auth_mount: jwt-gitlab
  role: helixflow-prod
  kv_mount: helixflow

target · flows_dir

اسم الهدف ومجلده في مشروع flows، الذي يجب أن يساوي ⁦flows/⁩ متبوعًا باسم الهدف. يبدأ الاسم بحرف لاتيني صغير، تليه أحرف صغيرة أو أرقام أو شرطات، و32 حرفًا كحد أقصى. وهو القيمة التي تُمرَّر إلى الخيار: --target

gitlab.url · gitlab.ca_path · gitlab.branch

عنوان HTTPS لخادم GitLab، ويشير ca_path (اختياري) إلى الجهة التي وقّعت شهادته، أما branch فهو الفرع المحمي، وقيمته الافتراضية main.

flows_project_id · approver_group_id

المعرّفان الرقميان لمشروع flows ولمجموعة معتمِدي الهدف.

pipeline_config

اختياري: القيمة المتوقعة لإعداد CI/CD configuration file. يقارنها doctor بالإعداد الفعلي ويستنتج منها مشروع الإدارة.

helixflow.binary · helixflow.profile

مسار الملف التنفيذي helixflow المثبت في الخطوة 3 من هذا القسم، واسم ملف تعريف HelixFlow الخاص بالهدف.

config_dir · state_dir · license_dir

مجلدات HelixFlow للإعداد والحالة والترخيص الخاصة بحساب الهدف. تُحفظ مجموعات الخطط التي تنتظر الموافقة داخل state_dir.

approval_window

المهلة المتاحة للموافقة بعد التخطيط: بين 5 دقائق و24 ساعة، و60 دقيقة افتراضيًا.

openbao

عنوان HTTPS للخزنة والجهة الموقِّعة لشهادتها، ونقطة تركيب مصادقة JWT، ودور الهدف، ونقطة تركيب KV v2 لأسراره (الخطوة 5 من هذا القسم).

base_url: https://st-prod.example.test:8444
env_class: prod
tls:
  mode: ca
  ca_path: /var/lib/helixflow-prod/config/ca/st-ca.pem
credentials:
  source: env
admin:
  production:
    enabled: true
    admin_actors: [helixflow-prod]
    strict_stop: true
    human_confirmation: false
    write:
      actions: [create, modify]
      families: [account, application, certificate, route, site, subscription, transfer-profile, transfer-site]

7. ربط خط التنفيذ

لا يحتوي مشروع flows على ملف ⁦.gitlab-ci.yml⁩. يوضع القالب pipeline.yml، الذي يُقدَّم عند الطلب مع helixflow-ci، في مشروع الإدارة، ولا تعدّله الفرق. ويشير إليه مشروع flows عبر إعداده CI/CD configuration file بالصيغة ⁦pipeline.yml@<admin group>/<admin project>⁩:

pipeline.yml@helixflow-admin/admin

يعلن القالب هدفين: nonprod (المجلد flows/nonprod، الفئة preprod) وprod (المجلد flows/prod، الفئة prod). ولا يعمل إلا عند طلب دمج أو دفع إلى main أو تشغيل يدوي لخط التنفيذ على main. تحمل هذه الأسطر من القالب الضمانات الموضحة أدناه:

variables:
  GIT_DEPTH: "0"

.target:
  id_tokens:
    HELIXFLOW_CI_ID_TOKEN:
      aud: helixflow-ci

.prod:
  extends: .target
  tags: [helixflow-prod]
  resource_group: helixflow-prod
  variables: { HF_TARGET: prod }

• GIT_DEPTH: "0" يطلب السجل الكامل. مع العمق المحدود الافتراضي في GitLab، تؤدي قاعدة مقارنة قديمة جدًا (دفع عدة التزامات أو طلب دمج طويل) إلى فشل quality وplan (الرمز 2).
• resource_group: helixflow-<target> يمنع خطَّي تنفيذ من الكتابة في الهدف نفسه في الوقت ذاته.
• id_tokens يمنح كل مهمة هدف رمز OIDC الذي يُستبدل برمز OpenBao. وتعلن مهام plan وapply وverify أيضًا بيئة هدفها، التي يتحقق منها قيد environment في الدور.

8. التحقق من التثبيت باستخدام doctor

بعد كل تثبيت أو تعديل، شغّل doctor خارج أي مهمة، في جلسة لحساب الهدف. يكتفي بالقراءة ولا يكتب تقريرًا.

helixflow-ci doctor --target prod --gitlab-token-file ./gitlab-read-token

دون رمز GitLab، يتحقق من:

• وجود الملف التنفيذي helixflow وصلاحية الترخيص؛
• أن MCP يبدأ ويعلن القدرات المتوقعة؛
• أن ملف التعريف صارم دون سؤال بشري، وأن flow_apply مسموح فيه لحساب الهدف (ويُسمّى أي رفض بمفتاحه policy_key)؛
• أن OpenBao يستجيب وغير مختوم.

للتحقق أيضًا من إعدادات GitLab الموسومة «يتحقق منه doctor» في الخطوة 4 من هذا القسم، أضف الخيار: --gitlab-token-file

يحتوي الملف، بالصلاحيات 0600، رمز read_api يجب أن يستطيع قراءة مشروع flows ومشروع الإدارة ومجموعة المعتمِدين، ولا يكفي رمز حساب الخدمة المحفوظ في OpenBao، ولم يُقَس بعدُ أدنى دور في GitLab يكفي لذلك. احذف الملف بعد تشغيل doctor، أو استخدم رمزًا قصير الأجل ثم ألغه. ومن دون هذا الخيار يذكر doctor ذلك ويتخطى هذه الفحوص.

يبدأ كل سطر بـ OK أو KO أو ⁦--⁩ (فحص لم يُنفَّذ). تكفي نتيجة KO واحدة ليخرج doctor بالرمز 1. لا يقرأ doctor بيانات اعتماد SecureTransport من الخزنة، فأول مهمة plan هي التي تختبرها.

9. العمل اليومي

1. اكتب مستند تدفق YAML أو عدّله على فرع، مباشرة داخل ⁦flows/<target>/⁩ (دون مجلد فرعي) وبالامتداد ⁦.yaml⁩ أو ⁦.yml⁩، ثم افتح طلب دمج. ويعني الانتقال إلى الإنتاج نسخ الملف إلى ⁦flows/prod/⁩ عبر طلب دمج.
2. تفحص quality طلب الدمج دون اتصال. وعند الفشل يبقى طلب الدمج محظورًا ويسمّي التقرير الملف والحقل والقاعدة.
3. بعد الدمج في main تنشر مهمة plan للهدف ملخصها: سطر لكل كائن وإجراء، والعدّادات، والموعد النهائي للموافقة. اقرأه قبل الموافقة، وتعني عبارة «لا شيء للتطبيق» أن كل النتائج noop.
4. للموافقة، ينقر عضو في مجموعة المعتمِدين على ▶ في مهمة apply للهدف. تعتمد النقرة مجموعة الخطط الناتجة عن آخر مهمة plan ناجحة في خط التنفيذ هذا، وإعادة تشغيل plan تستبدلها، فاقرأ حينها أحدث تقرير.
5. ثم تقارن مهمة verify الهدف بالمستودع، وأي انحراف يُفشلها ويسرد الحقول المختلفة.

تنتهي صلاحية الخطة غير المعتمدة عند الموعد الذي يحدده approval_window (24 ساعة كحد أقصى). وترفض apply أيضًا الخطة المتقادمة أو المستهلكة أو التي تغيّر التزامها أو أحد ملفاتها أو أحد أسرارها. في هذه الحالات لا يُكتب شيء: أعد تشغيل مهمة plan.

الإشارة إلى سرّ في تدفق

لا يُكتب السر أبدًا كنص صريح في تدفق. ضع مرجعًا بالصيغة ⁦${secret:<path>#<field>}⁩ تحت مفتاح سري (اسم يحتوي password أو secret أو token…)، ويكون المسار نسبيًا إلى ⁦helixflow/<target>/flows/⁩ في الخزنة.

partnerPassword: ${secret:pesit/partner-a#password}

ترفض quality القيمة الصريحة تحت مفتاح سري، والمرجع تحت أي مفتاح آخر. تُحَلّ المراجع عند التخطيط ثم مجددًا عند التطبيق، في الذاكرة: لا يُكتب المستند الناتج على القرص أبدًا، ولا تظهر أي قيمة محلولة في تقرير أو سجل.

10. حل مشكلات السلسلة

الرمز 0 · نجاح

طُبّق كل شيء، أو أن نتائج مجموعة الخطط كلها noop.

الرمز 1 · رفض أو فشل معروف

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

الرمز 2 · إعداد غير صالح

ملف cible.yaml غير مقروء أو مشوّه أو بصلاحيات غير 0600 أو يحتوي مسارًا نسبيًا، أو خيار ناقص أو مشوّه، أو جهة TLS غير مقروءة، أو مستودع Git غير مقروء.

الرمز 3 · نتيجة غير مؤكدة

لا يعرف helixflow-ci ما الذي كُتب في الهدف (ضاعت استجابة MCP أو لم يُؤكَّد التنفيذ). يحظر MCP الهدف (execution.pending_reconciliation) ولا يُعاد تنفيذ أي شيء تلقائيًا.

فشل ملف من بين عدة ملفات

تتوقف apply عند أول فشل، ويميّز التقرير بين الملفات المطبّقة والفاشلة وغير المجرَّبة. أعد تشغيل (Retry) مهمة plan ثم انقر apply في خط التنفيذ نفسه، فتعطي الملفات المطبّقة سابقًا النتيجة noop. ويصلح أيضًا خط تنفيذ يُشغَّل يدويًا على main.

المطابقة بعد نتيجة غير مؤكدة

بعد الرمز 3، يطابق مسؤول التشغيل الهدف، وليس خط التنفيذ:

1. دوّن قيمة execution_ref للملف المعني من helixflow-report.md.
2. اقرأ execution_status على MCP، بمساعدك المعتاد أو بعميل MCP مباشر.
3. تحقق من الحالة الفعلية في SecureTransport، ثم استدعِ execution_reconcile لرفع الحظر عن الهدف.
4. بعد ذلك فقط، شغّل خط تنفيذ جديدًا للتخطيط والتطبيق.

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