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

Woodpecker CI: خط CI/CD خفيف بجانب Gitea على سيرفرك

نبني خطاً يختبر الكود ويرفع Docker Image من وسم محمي، مع إحدى عشرة رسالة خطأ حقيقية في الطريق، وتجربة سحب فيها مطور توكن الخط من السجل.

Woodpecker CI: خط CI/CD خفيف بجانب Gitea على سيرفرك

فريق صغير من ثلاثة مطورين يبني واجهة برمجية لمتجر يبيع طلبات التموين للمطاعم، وكل الكود عندهم على Gitea في سيرفر داخلي كما شرحنا في Gitea: خادم Git خاص لفريقك. وقد بدأوا مع Gitea Actions كما في Gitea Actions، ولكن بعد أشهر ظهرت عندهم ثلاثة أسئلة: أول خطوة في كل خط هي actions/checkout، وهي كود JavaScript ينزل من خارج الشركة ويحتاج Node داخل كل Image يستخدمونها، والمسؤول عن الأمن يسأل من يراجع هذه الخطوات الجاهزة ومن يضمن أن الوسم الذي يشيرون إليه لم يتغير، ومدير التقنية يريد أن يبقى خط CI مستقلاً عن منصة الكود، لأنهم يفكرون في الانتقال يوماً إلى Forgejo أو GitLab ولا يريدون إعادة كتابة كل الخطوط. فاقترح أحدهم أن يجربوا Woodpecker CI، وهو خط CI/CD مفتوح المصدر، كل خطوة فيه Container تنفذ أوامر عادية، ويعمل مع Gitea وForgejo وGitLab وGitHub وغيرها.

وفي هذا المقال سوف نبني ما بناه الفريق خطوة بخطوة على جهاز واحد فيه Docker فقط: Gitea بالإصدار 28.3.0، وWoodpecker بالإصدار 3.20.1، وخط يختبر الكود مع قاعدة PostgreSQL حقيقية في كل دفع Push، ويبني Docker Image ويرفعها إلى Registry عند كل وسم إصدار. ولن نعرض النسخة النظيفة فقط، فقد ظهرت لنا في الطريق إحدى عشرة رسالة خطأ حقيقية، وكل واحدة منها تعلمك شيئاً عن طريقة عمل الأداة، ثم جربنا ما يخاف منه المسؤول عن الأمن فعلاً: مطور يسحب سر الخط من سجل التشغيل. وقد شرحنا مفهوم CI/CD نفسه في مفهوم CI/CD للمبتدئين، فلن نعيده هنا. وسوف نناقش في هذا المقال ما يلي:

  • من أين جاء Woodpecker، ولماذا تختاره فرق تستخدم Gitea بدلاً من Gitea Actions أحياناً.
  • كيف يعمل من الداخل: السيرفر Server والوكيل Agent والطابور Queue، وكيف تتحول ملفات YAML إلى Containers.
  • المختبر كاملاً: ملف Docker Compose، وتطبيق OAuth2 في Gitea، وتفعيل المستودع.
  • ثلاث مشاكل قبل أول تشغيل: Webhook يرفضه Gitea، وClone من عنوان خاطئ، وخطوة لا تعرف اسم السيرفر.
  • ملف الخط سطراً بسطر: خطوات Steps وخدمات Services وأكثر من ملف Workflow.
  • بناء ال Image ورفعها: الإضافات Plugins، ولماذا تحتاج بعضها صلاحيات Privileged، وسلسلة الأخطاء التي وصلت بنا إلى تصميم أفضل.
  • الأسرار Secrets: كيف خرج التوكن من السجل رغم الإخفاء، وكيف منعناه بوسوم محمية.
  • ماذا يحدث إذا توقف الوكيل في منتصف الخط، وتشغيل الخط على جهازك قبل الدفع، ثم الأخطاء الشائعة وقائمة تحقق.

من أين جاء Woodpecker؟ Drone Fork

قبل Woodpecker كان هناك Drone، وهو خط CI مبني على فكرة بسيطة جداً في وقتها: كل خطوة في الخط Container، والخط كله ملف YAML في المستودع. وبعد الإصدار 0.8 تغيرت رخصة Drone من Apache 2.0 إلى رخصة تجارية، فأخذ أحد المساهمين آخر نسخة حرة منه وبدأ مشروعاً منفصلاً، وأول Commit في هذا المشروع كان في 3 أبريل 2019، وأول إصدار v0.8.91 بعده بثلاثة أيام، ثم تغير اسم المشروع إلى Woodpecker في 27 أغسطس 2019، كما تذكر صفحة المشروع. والمشروع اليوم ما زال برخصة Apache 2.0، ويديره مجتمع من المساهمين وليس شركة، ونسخته الثالثة هي الحالية، وآخر إصدار وقت كتابة المقال هو v3.20.1 الصادر في 29 أكتوبر 2026.

وقد يتساءل البعض: إذا كان Gitea فيه Actions، فلماذا نحتاج أداة أخرى؟ والإجابة أن الأداتين تختلفان في الفلسفة أكثر من الميزات. فخط Gitea Actions مكتوب بصيغة GitHub Actions، وقوته في أنك تستطيع استخدام آلاف الخطوات الجاهزة المكتوبة لـ GitHub، ونقطة ضعفه هي القوة نفسها: كل خطوة جاهزة كود يكتبه غيرك ويتغير خلف وسم، وأغلبها يحتاج Node. أما Woodpecker فالخطوة فيه إما أوامر Shell داخل Image تختارها أنت، وإما إضافة Plugin، والإضافة نفسها ليست إلا Image تقرأ إعداداتها من متغيرات بيئة، فلا توجد طبقة JavaScript بينك وبين ما يحدث، وما تقرؤه في ملف YAML هو ما ينفذ. وهو كذلك منفصل عن منصة الكود، فيتصل بها عبر OAuth2 والـ Webhooks فقط، وإذا انتقلت من Gitea إلى Forgejo تغير إعداد الاتصال في السيرفر وبقيت ملفات الخطوط كما هي.

وبالطبع لهذا ثمن، فلا يوجد سوق كبير للخطوات الجاهزة، وكل شيء تكتبه بنفسك بأوامر عادية، وبعض الأشياء التي تأتي جاهزة في Actions، مثل ذاكرة التخزين Cache بين التشغيلات، تحتاج في Woodpecker إلى إضافة أو إلى Volume. وسوف نقارن الأدوات الثلاث المشهورة على الخط نفسه بالأرقام في مقال قادم بإذن الله، أما هنا فنركز على Woodpecker وحده.

كيف يعمل من الداخل؟ Server, Agent and Queue

يتكون Woodpecker من برنامجين صغيرين. الأول هو السيرفر woodpecker-server، وهو الذي يتحدث مع Gitea، ويعرض الواجهة، ويحفظ الخطوط والسجلات والأسرار في قاعدة بيانات، وقاعدته الافتراضية SQLite مدمجة، ويدعم بدلاً منها PostgreSQL أو MySQL كما في توثيق السيرفر. والثاني هو الوكيل woodpecker-agent، وهو الذي ينفذ الخطوط فعلاً، ويعمل على جهاز البناء، وقد يكون جهازاً آخر غير جهاز السيرفر، ويمكن أن يكون عندك أكثر من وكيل. والصورة التالية تبين ما يحدث من لحظة الدفع إلى آخر خطوة:

رسم يبين المطور dev1 يدفع إلى Gitea 28.3.0، فيرسل Gitea طلب Webhook إلى woodpecker-server 3.20.1 الذي يقرأ ملفات .woodpecker من Gitea ويضع المهام في الطابور، ثم يتصل woodpecker-agent بالسيرفر عبر gRPC على المنفذ 9000 ويسحب المهمة، وينشئ على Docker خطوات clone بإضافة plugin-git 2.11.0 وخدمة db من postgres:18-alpine وخطوة test من python:3.13-alpine تشترك في Volume فيه الكود وشبكة خاصة بالمهمة، ثم يرسل السجلات إلى السيرفر الذي يكتب حالة ال Commit في Gitea
من الدفع إلى خطوات في Containers: الوكيل هو الذي يسأل السيرفر عن المهام
  1. يدفع المطور إلى Gitea، فيرسل Gitea طلباً إلى عنوان /api/hook في السيرفر، وهذا هو ال Webhook الذي أنشأه Woodpecker في المستودع عندما فعلناه.
  2. يقرأ السيرفر من Gitea كل الملفات داخل مجلد .woodpecker/ في ال Commit نفسه، ويحول كل ملف إلى مهمة Workflow، ويطبق الشروط when على كل مهمة وكل خطوة، ويفحصها بأداة الفحص Linter، ثم يضع المهام الجاهزة في الطابور.
  3. الوكيل هو الذي يتصل بالسيرفر عبر gRPC على المنفذ 9000، ويسأله عن مهمة تناسبه، أي أن السيرفر لا يحتاج إلى الوصول إلى جهاز البناء، فتستطيع أن تضع الوكيل خلف جدار حماية Firewall لا يقبل أي اتصال داخل، وهذا نفس ما رأيناه مع Gitea Runner.
  4. عندما يستلم الوكيل مهمة، ينشئ لها في Docker شبكة خاصة وVolume للكود، ثم يشغل خطوة clone أولاً، وهي إضافة plugin-git التي يضيفها Woodpecker وحده دون أن تكتبها، ثم الخدمات Services في الخلفية، ثم الخطوات Steps واحدة بعد الأخرى، وكل خطوة Container مستقل يرى مجلد الكود نفسه.
  5. يرسل الوكيل السجلات إلى السيرفر أثناء التنفيذ، وفي النهاية يكتب السيرفر حالة ال Commit في Gitea، فتظهر علامة النجاح أو الفشل بجانب ال Commit وطلب الدمج.

وعدد المهام التي ينفذها الوكيل في الوقت نفسه يحدده WOODPECKER_MAX_WORKFLOWS، وقيمته الافتراضية 1 كما في توثيق الوكيل، وجعلناه 2 في المختبر لأن عندنا ملفين يعملان معاً. وطريقة تنفيذ الخطوات تسمى الخلفية Backend، وهي هنا Docker عبر docker.sock، وهناك أيضاً خلفية Kubernetes تنشئ Pod لكل خطوة، وخلفية Local تنفذ الأوامر على الجهاز نفسه دون Containers. وانتبه هنا إلى أن الوكيل الذي يملك docker.sock يملك الجهاز كله عملياً، لأن من يستطيع أن يطلب من Docker تشغيل Container يستطيع أن يطلب Container بصلاحيات كاملة، ولهذا يضع Woodpecker حدوداً على ما تستطيع الخطوة أن تطلبه، كما سوف نرى عند الإضافات Privileged.

المختبر: Gitea مع Woodpecker في Docker Compose

كل ما في المختبر يبدأ اسمه بـ wr-ci- حتى نحذفه بالاسم في النهاية، والمنافذ مربوطة بالعنوان 127.0.0.1 فقط فلا يراها أحد على الشبكة. وقد استخدمنا أسماء ال Containers نفسها عناوين لكل شيء، مثل http://wr-ci-gitea:3301، لأن المتصفح والسيرفر وخطوات الخط يجب أن يروا جميعاً العنوان نفسه، وفي المختبر جعلنا المتصفح يحول هذه الأسماء إلى 127.0.0.1، أما في سيرفر حقيقي فيكون عندك اسم نطاق مثل git.example.com وشهادة TLS، ولا تحتاج إلى هذا التحايل. وهذا ملف compose.yaml بشكله النهائي بعد كل الإصلاحات التي سوف نمر بها:

name: wr-ci
services:
  gitea:
    image: gitea/gitea:28.3.0
    container_name: wr-ci-gitea
    environment:
      GITEA__server__HTTP_PORT: "3301"
      GITEA__server__ROOT_URL: http://wr-ci-gitea:3301/
      GITEA__server__DISABLE_SSH: "true"
      GITEA__server__PUBLIC_URL_DETECTION: legacy
      GITEA__database__DB_TYPE: sqlite3
      GITEA__security__INSTALL_LOCK: "true"
      GITEA__service__DISABLE_REGISTRATION: "true"
      GITEA__security__ALLOWED_HOST_LIST: 172.31.231.0/24:8301
    volumes:
      - wr-ci-gitea-data:/data
    ports:
      - "127.0.0.1:3301:3301"
    networks: [wr-ci-net]
  woodpecker:
    image: woodpeckerci/woodpecker-server:v3.20.1
    container_name: wr-ci-woodpecker
    environment:
      WOODPECKER_HOST: http://wr-ci-woodpecker:8301
      WOODPECKER_SERVER_ADDR: ":8301"
      WOODPECKER_ADMIN: ops
      WOODPECKER_GITEA: "true"
      WOODPECKER_GITEA_URL: http://wr-ci-gitea:3301
      WOODPECKER_GITEA_CLIENT: ${WP_CLIENT}
      WOODPECKER_GITEA_SECRET: ${WP_SECRET}
      WOODPECKER_PLUGINS_PRIVILEGED: woodpeckerci/plugin-docker-buildx:6.1.2
      WOODPECKER_AGENT_SECRET: ${WP_AGENT_SECRET}
    volumes:
      - wr-ci-wp-data:/var/lib/woodpecker
    ports:
      - "127.0.0.1:8301:8301"
    networks: [wr-ci-net]
  agent:
    image: woodpeckerci/woodpecker-agent:v3.20.1
    container_name: wr-ci-wp-agent
    environment:
      WOODPECKER_SERVER: wr-ci-woodpecker:9000
      WOODPECKER_AGENT_SECRET: ${WP_AGENT_SECRET}
      WOODPECKER_MAX_WORKFLOWS: "2"
      WOODPECKER_BACKEND_DOCKER_NETWORK: wr-ci-net
      WOODPECKER_BACKEND_DOCKER_VOLUMES: wr-ci-certs:/etc/docker/certs.d:ro
    volumes:
      - wr-ci-wp-agent:/etc/woodpecker
      - /var/run/docker.sock:/var/run/docker.sock
    networks: [wr-ci-net]
    depends_on: [woodpecker]
  registry:
    image: caddy:2.11.8-alpine
    container_name: wr-ci-registry
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - wr-ci-caddy:/data
    networks:
      wr-ci-net:
        aliases: [registry.wr-ci.lan]
networks:
  wr-ci-net:
    name: wr-ci-net
    ipam:
      config:
        - subnet: 172.31.231.0/24
volumes:
  wr-ci-gitea-data:
    name: wr-ci-gitea-data
  wr-ci-wp-data:
    name: wr-ci-wp-data
  wr-ci-wp-agent:
    name: wr-ci-wp-agent
  wr-ci-caddy:
    name: wr-ci-caddy
  wr-ci-certs:
    name: wr-ci-certs

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

  • WOODPECKER_HOST هو العنوان الذي يفتحه المتصفح، ومنه يبني Woodpecker عنوان ال Webhook وعنوان العودة من Gitea بعد الدخول، لذلك يجب أن يكون العنوان الذي يصل إليه Gitea والمستخدم معاً.
  • WOODPECKER_GITEA_URL هو عنوان Gitea كما يراه السيرفر، وWOODPECKER_ADMIN يجعل المستخدم ops مديراً في Woodpecker.
  • WOODPECKER_AGENT_SECRET سر مشترك بين السيرفر والوكيل، ومن يعرفه يستطيع أن يسجل وكيلاً عنده ويستلم مهامك وأسرارها، فعامله كأي كلمة مرور، وقد ولدناه بـ 32 بايت عشوائية.
  • المتغيرات الثلاثة بين ${…} تأتي من ملف .env منفصل لا يدخل المستودع، ونمرره بالخيار --env-file.
  • بقية الإعدادات، مثل ALLOWED_HOST_LIST وPUBLIC_URL_DETECTION وBACKEND_DOCKER_NETWORK وال Registry في آخر الملف، لم تكن في النسخة الأولى، وكل واحد منها جاء بعد رسالة خطأ سوف نراها بعد قليل.

تطبيق OAuth2 في Gitea: Login Flow

لا يوجد في Woodpecker حساب أو كلمة مرور خاصة به، فالمستخدم يدخل بحساب Gitea عبر OAuth2، وهذا هو السبب أن كل مستخدم في Woodpecker هو مستخدم في Gitea وبالصلاحيات نفسها على المستودعات. لذلك نبدأ بتشغيل Gitea وحده، وننشئ المستخدمين، ثم نسجل Woodpecker كتطبيق OAuth2 عند المستخدم ops، وعنوان العودة يجب أن ينتهي بـ /authorize كما في توثيق الربط مع Gitea:

docker compose up -d gitea
docker exec -u git wr-ci-gitea gitea admin user create --admin --username ops \
  --password 'Lab-Ops-2026!' --email [email protected] --must-change-password=false
docker exec -u git wr-ci-gitea gitea admin user create --username dev1 \
  --password 'Lab-Dev1-2026!' --email [email protected] --must-change-password=false

curl -s -u 'ops:Lab-Ops-2026!' -H 'Content-Type: application/json' \
  -X POST http://127.0.0.1:3301/api/v1/user/applications/oauth2 \
  -d '{"name":"woodpecker","redirect_uris":["http://wr-ci-woodpecker:8301/authorize"],"confidential_client":true}'

يرجع الطلب الأخير client_id وclient_secret، فنضعهما في ملف .env مع سر الوكيل، ثم نشغل البقية بالأمر docker compose --env-file wp.env up -d. وعند أول دخول إلى Woodpecker يضغط المستخدم على زر Gitea في صفحة الدخول، فيحوله Woodpecker إلى صفحة الموافقة في Gitea، وهي الصفحة التالية:

صفحة Gitea 28.3.0 بعنوان Authorize woodpecker to access your account تقول إن التطبيق سوف يستطيع قراءة وكتابة كل معلومات الحساب بما فيها المستودعات الخاصة والمنظمات، وإن المستخدم سوف يعود إلى http://wr-ci-woodpecker:8301/authorize، وفيها زر Authorize Application
صفحة الموافقة في Gitea: لاحظ حجم الصلاحية التي يطلبها التطبيق

اقرأ هذه الصفحة جيداً قبل أن تضغط الزر، لأنها تقول بوضوح إن التطبيق سوف يستطيع «قراءة وكتابة كل معلومات حسابك، بما فيها المستودعات الخاصة والمنظمات». وهذا يعني أن سيرفر Woodpecker يحفظ عنده توكن لكل مستخدم دخل إليه بهذه الصلاحية الواسعة، ويستخدمه ليقرأ ملفات الخطوط ويكتب حالة ال Commits وينشئ ال Webhooks. لذلك احم سيرفر Woodpecker وقاعدة بياناته كما تحمي Gitea نفسه، وخذ نسخة احتياطية منهما معاً، ولا تفتح واجهته للعموم إلا خلف Reverse Proxy بشهادة TLS. وبعد الموافقة يعود المستخدم إلى Woodpecker، ومن صفحة المستودعات يضغط زر إضافة مستودع ويختار store/orders-api، أو يطلب ذلك من الواجهة البرمجية API بالتوكن الشخصي الذي يجده في إعدادات حسابه:

curl -s -H "Authorization: Bearer $WP_TOKEN" "http://127.0.0.1:8301/api/user/repos?all=true"
curl -s -H "Authorization: Bearer $WP_TOKEN" -X POST "http://127.0.0.1:8301/api/repos?forge_remote_id=1"

والمخرج سوف يكون كما يلي، وقد اختصرنا الأسطر الطويلة:

1 store/orders-api false
{"id":1,"forge_id":1,"forge_remote_id":"1","org_id":2,"owner":"store","name":"orders-api",
 "full_name":"store/orders-api","clone_url":"http://wr-ci-gitea:3301/store/orders-api.git",
 "default_branch":"main","pr_enabled":true,"timeout":60,"visibility":"private","private":true,
 "trusted":{"network":false,"volumes":false,"security":false},"require_approval":"forks",
 "active":true,"allow_pr":true,"allow_deploy":false,"config_file":"",
 "cancel_previous_pipeline_events":["push","pull_request"], ...}

في المخرج أعلاه لاحظ التالي:

  • timeout":60 هي المهلة القصوى لكل خط بالدقائق، وسوف نعود إليها عندما يتوقف الوكيل في منتصف الخط.
  • trusted كلها false، أي أن خطوات هذا المستودع لا تستطيع أن تربط Volumes من الجهاز، ولا أن تستخدم شبكة الجهاز، ولا أن تطلب صلاحيات أمنية خاصة، وهذا هو الوضع الصحيح الافتراضي.
  • require_approval":"forks" يعني أن الخطوط القادمة من نسخ Forks يملكها آخرون لا تعمل حتى يوافق عليها مسؤول، كما في إعدادات المشروع.
  • cancel_previous_pipeline_events يعني أن دفعة جديدة إلى الفرع نفسه تلغي الخط القديم الذي ما زال يعمل، فلا يضيع الوكيل وقته على Commit لم يعد أحد يهتم به.

ثلاث مشاكل قبل أول تشغيل: Webhook, Clone URL, DNS

التطبيق نفسه بسيط: دالة تحسب مجموع الطلب مع ضريبة القيمة المضافة بنسبة 15%، ودالة تحفظ الطلب في PostgreSQL، وأربعة اختبارات بأداة pytest، منها اختبار يحتاج قاعدة بيانات حقيقية، وملف الخط الأول هو .woodpecker/test.yaml الذي سوف نشرحه بعد قليل. دفعنا الكود ثم Commit صغيراً، وانتظرنا أن يظهر الخط في Woodpecker، فلم يظهر شيء.

ال Webhook لا يصل: Gitea Egress Policy

عندما لا يبدأ الخط بعد الدفع، فأول مكان تنظر فيه هو سجل Gitea، لأنه هو الذي يرسل ال Webhook، وكان فيه السطر التالي:

services/webhook/webhook.go:99:handler() [E] Unable to deliver webhook task[1]: ... due to error in http client: Post "http://wr-ci-woodpecker:8301/api/hook?access_token=...": dial tcp 172.21.0.3:8301: denied by egress policy: wr-ci-woodpecker(172.21.0.3) needs an explicit IP allow entry (non-public address)

والسبب أن Gitea يمنع أي طلب صادر منه إلى عنوان خاص Private Address، مثل عناوين شبكات Docker الداخلية أو الشبكة المحلية، حتى لا يستخدم أحد ال Webhooks ليجعل Gitea يطلب عناوين داخلية لا يفترض أن تصل إليها، وهذا الهجوم يسمى SSRF. وفي Gitea 28 يتحكم في ذلك الإعدادان EGRESS_MODE وALLOWED_HOST_LIST في قسم [security]، كما في قائمة إعدادات Gitea. فأضفنا اسم السيرفر wr-ci-woodpecker:8301 إلى القائمة، وأعدنا اختبار ال Webhook، فظهر الخطأ نفسه حرفياً. والتفصيل الذي يغيب عن كثيرين أن التوثيق يقول إن العناوين الخاصة وعناوين Loopback تحتاج إلى مدخل من نوع الشبكات المعرفة مسبقاً مثل private، أو مدخل CIDR، ولا يكفي اسم الجهاز، لأن الاسم قد يتغير ما يشير إليه، ولذلك قالت الرسالة «needs an explicit IP allow entry».

والحل الذي يناسب هذا الأمان هو أصغر مدى ممكن، وليس الكلمة private التي تفتح كل الشبكات الخاصة، فأعطينا شبكة Docker مدى ثابتاً 172.31.231.0/24 في ملف Compose، لأن Docker يختار مدى مختلفاً كل مرة إذا لم تحدده، ثم سمحنا بهذا المدى على المنفذ 8301 فقط. وفي سيرفر حقيقي يكون Woodpecker غالباً على اسم نطاق وعنوان عام خلف Reverse Proxy، فلا تحتاج إلى هذا الإعداد أصلاً، أما إذا كان على الشبكة الداخلية فاكتب عنوانه أو مداه الصغير بالمنفذ.

ال Clone من عنوان خاطئ: PUBLIC_URL_DETECTION

بعد إصلاح ال Webhook ظهر أول خط، وفشل في أول خطوة، وهذا سجل خطوة clone:

pipeline #1 event=push branch=main status=failure commit=d0a19dd0 duration=9s
workflow test: failure
  step clone (clone) failure exit=128 8s
  step db (service) skipped exit=0
  step test (commands) skipped exit=0

--- test / clone
▶  git init --object-format sha1 -b main
Initialized empty Git repository in /woodpecker/src/127.0.0.1/store/orders-api/.git/
▶  git config --global --replace-all safe.directory /woodpecker/src/127.0.0.1/store/orders-api
▶  git remote add origin http://127.0.0.1:3301/store/orders-api.git
▶  git fetch --no-tags --depth=1 --filter=tree:0 origin +d0a19dd087ff44b5dd7b4d182cf7f135688ac945:
fatal: unable to access 'http://127.0.0.1:3301/store/orders-api.git/': Failed to connect to 127.0.0.1:3301 after 0 ms: Could not connect to server
exit status 128

لاحظ العنوان الذي حاولت الخطوة أن تسحب منه: 127.0.0.1:3301، وليس wr-ci-gitea:3301 المكتوب في ROOT_URL. ومن أين جاء هذا العنوان؟ من طريقتنا في الدفع، فقد دفعنا من الجهاز إلى http://127.0.0.1:3301، وGitea في الإعداد الافتراضي PUBLIC_URL_DETECTION=auto يبني الروابط من ترويسة Host في الطلب الذي يتعامل معه، فكتب في ال Webhook رابط Clone بالعنوان الذي جاء منه الدفع، وصدقه Woodpecker. وهذا السلوك مفيد عندما يفتح الناس Gitea من أكثر من عنوان، ولكنه في سيرفر CI يعني أن نجاح الخط يعتمد على العنوان الذي استخدمه المطور في الدفع. والحل أن نجعل Gitea يستخدم ROOT_URL دائماً بالقيمة legacy، فلا يستخدم ترويسة Host إلا إذا جاء الطلب من Reverse Proxy يرسل X-Forwarded-Proto. وفي سيرفر حقيقي يدفع الجميع إلى git.example.com فلا تظهر المشكلة، ولكن تذكرها إذا رأيت خطوة Clone تحاول الوصول إلى عنوان داخلي أو إلى localhost.

الخطوة لا تعرف اسم Gitea: Backend Docker Network

بعد هذا الإعداد تغير الخطأ، وهذا دائماً علامة جيدة:

▶  git remote add origin http://wr-ci-gitea:3301/store/orders-api.git
▶  git fetch --no-tags --depth=1 --filter=tree:0 origin +9dac4966ba0d83ee120a1f1155eb81e0527db1eb:
fatal: unable to access 'http://wr-ci-gitea:3301/store/orders-api.git/': Could not resolve host: wr-ci-gitea (Domain name not found)
exit status 128

العنوان صحيح الآن، ولكن خطوة Clone لا تعرف ما هو wr-ci-gitea. والسبب ما ذكرناه في وصف المعمارية: الوكيل ينشئ لكل مهمة شبكة Docker خاصة بها، والأسماء في Docker لا تعمل إلا داخل الشبكة نفسها كما شرحنا في شبكات Docker، وGitea على شبكة wr-ci-net وليس على شبكة المهمة. فأضفنا إلى الوكيل WOODPECKER_BACKEND_DOCKER_NETWORK=wr-ci-net، فأصبح كل Container ينشئه الوكيل متصلاً بهذه الشبكة أيضاً، ثم أعدنا تشغيل الخط من زر Restart، فنجح.

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

أول خط أخضر: Steps and Services

هذا هو ملف .woodpecker/test.yaml بشكله النهائي، والصيغة كاملة في توثيق صيغة الخط:

when:
  - event: [push, pull_request, tag]

services:
  - name: db
    image: postgres:18-alpine
    environment:
      POSTGRES_PASSWORD: test
      POSTGRES_DB: orders

steps:
  - name: test
    image: python:3.13-alpine
    environment:
      DATABASE_URL: postgresql://postgres:test@db:5432/orders
    commands:
      - pip install --quiet -r requirements.txt
      - python -m pytest -q

في الملف أعلاه لاحظ التالي:

  • when في أعلى الملف شرط على المهمة كلها، أي أن هذا الملف يعمل عند الدفع وعند طلب الدمج وعند إنشاء وسم، ولا يعمل مثلاً عند التشغيل اليدوي Manual أو المجدول Cron. وتستطيع أن تضع when على خطوة واحدة أيضاً، وأن تشترط الفرع أو المسار الذي تغير أو الحالة.
  • services هي Containers تعمل في الخلفية طوال المهمة، وتصل إليها الخطوات باسمها، ولهذا كتبنا db في عنوان قاعدة البيانات، كما في توثيق الخدمات.
  • steps هي الخطوات بالترتيب، وكل خطوة Image وأوامر. ويضع Woodpecker الأوامر في سكربت Shell وينفذه داخل ال Container، وإذا فشل أي أمر توقفت الخطوة وفشل الخط.
  • لا توجد خطوة Checkout، فخطوة clone يضيفها Woodpecker وحده في أول كل مهمة، وهي التي رأيناها تفشل مرتين.

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

pipeline #3 event=push branch=main status=success commit=9dac4966 duration=24s
workflow test: success
  step clone (clone) success exit=0 2s
  step db (service) success exit=0 21s
  step test (commands) success exit=0 19s

--- test / clone
▶  git fetch --no-tags --depth=1 --filter=tree:0 origin +9dac4966ba0d83ee120a1f1155eb81e0527db1eb:
From http://wr-ci-gitea:3301/store/orders-api
 * branch            9dac4966ba0d83ee120a1f1155eb81e0527db1eb -> FETCH_HEAD
▶  git reset --hard -q 9dac4966ba0d83ee120a1f1155eb81e0527db1eb

--- test / db
2026-11-05 08:30:36.157 UTC [45] LOG:  starting PostgreSQL 18.6 on x86_64-pc-linux-musl, compiled by gcc (Alpine 15.2.0) 15.2.0, 64-bit
2026-11-05 08:30:36.185 UTC [45] LOG:  database system is ready to accept connections

--- test / test
▶  pip install --quiet -r requirements.txt
WARNING: Running pip as the 'root' user can result in broken permissions ...
▶  python -m pytest -q
....                                                                     [100%]
4 passed in 0.42s

في المخرج أعلاه لاحظ التالي:

  • خطوة Clone تسحب Commit واحداً بعمق 1 --depth=1، وليس تاريخ المستودع كله، ولهذا استغرقت ثانيتين، وإذا احتاجت خطوة لاحقة إلى التاريخ، مثل أداة تحسب الإصدار من الوسوم، فعليك أن تطلب ذلك في إعداد خطوة Clone.
  • مدة الخدمة 21 ثانية لأنها تعمل حتى تنتهي المهمة، وليس لأن قاعدة البيانات احتاجت 21 ثانية لتبدأ، فقد كانت جاهزة بعد ثوان من تشغيلها كما يقول سطر ready to accept connections.
  • الاختبار الذي يحتاج قاعدة البيانات نجح دون أن ننتظر الخدمة صراحة، والسبب أن pip install استغرق معظم الوقت فكانت القاعدة جاهزة قبله. ولا تعتمد على هذا الحظ، فإذا استخدمت Image فيها المكتبات مسبقاً فسوف يبدأ الاختبار قبل أن تقبل القاعدة الاتصال، فأضف قبله أمراً ينتظر القاعدة، مثل حلقة صغيرة على pg_isready.
  • كل تشغيل ينزل المكتبات من PyPI من جديد، لأن كل خطوة Container نظيف، وسوف نعود إلى هذا في قسم السرعة.

أكثر من ملف: Workflows and depends_on

كل ملف في مجلد .woodpecker/ مهمة Workflow مستقلة، والمهام تعمل بالتوازي إذا كان عند الوكيل مكان، إلا إذا ربطت بينها بالكلمة depends_on كما في توثيق المهام. وهذا ما نحتاجه بالضبط: مهمة test تعمل مع كل دفع، ومهمة build تبني ال Image وترفعها، ولا تبدأ إلا بعد نجاح test في الخط نفسه. وفصل المهام في ملفات مختلفة يعطيك شيئين: كل ملف له شرط when خاص به، فلا تحتاج إلى تكرار الشرط على كل خطوة، وكل مهمة لها Container وشبكة وVolume خاص، فلا تختلط ملفات البناء بملفات الاختبار.

بناء ال Image ثم رفعها: Plugins and Privileged

الإضافة Plugin في Woodpecker هي Image عادية تقرأ إعداداتها من متغيرات بيئة تبدأ بـ PLUGIN_، فإذا كتبت تحت settings الإعداد repo فسوف تجده الإضافة في المتغير PLUGIN_REPO، كما في توثيق الإضافات. ولبناء Docker Image يستخدم أغلب الناس إضافة docker-buildx، فكتبنا أول نسخة من .woodpecker/build.yaml كما يكتبها أغلبنا أول مرة: إضافة واحدة تبني وترفع إلى Registry في Gitea نفسه، بتوكن نحفظه في Woodpecker على شكل سر Secret.

لماذا رفض الخط قبل أن يبدأ؟ PLUGINS_PRIVILEGED

الخط الأول بهذا الملف لم يبدأ أصلاً، وظهر فيه خطأ من أداة الفحص Linter:

pipeline #4 event=push branch=main status=error commit=c20ee589 duration=0s
errors: [
 {
  "type": "linter",
  "message": "The formerly privileged plugin `woodpeckerci/plugin-docker-buildx:6.1.2` is no longer privileged by default, if required, add it to `WOODPECKER_PLUGINS_PRIVILEGED`",
  "is_warning": false,
  "data": {
   "field": "steps.image",
   "file": "build"
  }
 }
]

والسبب أن إضافة buildx تشغل خدمة Docker كاملة dockerd داخل ال Container الخاص بها، وهذا يحتاج ال Container إلى الوضع Privileged، أي إلى صلاحيات قريبة من صلاحيات root على جهاز الوكيل. والرسالة تقول إن هذه الإضافة كانت في الإصدارات السابقة مسموحاً لها بذلك افتراضياً، أما الآن فيجب أن يسمح بها مدير السيرفر صراحة. فأضفنا إلى السيرفر WOODPECKER_PLUGINS_PRIVILEGED=woodpeckerci/plugin-docker-buildx:6.1.2، ولاحظ أننا كتبنا الوسم كاملاً، لأن القائمة تسمح بال Image بالاسم والوسم المكتوبين فقط، فإذا كتبت الاسم دون وسم فقد سمحت لكل إصدار، بما فيها إصدار قد يأتي غداً بكود لم يره أحد. ولا يستطيع المطور أن يكتب privileged: true في خطوة عادية، لأن المستودع غير موثوق Trusted، وهذا هو الحد الذي ذكرناه عن docker.sock: الخطوة تطلب ما تشاء، والسيرفر هو الذي يقرر ما يقبله.

من HTTP إلى TLS: سلسلة أخطاء ال Registry

بعد السماح بالإضافة بدأ البناء فعلاً، ونجح، ثم فشل عند الرفع:

#9 ERROR: failed to push wr-ci-gitea:3301/store/orders-api:latest: failed to do request: Head "https://wr-ci-gitea:3301/v2/store/orders-api/blobs/sha256:7b229517ed222597277036d94892173207d01a731ab3a88eeb1de2e963a2c788": http: server gave HTTP response to HTTPS client

كان Gitea في المختبر يعمل ب HTTP، وأداة البناء BuildKit تفترض أن كل Registry يعمل ب HTTPS. وكنا قد كتبنا في الإعدادات insecure: true، والسجل يبين أن الإضافة مررتها فعلاً إلى dockerd بالخيار --insecure-registry wr-ci-gitea:3301، ولكن البناء نفسه لا يحدث في dockerd، وإنما في Container منفصل اسمه BuildKit تنشئه الإضافة بالأمر docker buildx create، ولهذا Container إعداده الخاص للـ Registries. وتوثيق الإضافة يذكر إعداداً اسمه buildkit_config لهذا الغرض، فجربنا النسخة 6.1.2-insecure من الإضافة لأن الكود يسمح بهذا الإعداد في النسخة المبنية بالوسم insecure فقط، فظهر الخطأ نفسه. وعندما سألنا الملف التنفيذي داخل النسختين عن خياراته وجدنا أن كلتيهما لا تعرف الخيار أصلاً:

== woodpeckerci/plugin-docker-buildx:6.1.2 --help | grep buildkit
   --daemon.buildkit-debug                                            enables buildkit debug [$PLUGIN_BUILDKIT_DEBUG]
   --buildkit.oci.max-parallelism int                                 sets the maximum number of parallel build steps for OCI worker (default: 0) [$PLUGIN_BUILDKIT_OCI_MAX_PARALLELISM]
== woodpeckerci/plugin-docker-buildx:6.1.2-insecure --help | grep buildkit
   --daemon.buildkit-debug                                            enables buildkit debug [$PLUGIN_BUILDKIT_DEBUG]
   --buildkit.oci.max-parallelism int                                 sets the maximum number of parallel build steps for OCI worker (default: 0) [$PLUGIN_BUILDKIT_OCI_MAX_PARALLELISM]

أي أن الإعداد كان يصل إلى الإضافة ثم يتجاهل بصمت، وهذا درس عملي مهم: عندما لا يغير إعداد شيئاً، فاسأل الأداة نفسها عن خياراتها بدلاً من أن تقرأ التوثيق مرة أخرى. ولم نكمل في هذا الطريق، لأن الحل الصحيح هو ما تحتاجه في الإنتاج على أي حال: Registry بشهادة TLS. فوضعنا أمام Gitea خادم Caddy بشهادة من سلطة شهادات داخلية تنشئها Caddy نفسها بالإعداد tls internal كما في توثيق Caddy، ونسخنا شهادة هذه السلطة إلى Volume اسمه wr-ci-certs في المسار الذي تبحث فيه الإضافة /etc/docker/certs.d/<registry>/ca.crt، وجعلنا الوكيل يربطه في كل خطوة بالإعداد WOODPECKER_BACKEND_DOCKER_VOLUMES. وإذا أردت أن تفهم ما تحتويه الشهادة ولماذا تثق بها الأدوات فقد شرحنا ذلك في الشهادات الرقمية TLS وX.509. وهذا ملف Caddy:

# TLS in front of Gitea's container registry, with Caddy's own internal CA (lab only)
registry.wr-ci.lan {
	tls internal
	log
	reverse_proxy wr-ci-gitea:3301
}

ولكن الخط التالي فشل برسالة غريبة لا علاقة لها بالشهادات:

time="2026-11-05T08:43:36Z" level=info msg="found ca file for 'wr-ci-registry' registry"
+ docker buildx create --name builder --use --config /tmp/buildkit.toml
#9 ERROR: failed to push wr-ci-registry/store/orders-api:latest: push access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed

الإضافة وجدت الشهادة ومررتها إلى BuildKit، والرفض «insufficient_scope» يبدو مشكلة صلاحيات في توكن Gitea، فجربنا التوكن مباشرة على Gitea ونجح، ثم فعلنا سجل الطلبات في Caddy فلم نجد فيه طلباً واحداً من BuildKit، أي أن الرفع لم يصل إلى سيرفرنا أصلاً. والسبب في الاسم الذي اخترناه للـ Registry: wr-ci-registry ليس فيه نقطة ولا منفذ، وقاعدة أسماء ال Images في Docker أن الجزء الأول من الاسم لا يعتبر عنوان Registry إلا إذا كان فيه نقطة أو منفذ أو كان localhost، وإلا فهو اسم حساب في Docker Hub. فكان BuildKit يحاول أن يرفع إلى docker.io/wr-ci-registry/store/orders-api، وDocker Hub يرفض طبعاً. فغيرنا الاسم إلى registry.wr-ci.lan، وهذا أيضاً سبب أن اسم ال Registry في الإنتاج يكون دائماً اسم نطاق كاملاً.

ثم وصلنا إلى الخطأ الأخير في هذا الطريق:

#9 ERROR: failed to push registry.wr-ci.lan/store/orders-api:latest: failed to authorize: failed to fetch oauth token: Post "https://registry.wr-ci.lan/v2/token": tls: failed to verify certificate: x509: certificate signed by unknown authority

وهنا سجل Caddy يقول شيئاً مهماً: وصلت طلبات HEAD /v2/store/orders-api/blobs/… عبر TLS وردت ب 401، أي أن BuildKit وثق بالشهادة عندما طلب ال Registry، ثم رفضها عندما طلب التوكن من عنوان /v2/token على السيرفر نفسه. فالشهادة التي تمررها الإضافة تستخدم في طلبات ال Registry ولا تستخدم في طلب التوكن، ولا يوجد في النسخة العادية من الإضافة إعداد آخر نغيره. وعند هذه النقطة توقفنا وسألنا سؤالاً كان يجب أن نسأله من البداية: لماذا نعطي التوكن أصلاً لخطوة تعمل بصلاحيات Privileged؟

الخطوة Privileged بلا أسرار: Build Then Push

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

رسم لملف build.yaml الذي يعتمد على test ويعمل عند وسم v*، وفيه خطوة image من plugin-docker-buildx 6.1.2 بصلاحيات Privileged تبني فقط بالإعداد dry_run وتكتب image.tar بصيغة OCI في Volume المهمة دون أي سر، ثم خطوة push من crane debug v0.22.1 في Container عادي تملك السر registry_token لأحداث tag فقط وتثق بالشهادة الداخلية عبر SSL_CERT_FILE وترفع بالأمر crane push --index إلى https://registry.wr-ci.lan خلف Caddy
البناء في خطوة بلا أسرار، والرفع في خطوة بلا صلاحيات واسعة
  • خطوة image تبني فقط بالإعداد dry_run: true، وتكتب ال Image ملفاً بصيغة OCI في مجلد العمل بالإعداد output: type=oci,dest=image.tar، ولا يوجد فيها أي سر.
  • خطوة push تعمل في Container عادي من أداة crane، وهي أداة صغيرة من Google تتعامل مع ال Registries دون Docker، وتقرأ الشهادة الداخلية من المتغير SSL_CERT_FILE، فتثق بها في كل الطلبات بما فيها طلب التوكن.

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

"message": "secret \"registry_token\" is only allowed to be used by plugins (a filter has been set on the secret). Note: Image filters do not work for normal steps"

أي أن فلتر ال Image على السر يعمل مع الإضافات فقط، لأن الإضافة لا تنفذ أوامر يكتبها المستخدم، أما الخطوة العادية فتستطيع أن تفعل بالسر ما تشاء، فلا معنى لتقييده بال Image، فحذفنا الفلتر وقيدناه بنوع الحدث كما سوف نرى. والثانية أن Image الأداة crane/debug ليس فيها /bin/sh، لأن ال Shell فيها في /busybox/sh، وWoodpecker ينفذ الأوامر ب /bin/sh:

step push (commands) failure exit=0 error=Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "/bin/sh": stat /bin/sh: no such file or directory 1s

فكتبنا entrypoint للخطوة يفك السكربت الذي يضعه Woodpecker في المتغير CI_SCRIPT وينفذه ب busybox. والثالثة أن crane push يقرأ ملف Docker Tarball الذي فيه manifest.json، والملف الذي كتبته الإضافة بصيغة OCI مختلف:

▶  crane push image.tar registry.wr-ci.lan/store/orders-api:3f544ebe
Error: loading image.tar as tarball: file manifest.json not found in tar

فاستخرجنا الملف إلى مجلد OCI ورفعناه بالخيار --index، وهو الخيار الذي يرفع الفهرس Index كاملاً، أي ال Image ومعها شهادة البناء Attestation التي يكتبها BuildKit، وسوف نحتاج إلى هذه الشهادة في مقال SLSA. والصورة التالية تجمع الرسائل الإحدى عشرة من أول دفع حتى أول Image في ال Registry، وبجانب كل رسالة الإصلاح الذي جعل الخطوة التالية تعمل:

شبكة من إحدى عشرة بطاقة حمراء: 1 Webhook مرفوض denied by egress policy والإصلاح ALLOWED_HOST_LIST بمدى CIDR، 2 clone إلى 127.0.0.1:3301 والإصلاح PUBLIC_URL_DETECTION=legacy، 3 Could not resolve host والإصلاح BACKEND_DOCKER_NETWORK، 4 no longer privileged والإصلاح PLUGINS_PRIVILEGED، 5 HTTP response to HTTPS client والإصلاح TLS بشهادة داخلية، 6 insufficient_scope والإصلاح اسم بنقطة، 7 x509 unknown authority والإصلاح البناء بلا رفع ثم crane، 8 فلتر ال Image للإضافات فقط، 9 stat /bin/sh والإصلاح entrypoint من busybox، 10 manifest.json not found والإصلاح crane push --index، 11 orders-api:nil والإصلاح اقتباس الأوامر، ثم بطاقة خضراء خط أخضر v0.1.0
إحدى عشرة رسالة خطأ حقيقية من المختبر، وإصلاح كل منها

الأسرار في Woodpecker: Secrets and Events

السر Secret في Woodpecker قيمة تحفظ في قاعدة بيانات السيرفر، وتصل إلى الخطوة كمتغير بيئة عندما تكتب from_secret، ولكل سر شرطان كما في توثيق الأسرار: قائمة بأنواع الأحداث التي يسمح بها، وهي افتراضياً push وtag وdeployment وليس pull_request، وقائمة اختيارية بال Images التي يسمح لها، وتعمل مع الإضافات فقط كما رأينا. وأنشأنا السر من الواجهة البرمجية بتوكن من Gitea صلاحيته write:package فقط، أي أنه لا يستطيع أن يقرأ الكود أو يغير المستودع، وإنما يرفع الحزم:

curl -s -H "Authorization: Bearer $WP_TOKEN" -H 'Content-Type: application/json' \
  -X POST http://127.0.0.1:8301/api/repos/1/secrets \
  -d "{\"name\":\"registry_token\",\"value\":\"$TOK\",\"events\":[\"push\",\"tag\"],\"images\":[\"woodpeckerci/plugin-docker-buildx\"]}"

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

مطور يسحب التوكن من السجل: Masking Is Not Protection

أنشأ dev1 فرعاً اسمه feature/leak، وأضاف إلى test.yaml خطوة صغيرة تطبع التوكن مرتين، مرة كما هو ومرة بعد تحويله إلى base64، ثم دفع الفرع وفتح طلب دمج:

  - name: debug
    image: alpine:3.24
    environment:
      TOKEN:
        from_secret: registry_token
    commands:
      - echo "token is $TOKEN"
      - echo "$TOKEN" | base64

طلب الدمج رفض كما توقعنا، لأن السر لا يسمح بحدث pull_request:

15 pull_request main error [{"type":"generic","message":"secret \"registry_token\" is not allowed to be used with pipeline event \"pull_request\"","is_warning":false,"data":null}]

ولكن الدفع نفسه إلى الفرع حدث من نوع push، والسر يسمح ب push، فهذا ما حدث في الخط 14:

pipeline #14 event=push branch=feature/leak status=success commit=dca1034d duration=24s
workflow test: success
  step clone (clone) success exit=0 2s
  step db (service) success exit=0 20s
  step test (commands) success exit=0 17s
  step debug (commands) success exit=0 2s

--- test / debug
▶  echo "token is $TOKEN"
token is ********
▶  echo "$TOKEN" | base64
MjUzZTNhZTQyYmIwY2FiNjcxZGQ2NjIyMjk2OTE0N2RiZDgzYjczZQo=

الإخفاء نجح في السطر الأول وفشل في الثاني، لأن Woodpecker يبحث في السجل عن النص الحرفي للسر، وأي تحويل بسيط يغير النص، والسطر الأخير إذا فككته بـ base64 -d يعطيك التوكن كاملاً، وقد تحققنا من أنه يبدأ بالأحرف نفسها. وأهم من ذلك أن شرط الحدث في السر لا يعرف شيئاً عن الفرع: كل دفع إلى أي فرع من أي شخص له صلاحية الكتابة يحصل على السر، ولا يوجد في أسرار Woodpecker فلتر على الفرع، لأن ملف الخط نفسه، بما فيه شروط when، يكتبه الشخص الذي يدفع.

📌
في 14 و15 مارس 2025 عدل مهاجم الوسوم في خطوة GitHub Actions المشهورة tj-actions/changed-files لتشير إلى Commit خبيث، بحسب الإعلان الأمني GHSA-mrrh-fwg8-r2c3. وكان الكود الخبيث يقرأ ذاكرة العملية التي تنفذ الخط، ويستخرج منها الأسرار، ثم يحولها إلى base64 ويطبعها في سجل التشغيل، فظهرت الأسرار في سجلات المستودعات العامة لكل من يقرؤها، وذكر الإعلان أن الخطوة كانت مستخدمة في أكثر من 23 ألف مستودع. والدرس هو ما رأيناه في المختبر بالضبط: إخفاء الأسرار في السجل يحميك من الخطأ غير المقصود، ولا يحميك من كود يريد أن يخرجها.

الحل الأول: Require Approval

أول حل في إعدادات المستودع هو خيار الموافقة require_approval، وقيمته الافتراضية forks، فغيرناه إلى all_events وجعلنا ops وحده في قائمة من لا تحتاج خطوطهم إلى موافقة، ثم دفع dev1 مرة أخرى:

16 push feature/leak blocked dev1 []

الخط الآن ينتظر Blocked حتى يراجعه ops ويوافق عليه أو يرفضه Decline، ويستطيع المراجع أن يرى ملف الخط في تبويب Config قبل أن يقرر. وهذا الحل فعال، ولكنه ثقيل على فريق صغير، لأن كل دفع من كل مطور إلى كل فرع، بما فيه الدفع إلى main، أصبح ينتظر شخصاً، وبعد أسبوع سوف يوافق هذا الشخص على كل شيء دون أن يقرأ. فأعدنا الخيار إلى forks، وبحثنا عن حل يقلل عدد الخطوط التي تحتاج السر بدلاً من مراجعة كل الخطوط.

الحل الذي اخترناه: Protected Tags

السؤال الصحيح هو: متى نحتاج التوكن فعلاً؟ والإجابة عند إصدار نسخة فقط، أما الاختبار في كل دفع فلا يحتاج أي سر. لذلك جعلنا السر لحدث tag وحده، وجعلنا مهمة البناء تعمل عند الوسوم التي تبدأ ب v فقط، ثم حمينا هذه الوسوم في Gitea بحيث لا ينشئها إلا ops، كما في توثيق الوسوم المحمية:

curl -s -H "Authorization: Bearer $WP_TOKEN" -X PATCH -H 'Content-Type: application/json' \
  http://127.0.0.1:8301/api/repos/1/secrets/registry_token -d '{"images":[],"events":["tag"]}'
curl -s -u 'ops:Lab-Ops-2026!' -H 'Content-Type: application/json' \
  -X POST http://127.0.0.1:3301/api/v1/repos/store/orders-api/tag_protections \
  -d '{"name_pattern":"v*","whitelist_usernames":["ops"]}'

وهذا ملف .woodpecker/build.yaml بشكله النهائي:

depends_on: [test]

when:
  - event: tag
    ref: refs/tags/v*

steps:
  # privileged step: builds only, gets no secret
  - name: image
    image: woodpeckerci/plugin-docker-buildx:6.1.2
    settings:
      repo: registry.wr-ci.lan/store/orders-api
      tags: ["${CI_COMMIT_TAG}"]
      dry_run: true
      output: type=oci,dest=image.tar

  # unprivileged step: holds the registry token (tag events only), trusts the lab CA, pushes the OCI layout
  - name: push
    image: gcr.io/go-containerregistry/crane/debug:v0.22.1
    # the debug image has busybox in /busybox, not /bin/sh
    entrypoint: ["/busybox/sh", "-c", "echo $CI_SCRIPT | base64 -d | /busybox/sh -e"]
    environment:
      REGISTRY_TOKEN:
        from_secret: registry_token
      SSL_CERT_FILE: /etc/docker/certs.d/registry.wr-ci.lan/ca.crt
    commands:
      - crane auth login registry.wr-ci.lan -u ops -p "$REGISTRY_TOKEN"
      - mkdir -p oci && tar -xf image.tar -C oci
      - "crane push --index oci registry.wr-ci.lan/store/orders-api:${CI_COMMIT_TAG}"

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

errors: [
 {
  "type": "compiler",
  "message": "yaml: construct errors: line 27: cannot unmarshal 'map[crane push --index oci registry.wr-ci.lan/store/orders-api:<nil>]' of type map[string]interface {} into a string value",
  "is_warning": false,
  "data": null
 }
]

والسبب أن Woodpecker يستبدل المتغيرات مثل ${CI_COMMIT_TAG} في نص الملف قبل أن يقرأه كـ YAML، ثم يطبق الشروط when بعد ذلك، وعند الدفع العادي لا يوجد وسم، فأصبح السطر ينتهي ب orders-api:، وقرأه YAML كمفتاح في Map بلا قيمة. وإذا كانت قواعد YAML في هذه الحالة غير واضحة لك فقد شرحناها في YAML للمبتدئين. والقاعدة العملية: اقتبس كل أمر فيه نقطتان، وكل أمر فيه متغير قد يكون فارغاً، حتى لو كنت متأكداً أن المهمة لن تعمل في تلك الحالة.

والآن جربنا ما جربناه قبل قليل. دفع dev1 الفرع نفسه بخطوة debug، فرفض الخط كله قبل أن تبدأ أي خطوة:

21 push refs/heads/feature/leak error dev1 [{"type":"generic","message":"secret \"registry_token\" is not allowed to be used with pipeline event \"push\"","is_warning":false,"data":null}]

ثم حاول أن ينشئ الوسم v0.1.0 بنفسه ليحصل على حدث tag، فرفض Gitea الدفع:

remote: error: Tag v0.1.0 is protected
To http://127.0.0.1:3301/store/orders-api.git
 ! [remote rejected] v0.1.0 -> v0.1.0 (pre-receive hook declined)
error: failed to push some refs to 'http://127.0.0.1:3301/store/orders-api.git'

وعندما دفع ops الوسم نفسه عمل الخط كاملاً، وهذا مختصره:

pipeline #19 event=tag branch= status=success commit=89191c81 duration=207s
workflow build: success
  step clone (clone) success exit=0 69s
  step image (plugin) success exit=0 82s
  step push (commands) success exit=0 9s
workflow test: success
  step clone (clone) success exit=0 3s
  step db (service) success exit=0 40s
  step test (commands) success exit=0 31s

--- build / push
2026/11/05 09:03:21 registry.wr-ci.lan/store/orders-api@sha256:bccd0b30bbad8748f009adfa81b6c7143be0bfe3a96271feb0a95070c2fe7d19: digest: sha256:bccd0b30bbad8748f009adfa81b6c7143be0bfe3a96271feb0a95070c2fe7d19 size: 1429
registry.wr-ci.lan/store/orders-api@sha256:da9174a61937394994bc3b0c59b366db7131d43aa92e062e8de44794762ffe8c
2026/11/05 09:03:21 registry.wr-ci.lan/store/orders-api:v0.1.0: digest: sha256:da9174a61937394994bc3b0c59b366db7131d43aa92e062e8de44794762ffe8c size: 481

في المخرج أعلاه لاحظ التالي:

  • مهمة build بدأت بعد أن نجحت test، لأن depends_on يربط المهمتين في الخط نفسه، فلو فشل اختبار لما بنيت Image أصلاً.
  • هناك Digest بحجم 1429 بايت وآخر بحجم 481، والأول هو ال Manifest الخاص بال Image نفسها، والثاني هو الفهرس Index الذي يشير إلى ال Image وإلى شهادة البناء، والوسم v0.1.0 يشير إلى الفهرس.
  • خطوة Clone استغرقت هنا 69 ثانية، وهي أطول بكثير من ثانيتين في الخطوط السابقة، لأنها في حدث الوسم تسحب الوسوم أيضاً، ولأن الجهاز كان مشغولاً بخطوط أخرى في الوقت نفسه، وهذا رقم من مختبر على جهاز واحد وليس قياساً للأداة.

والصورة التالية تجمع التجربة قبل التغيير وبعده:

رسم بجزأين: على اليمين قبل التغيير، السر لأحداث push وtag، والمطور dev1 بصلاحية كتابة فقط يدفع فرع feature/leak بخطوة debug، فيطبع السجل token is ******** ثم نص base64 للتوكن، والخط ينجح والتوكن يخرج، وعلى اليسار بعد التغيير، السر لأحداث tag فقط مع وسوم محمية، فدفع الفرع يرفض بأن السر غير مسموح لحدث push، ووسم v0.1.0 من dev1 يرفض لأنه محمي، ووسم ops ينجح في الخط 19
شرط الحدث في السر لا يعرف الفرع، والوسوم المحمية هي التي تحدد من يحصل على السر

وهذه هي صفحة الخط 19 في واجهة Woodpecker، وفيها المهمتان وخطواتهما ومدة كل خطوة:

واجهة Woodpecker 3.20.1 لخط رقم 19 في المستودع store/orders-api بعنوان created tag v0.1.0، وفيه مهمة build بخطوات clone وimage وpush ومدتها 02:43، ومهمة test بخطوات clone وdb وtest ومدتها 00:44، وسجل خطوة clone يبدأ بالأمر git init ثم git fetch --tags
خط الوسم v0.1.0 في Woodpecker: مهمة البناء بعد مهمة الاختبار

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

ماذا لو توقف الوكيل في منتصف الخط؟ Agent Lost

الوكيل برنامج يعمل على جهاز، والأجهزة تعاد تشغيلها للتحديثات، أو ينفد منها القرص، أو يتوقف Docker عليها. فأردنا أن نعرف ماذا يرى الفريق عندما يحدث ذلك في منتصف خط، فأعدنا تشغيل خط الاختبار، وعندما بدأت خطوة test أوقفنا الوكيل بالأمر docker stop wr-ci-wp-agent، ثم راقبنا الخط من الواجهة البرمجية وسجلات السيرفر. والصورة التالية تبين ما حدث بالتوقيت:

خط زمني: 09:05:26 خطوة test تعمل وأمر docker stop للوكيل، 09:05:31 Container الخطوة Exited 137، 09:06:15 السيرفر يكتب resubmitting expired task، 09:11:32 الوكيل يعود ويكتب dropping stale task، 09:17:32 الواجهة ما زالت running، ثم cancel فيصبح الخط killed، وتحته ما بقي على الجهاز من Container وVolume وشبكة باسم wp_، وما تفعله في الإنتاج
توقف الوكيل في منتصف الخط: الخط بقي running حتى ألغيناه
09:05:53 running | test:running(clone=success,db=running,test=running)
docker ps -a: wp_01M6NF92DCZJQMAFKNHQMW65JV Exited (137)
{"level":"info","task_id":"25","time":"2026-11-05T09:06:15Z","message":"queue: resubmitting expired task"}
{"level":"error","error":"backoff: permanent error (last error: sql: no rows in result set)","time":"2026-11-05T09:11:32Z","message":"pull queue item: 25: not found in backup, dropping stale task"}
running test:running agent=1 clone=success,db=running,test=running
killed test:running clone=success,db=running,test=running

في المخرج أعلاه لاحظ التالي:

  • عندما توقف الوكيل أوقف معه Container الخطوة، فخرج برمز 137، وهو رمز الإيقاف الإجباري، ولم يكمل الاختبار.
  • بعد قرابة 50 ثانية لاحظ السيرفر أن المهمة لم يعد يصله منها شيء، فأعادها إلى الطابور، وهذا معنى resubmitting expired task.
  • عندما عاد الوكيل بعد ست دقائق سحب المهمة، ولكنه لم يجد بياناتها فأسقطها dropping stale task، وبقيت الواجهة تقول إن الخط يعمل running، وبعد 12 دقيقة من توقف الوكيل كان الخط ما زال running، فألغيناه يدوياً فأصبح killed، ثم أعدنا تشغيله من زر Restart فنجح.
  • لولا الإلغاء لبقي الخط معلقاً حتى تنتهي مهلة المستودع، وهي 60 دقيقة، وحالة ال Commit في Gitea معلقة معه، وطلب الدمج الذي يشترط نجاح الخط لا يدمج.

وهذه قائمة الخطوط في واجهة Woodpecker بعد التجربة، والخط 23 فيها بعلامة الإلغاء ومدة 12 دقيقة، وهي المدة التي بقي فيها running دون أن يعمل فيه شيء، وفوقه الخط 24 الذي أعدنا تشغيله:

قائمة الخطوط في Woodpecker للمستودع store/orders-api: الخط 24 يعمل، والخط 23 ملغى بمدة 12 minutes، والخطان 22 و21 فاشلان قبل أن يبدآ not started yet بسبب شرط السر، والخط 20 ناجح، والخط 19 للوسم v0.1.0 ناجح بمدة 3 minutes، والخط 18 فاشل قبل أن يبدأ بسبب خطأ YAML
الخط 23 بقي 12 دقيقة دون وكيل، والخطان 21 و22 رفضهما شرط السر قبل أن يبدآ

وعند التنظيف وجدنا على الجهاز Container الخطوة متوقفاً،وVolume وشبكة باسم يبدأ ب wp_، لأن الوكيل الذي أنشأها توقف قبل أن يصل إلى خطوة التنظيف، ولا يعود إليها بعد ذلك. وفي سيرفر يعمل شهوراً تتراكم هذه البقايا، فراقب عدد الوكلاء المتصلين وانبه عندما يصل إلى صفر، وحدث الوكيل أو أعد تشغيل جهازه في وقت لا تعمل فيه خطوط، واجعل مهلة المستودع قريبة من المدة الحقيقية للخط بدلاً من ساعة كاملة، ونظف البقايا التي يبدأ اسمها ب wp_ بأمر مجدول. ولاحظنا في سجل السيرفر في الوقت نفسه رسائل database is locked من قاعدة SQLite عندما كانت عدة خطوط تعمل معاً، وهذا سبب آخر لتستخدم PostgreSQL في سيرفر يعمل عليه فريق.

تشغيل الخط على جهازك قبل الدفع: woodpecker-cli exec

كل خطأ من الأخطاء السابقة احتاج إلى Commit ودفع وانتظار، وهذا بطيء ويملأ تاريخ المستودع برسائل مثل «ci: try again». ولهذا يأتي مع Woodpecker أمر woodpecker-cli exec الذي ينفذ ملف الخط على جهازك بخلفية Docker دون سيرفر، كما في توثيق التشغيل المحلي. وجربناه من Image الأداة الرسمية دون تثبيت شيء، ومررنا في الطريق بثلاث رسائل:

# 1) docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/src -w /src woodpeckerci/woodpecker-cli:v3.20.1 exec .woodpecker/test.yaml
{"level":"fatal","error":"no workflows to execute (all filtered out)","time":"2026-11-05T09:19:36Z","message":"error running cli"}
# 2) same with --pipeline-event push
{"level":"fatal","error":"permission denied while trying to connect to the docker API at unix:///var/run/docker.sock","time":"2026-11-05T09:19:54Z","message":"error running cli"}
# 3) with -u 0, repo mounted at /src
[test:L4:3s] ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'
  • الأولى لأن الحدث الافتراضي في التشغيل المحلي هو manual، وملفنا يشترط push أو pull_request أو tag، فاستبعدت الشروط المهمة الوحيدة، والحل الخيار --pipeline-event push.
  • الثانية لأن Image الأداة تعمل بمستخدم عادي لا يملك docker.sock، فشغلناها بالمستخدم root بالخيار -u 0، وهذا مقبول على جهاز المطور فقط.
  • الثالثة هي الأهم: الأداة تطلب من Docker أن يربط مجلد العمل /src في خطوات الخط، ولكن Docker يبحث عن /src على الجهاز نفسه وليس داخل Container الأداة، فيربط مجلداً فارغاً. والحل أن تربط المستودع في Container الأداة بالمسار نفسه الذي يراه Docker، أي -v $PWD:$PWD -w $PWD.

وبعد الإصلاحات الثلاثة كان المخرج كما يلي:

# test
[test:L0:0s] ▶  pip install --quiet -r requirements.txt
[test:L5:21s] ▶  python -m pytest -q
[test:L6:25s] ....                                                                     [100%]
[test:L7:25s] 4 passed in 2.12s

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

السرعة وذاكرة التخزين: Cache

في الأرقام التي رأيناها شيئان يكلفان أغلب وقت الخط. الأول أن خطوة الاختبار تنزل المكتبات من PyPI في كل تشغيل، لأن كل خطوة Container جديد، وكانت الخطوة تستغرق بين 17 و50 ثانية بحسب انشغال الجهاز، منها ثوان قليلة للاختبارات نفسها. والثاني أن إضافة buildx تشغل BuildKit جديداً في كل مرة، وفي أول تشغيلاتها سحبت Image الخاصة به، فاستغرق سطر booting buildkit بين 44 و48 ثانية. وليس في Woodpecker كلمة cache كما في Actions، وأمامك ثلاثة خيارات:

  • Image مخصصة للاختبار فيها المكتبات مسبقاً، تبنيها مرة عند تغير ملف المكتبات وترفعها إلى ال Registry، وهذا أبسط حل وأكثره ثباتاً، ولا تنس معه انتظار قاعدة البيانات كما ذكرنا.
  • Volume على جهاز الوكيل لمجلد ذاكرة pip، ولكن ربط Volumes من الجهاز يحتاج إلى جعل المستودع موثوقاً Trusted، وهذا يعطي كل خطوة فيه، بما فيها خطوات طلبات الدمج، القدرة على ربط أي مجلد من الجهاز، كما في توثيق ال Volumes، فلا تفعله في مستودع يكتب فيه أكثر من شخص تثق به.
  • إضافة تحفظ الذاكرة في تخزين خارجي مثل S3، وهي مناسبة عندما يكون عندك أكثر من وكيل، لأن Volume على جهاز واحد لا يفيد وكيلاً على جهاز آخر.

أما الموارد وهي ساكنة فقد كانت أرقامها في المختبر صغيرة، فقد قسناها بالأمر docker stats بعد أن هدأ الجهاز:

wr-ci-gitea 198.4MiB / 31.29GiB 0.29%
wr-ci-woodpecker 44.21MiB / 31.29GiB 0.32%
wr-ci-wp-agent 11.63MiB / 31.29GiB 0.02%
wr-ci-registry 19.46MiB / 31.29GiB 0.00%

أي أن سيرفر Woodpecker والوكيل معاً أقل من 60 ميغابايت من الذاكرة، وحجم Image السيرفر 83.7 ميغابايت والوكيل 80.9 ميغابايت على القرص. ولكن لا تخلط هذا الرقم بتكلفة الخطوط نفسها، فإضافة buildx وحدها 729 ميغابايت على القرص، والذاكرة التي يحتاجها الخط هي ذاكرة الخطوات وليس ذاكرة الوكيل، وسوف نقيس ذلك كله مقارنة بأدوات أخرى في المقال القادم.

من المختبر إلى الإنتاج: Production Setup

المختبر كله على جهاز واحد، وفي سيرفر حقيقي لفريق يتغير شكله في نقاط واضحة:

  • Gitea وWoodpecker على اسمي نطاق خلف Reverse Proxy بشهادة TLS حقيقية، فلا تحتاج إلى PUBLIC_URL_DETECTION ولا إلى شبكة مشتركة بين الخطوات والخدمات، وALLOWED_HOST_LIST يحتوي على عنوان Woodpecker الداخلي فقط إذا كان داخلياً.
  • الوكيل على جهاز منفصل للبناء، لأن من يملك docker.sock يملك الجهاز، فلا تجعله جهاز Gitea أو جهاز قاعدة البيانات، وراجع مقال شبكات Docker في عزل هذا الجهاز عن بقية الشبكة.
  • قاعدة PostgreSQL لسيرفر Woodpecker بدلاً من SQLite، ونسخة احتياطية لها مع Gitea، لأن فيها الأسرار وتوكنات المستخدمين.
  • كل Image بوسم ثابت، في ملف Compose وفي ملفات الخطوط وفي قائمة PLUGINS_PRIVILEGED، وتحديثها بطلب دمج يراجعه أحد، وقد شرحنا أدوات تحديث ال Images في تحديث ال Containers بأمان.
  • الأسرار التي تحتاجها الخطوط بأقل صلاحية ممكنة، مثل توكن write:package فقط، ولأقل أحداث ممكنة، وإذا كان عندك مدير أسرار فقد شرحنا الخيارات في إدارة الأسرار.

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

  • الاعتماد على إخفاء الأسرار في السجل: يغطي النص الحرفي فقط، وbase64 أظهر التوكن كاملاً.
  • سر لأحداث push في مستودع يكتب فيه أكثر من شخص: كل دفع إلى أي فرع يحصل عليه، ولا يوجد فلتر على الفرع.
  • فلتر ال Image على سر تستخدمه خطوة عادية: يعمل مع الإضافات فقط، والخط يرفض.
  • السماح بإضافة Privileged باسمها دون وسم: يسمح لكل إصدار قادم منها.
  • إعطاء التوكن للخطوة Privileged نفسها: افصل البناء عن الرفع.
  • اسم Registry بلا نقطة ولا منفذ: يذهب الرفع إلى Docker Hub ويرفض برسالة تشبه مشكلة الصلاحيات.
  • Registry ب HTTP مع BuildKit: الإعداد insecure يصل إلى dockerd فقط، والحل TLS.
  • جعل المستودع Trusted من أجل ذاكرة pip: يعطي كل خطوة القدرة على ربط مجلدات الجهاز.
  • أوامر فيها متغير قد يكون فارغاً دون اقتباس: يقرؤها YAML كمفتاح ويرفض الخط كله.
  • الاكتفاء بالقيم الافتراضية في Gitea دون ALLOWED_HOST_LIST: لا يصل ال Webhook ولا يظهر الخط، والخطأ في سجل Gitea وحده.
  • عدم مراقبة الوكلاء: خط معلق running لا يلاحظه أحد، وبقايا wp_ تتراكم على القرص.

قائمة تحقق Checklist

قبل أن تعتمد الخط في فريقككيف تتحقق
ال Webhook يصل من Giteaدفعة جديدة تظهر خطاً خلال ثوان، ولا توجد denied by egress policy في سجل Gitea
رابط ال Clone هو العنوان الرسميسطر git remote add origin في سجل Clone فيه اسم النطاق
كل Image بوسم ثابتلا يوجد latest أو اسم بلا وسم في Compose وملفات الخطوط
الإضافات Privileged محددة بالوسمWOODPECKER_PLUGINS_PRIVILEGED فيها الاسم والوسم كاملين
المستودع غير Trustedالقيم الثلاث في trusted هي false
التوكن خارج الخطوة Privilegedخطوة البناء ليس فيها from_secret
الأسرار لأحداث الإصدار فقطدفع فرع بخطوة تطلب السر يرفض بـ not allowed to be used with pipeline event "push"
وسوم الإصدار محميةدفع وسم v* من مطور يرفض بـ Tag … is protected
الوكيل مراقبتنبيه عندما لا يوجد وكيل متصل، ومهلة المستودع قريبة من مدة الخط
السيرفر على PostgreSQL مع نسخة احتياطيةWOODPECKER_DATABASE_DRIVER=postgres واستعادة مجربة

إزالة التجربة Cleanup

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

docker rm -f $(docker ps -aq --filter name=wp_)
docker volume rm wp_01m6nf92dczjqmafknhm9445em_0_default
docker network rm wp_01m6nf92dczjqmafknhm9445em_0_default
docker compose --env-file wp.env down -v
docker volume rm wr-ci-certs

الخلاصة Summary

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

  • Woodpecker سيرفر صغير ووكيل يتصل به، وكل خطوة Container بأوامر عادية أو إضافة هي Image، ولا توجد طبقة خطوات جاهزة بينك وبين ما ينفذ، وفي المختبر كان السيرفر والوكيل معاً أقل من 60 ميغابايت من الذاكرة.
  • ثلاثة إعدادات في Gitea والوكيل كانت بين الدفع وأول خط: ALLOWED_HOST_LIST بمدى CIDR لأن Gitea يمنع العناوين الخاصة، وPUBLIC_URL_DETECTION=legacy لأن رابط ال Clone جاء من عنوان الدفع، وشبكة للخطوات تعرف اسم Gitea.
  • الإضافة التي تبني ال Images تحتاج إذناً صريحاً من السيرفر لأنها Privileged، والتصميم الأفضل أن تبني فقط دون أسرار، وأن ترفع خطوة عادية بالتوكن.
  • ال Registry يحتاج TLS واسماً فيه نقطة، والإعداد insecure لم يغير شيئاً لأن البناء يحدث في BuildKit وليس في dockerd.
  • إخفاء الأسرار في السجل لا يحمي من كود يريد إخراجها، وشرط الحدث لا يعرف الفرع، والحماية الحقيقية سر لأحداث الوسوم فقط ووسوم لا ينشئها إلا المسؤول.
  • عندما توقف الوكيل في منتصف الخط بقي الخط running حتى ألغيناه، وبقيت على الجهاز بقايا لا ينظفها أحد، فراقب الوكلاء.
  • الأمر woodpecker-cli exec يجرب الخط على جهازك قبل الدفع، بشرط أن يرى Docker مجلد المستودع بالمسار نفسه.

وفي المقال التالي في المرحلة بإذن الله نضع Gitea Actions وWoodpecker وJenkins على الخط نفسه، ونقيس كل واحد منها بالأرقام. والمقالات المرتبطة بهذا المقال:

دليلGitea: خادم Git خاص لفريقك على سيرفرككيف تثبت Gitea على سيرفرك حتى يبقى كود فريقك عندك بتجربة تشبه GitHub، مع النسخ الاحتياطي والتحديث.دليلGitea Actions: تشغيل CI/CD وبناء Docker Images على سيرفركاجعل سيرفرك يختبر الكود ويبني Docker Images تلقائياً مع كل push، دون أن يخرج كودك أو أسرارك إلى خدمة CI خارجية.دليلمفهوم CI/CD للمبتدئين: من كل Push إلى سيرفر يعملما الذي يعنيه التكامل المستمر والتسليم المستمر فعلاً، وكيف تبني خطاً صغيراً يختبر كل Push وينشر إلى staging ويتحقق منه، مع الأخطاء الحقيقية التي يكشفها وتلك التي لا يكشفها.دليلأمن سلسلة التوريد البرمجية Software Supply Chain للمبتدئينكل ما بين كود غيرك وسيرفرك قد يحمل كود المهاجم، وهنا تعرف التهديدات الحقيقية بحوادث موثقة والدفاع المناسب لكل حلقة.دليلSecrets Scanning: كيف تكتشف الأسرار المسربة في الكودكيف يخرج المفتاح من جهازك إلى تاريخ Git وخط CI، وكيف تكتشفه قبل غيرك، وماذا تفعل في الساعة الأولى بعد تسربه.دليلتشغيل OpenTofu من CI/CD: خطة Plan في كل طلب دمجخط على Gitea يضع خطة OpenTofu في كل طلب دمج ويطبقها بعد الموافقة، مع ما يحدث فعلاً عندما تتزامن الطلبات، وكيف خرج المفتاح من خطة فاشلة.

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

  • نوفمبر 2026: كتابة المقال وتنفيذ المختبر بـ Gitea 28.3.0 مع Woodpecker Server وAgent بالإصدار 3.20.1، وإضافة plugin-git 2.11.0 وplugin-docker-buildx 6.1.2 وcrane v0.22.1 وCaddy 2.11.8، وخدمة postgres:18-alpine بالإصدار PostgreSQL 18.6، وخطوة python:3.13-alpine مع pytest 9.2.0 وpsycopg 3.3.8، وwoodpecker-cli 3.20.1، على Docker Engine 29.8.0.
نشرة عرب رووت | ArabRoot

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

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

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

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