act

إذا كان ملف GitHub Actions يفشل بعد كل رفع، يصبح تصحيح خطوة بسيطة سلسلة من commits وتشغيلات متكررة. أداة act تشغّل ملفات العمل الموجودة في .github/workflows على جهازك، لتفحص وظيفة الاختبار قبل دفع التغيير. قيمتها العملية أنها تقرّب نتيجة CI من دورة التطوير اليومية؛ لكنها لا تجعل جهازك نسخة مطابقة لبيئة GitHub.

🧭 ما أداة act؟

أداة سطر أوامر مفتوحة المصدر من مشروع nektos. تقرأ ملفات GitHub Actions، تحدد الوظائف التي يطابقها الحدث الذي اخترته، ثم تستخدم Docker API لتشغيل الحاويات اللازمة. لا تحتاج إلى إنشاء صيغة CI جديدة: تعمل على ملف YAML الموجود في مشروعك. الإصدار الذي ظهر أحدث إصدار منشور وقت التحقق هو v0.2.89.

رسم توضيحي أصلي لمسار العمل، وليس لقطة من واجهة المنتج.

🎯 كيف ستفيدك؟

تخيل أن اختبار مشروعك يفشل في GitHub Actions بسبب أمر داخل ملف checks.yml. افتح المشروع محليًا، عدّل ملف العمل، ثم شغّل الوظيفة المعنية بـact. سترى سجل تنفيذها على جهازك قبل الرفع. هذا يقلل الحاجة إلى تشغيل GitHub Actions لكل محاولة تصحيح محلية، لكنه لا يلغي التشغيل النهائي على GitHub، ولا يتجاوز حد ميزانية حسابك إذا بقيت تعتمد على تشغيلات مستضافة هناك.

تناسب مطورًا منفردًا أو فريقًا صغيرًا لديه GitHub Actions ويريد دورة تصحيح أسرع. لا تناسب سير عمل يعتمد على خصائص GitHub غير المدعومة محليًا أو على مطابقة كاملة لصورة GitHub runner.

🌟 الميزات وطريقة استخدامها

1. تشغيل الحدث محليًا

داخل جذر المستودع، يعامل act بدون وسيطات الحدث push. يمكنك كتابة act push صراحة، أو act pull_request لفحص الوظائف المرتبطة بطلب الدمج. يعرض act -l pull_request قائمة الوظائف التي سيشغلها لذلك الحدث؛ ابدأ بالقائمة قبل تنفيذ ملف غير مألوف. تعتمد بعض الملفات على تفاصيل حدث لا يستطيع act استنتاجها من المستودع، فتحتاج إلى ملف JSON تمرره بالخيار -e.

• الفائدة: تعرف أي وظيفة ستعمل وتقرأ سجلها قبل رفع commit.
• القيد: محاكاة الحدث أساسية؛ لا تفترض أن جميع حقول سياق GitHub موجودة.

2. حصر التشغيل في ملف أو وظيفة

الخيار -W يحدد ملف workflow، و-j يحدد اسم الوظيفة. مثال: act -W .github/workflows/checks.yml -j test. هذا مفيد عندما تريد إصلاح اختبار واحد بدل إعادة تشغيل جميع الوظائف المحلية. تأكد أن اسم الملف والوظيفة يطابقان مشروعك.

رسم توضيحي لخيارات النطاق الموثقة؛ أسماء الملف والوظيفة في المثال توضيحية.

3. تمرير الأسرار عند الحاجة

يمكنك تمرير سر تفاعليًا بكتابة act -s MY_SECRET؛ إن لم يكن متغير البيئة موجودًا، يطلب act القيمة بإدخال لا يضعها في سجل أوامر shell. تتوفر أيضًا ملفات أسرار، لكن راجع مكان حفظها وصلاحياتها. GitHub يضيف GITHUB_TOKEN تلقائيًا في تشغيلاته، أما التشغيل المحلي فقد يحتاج منك إلى رمز إذا كانت الوظيفة تعتمد عليه.

رسم توضيحي؛ لا يحوّل الحاوية أو ملفات العمل غير الموثوقة إلى بيئة آمنة للأسرار.

4. تغيير صورة التشغيل مع فهم الفرق

يستخدم act صور Docker لتمثيل runner. تستطيع تحديد صورة أخرى بالخيار -P، لكن الصور الافتراضية قد تفتقد أدوات موجودة في GitHub runner. الصورة الأقرب قد تكون كبيرة جدًا. لهذا اقرأ سجل التنفيذ، ثم شغّل الفحص النهائي على GitHub قبل اعتماد التغيير.

رسم يشرح حدود المحاكاة، وليس نتيجة اختبار على مشروع فعلي.

🪜 مثال عملي خطوة بخطوة

مثال توضيحي لم أنفذه على مشروعك:

1. افتح مجلد المستودع الذي يحتوي .github/workflows/checks.yml.
2. تحقق من تشغيل Docker. على Mac يمكن تثبيت act بالأمر brew install act.
3. اعرض الوظائف باستخدام act -l push.
4. شغّل وظيفة الاختبار فقط: act -W .github/workflows/checks.yml -j test.
5. اقرأ الخطوة الفاشلة، عدّل ملف العمل أو الاختبار، ثم أعد الأمر نفسه.
6. ارفع التغيير عندما ينجح محليًا، وراجع نتيجة GitHub Actions نفسها قبل الدمج.

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

⚖️ مقارنة بالطريقة اليدوية

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

⚙️ الإعداد والتثبيت

على macOS أو Linux مع Homebrew: brew install act. يوفر المشروع ملفات جاهزة لـApple Silicon وIntel وLinux وWindows في صفحة الإصدارات. يحتاج التشغيل المعتاد Docker Engine API؛ تثبيت الأداة وحده لا يكفي. توثق التعليمات وضع تشغيل بعض وظائف Windows أو macOS مباشرة على المضيف دون Docker، لكنه يزيل عزل الحاوية ولا يصلح بديلًا عامًا لكل workflow. لا يدعم المشروع Podman رسميًا.

لتغيير صورة runner استخدم -P. ويمكن حفظ الوسيطات المتكررة في ملف .actrc؛ لا تخزن فيه أسرارًا. على Apple Silicon توجد نسخة Darwin_arm64 رسمية.

🔗 التوافق والتكلفة والخصوصية

الترخيص MIT ولا يفرض act نفسه اشتراكًا أو API مدفوعًا. موارد Docker والصور والشبكة والخدمات التي تستدعيها وظائفك منفصلة عن ترخيص الأداة. ينفذ act ملف العمل على جهازك؛ لكنه قد يسحب صور Docker أو actions من الشبكة، وقد تتصل خطوات workflow بخدمات خارجية. يستطيع العمل مع مستودعات GitHub Actions، لكنه ليس GitHub runner مطابقًا.

⚠️ الحدود والصلاحيات

التوثيق الرسمي يسجل خصائص غير مدعومة أو متجاهلة، منها concurrency وjob.permissions وjob.environment وOpenID Connect وjob.timeout-minutes. وقد تختلف الأدوات المثبتة في صورة Docker عن GitHub runner. لهذا لا تستخدم نجاح act دليلًا وحيدًا على نجاح النشر أو ضوابط الصلاحيات. افحص مصدر actions والصور المستخدمة قبل منحها رموزًا أو وصولًا لملفات جهازك. إدخال السر تفاعليًا يمنع ظهوره في سجل shell، لكنه لا يمنع خطوة workflow نفسها من قراءته.

📚 المصادر وتاريخ التحقق

تحققت في 29 سبتمبر 2026 من المستودع الأصلي، دليل التثبيت، دليل الاستخدام، دليل صور التشغيل، الخصائص غير المدعومة، والإصدارات. أحدث إصدار ظاهر v0.2.89 بتاريخ 1 يونيو 2026. أظهر المستودع نحو 72.1 ألف نجمة ونحو 2.0 ألف تفرع وقت الفحص؛ رقمان متغيران للمستودع، وليسا تقييمًا للجودة. لم أثبّت الأداة أو أنفذ المثال.