إنشاء إجراء GitHub مخصص

8 دقائق

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

أنواع إجراءات GitHub

رسم تخطيطي للأنوع الثلاثة من إجراءات GitHub؛ إجراءات Docker وJavaScript وخطوات التشغيل المركبة.

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

إجراءات حاوية Docker

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

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

أنشئ Dockerfile لتعريف الأوامر لتجميع صورة Docker.
أنشئ ملف بيانات التعريف action.yml لتعريف المدخلات والمخرجات للإجراء. بادر بتعيين القيمة runs: using: إلى docker والقيمة runs: image: إلى Dockerfile في الملف.
أنشئ الملف entrypoint.sh لوصف صورة docker.
بادر بتنفيذ الإجراء ودفعه إلى GitHub مع الملفات التالية: action.yml وentrypoint.sh وDockerfile وREADME.md.

إجراءات JavaScript

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

كمتطلب أساسي لإنشاء إجراءات JavaScript واستخدامها، التي تم تحزيمها، تحتاج إلى تنزيل Node.js، الذي يتضمن npm. كخطوة اختيارية (ولكن واحدة نوصي بها) هي استخدام مجموعة أدوات إجراءات GitHub Node.js، وهي مجموعة من حزم Node.js التي تسمح لك بإنشاء إجراءات JavaScript بسرعة بمزيد من التناسق.

خطوات إنشاء إجراء JavaScript هي الحد الأدنى والمباشر:

قم بإنشاء action.yml ملف بيانات تعريف لتعريف مدخلات ومخرجات الإجراء، بالإضافة إلى إخبار مشغل الإجراء بكيفية بدء تشغيل إجراء JavaScript هذا.
أنشئ الملف index.js مع معلومات السياق حول حِزم مجموعة الأدوات والتوجيه والوظائف الأخرى للإجراء.
بادر بتنفيذ الإجراء ودفعه إلى GitHub مع الملفات التالية: action.yml وindex.js وnode_modules وpackage.jsonوpackage-lock.jsonوREADME.md.

إجراءات خطوات التشغيل المركبة

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

إجراء مركب مجمع

تجمع الإجراءات المركبة المجمعة خطوات متعددة في وحدة قابلة لإعادة الاستخدام. يتم تعريف هذه الإجراءات في مستودع ويمكن الرجوع إليها في مهام سير العمل عبر مستودعات مختلفة. يعمل تجميع إجراء مركب على تبسيط مهام سير العمل وتقليل التكرار وتحسين إمكانية الصيانة.

عند إنشاء إجراء مركب مجمع، يتم تعريف الخطوات في ملف واحد action.yml . يحدد هذا الملف المدخلات والمخرجات وتسلسل الأوامر أو الإجراءات التي يجب تنفيذها. تعد الإجراءات المركبة المجمعة مفيدة بشكل خاص لأتمتة المهام المتكررة أو دمج أوامر shell متعددة في إجراء واحد قابل لإعادة الاستخدام.

إنشاء qction مركب

1. إعداد دليل للإجراء المركب

يجب وضع الإجراء المركب الخاص بك في الدليل الخاص به داخل المستودع.

مثال على بنية الدليل:

.github/actions/my-composite-action/
├── action.yml
└── scripts/
    └── my-script.sh

2. تعريف `action.yml` الملف

داخل دليل الإجراء المركب الخاص بي، قم بإنشاء action.yml ملف.

name: "My Composite Action"
description: "A reusable composite action that checks out code and sets up Node.js"

inputs:
  node-version:
    description: "The Node.js version to use"
    required: true

runs:
  using: "composite"
  steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}

ملاحظه: يشير الحقل using: "مركب" إلى أن هذا الإجراء هو إجراء مركب.

3. استخدام الإجراء المركب في سير عمل

بمجرد إنشاء الإجراء المركب، يمكن الرجوع إليه في سير عمل GitHub Actions.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Use my composite action
        uses: ./.github/actions/my-composite-action
        with:
          node-version: '18'

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

uses: owner/repository/.github/actions/my-composite-action@v1

لقطة شاشة لإجراء مركب مستخدم في سير عمل.

إضافة مخرجات إلى إجراء مركب

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

يوضح المثال التالي كيفية تعريف واستخدام الإخراج في إجراء مركب:

تعريف الإخراج في `action.yml`

action.yml يحدد الملف إخراجا يسمى script-result. يسترد هذا الإخراج قيمته من result إخراج run-script الخطوة. run-script تقوم الخطوة بتشغيل أمر Bash لتعيين قيمة الإخراج.

outputs:
  script-result:
    description: "Result from the script"
    value: ${{ steps.run-script.outputs.result }}

runs:
  using: "composite"
  steps:
    - id: run-script
      run: echo "result=Success" >> $GITHUB_OUTPUT
      shell: bash

لقطة شاشة لتعريف الإخراج في إجراء مركب.

استخدام الإخراج في سير عمل

بمجرد إنشاء الإجراء المركب، يمكن الوصول إلى مخرجاته في سير عمل. إليك مثال:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Run composite action
        id: my-action
        uses: ./.github/actions/my-composite-action

      - name: Display result
        run: echo "Script Result: ${{ steps.my-action.outputs.script-result }}"

في هذا المثال:

يتم استدعاء الإجراء المركب باستخدام uses الكلمة الأساسية .
الوصول إلى الإخراج script-result باستخدام بناء الجملة steps.<step-id>.outputs.<output-name> .
عرض النتيجة في سجلات سير العمل.

تحديد المخرجات في الإجراءات المركبة لإنشاء مهام سير عمل قابلة لإعادة الاستخدام ووحدات نمطية. يعمل هذا النهج على تبسيط مشاركة البيانات وتحسين إمكانية الصيانة.

أفضل الممارسات للإجراءات المركبة

أفضل الممارسات	الوصف
استخدام تعيين الإصدار	استخدم علامة `v1` للإشارة إلى الإصدار الثابت 1.
الاحتفاظ بالإجراءات النمطية	تجميع الخطوات ذات الصلة داخل إجراء مركب.
مدخلات المستند ومخرجاته	أضف أوصافا للمدخلات/المخرجات في `action.yml`.
الاختبار قبل النشر	التحقق من صحة الإجراء المركب في مستودع اختبار.

إجراء مركب في سير عمل

الإجراءات المركبة هي طريقة قوية لتبسيط مهام سير العمل عن طريق تجميع خطوات متعددة في وحدة قابلة لإعادة الاستخدام. تسمح لك هذه الإجراءات بتعريف سلسلة من الأوامر أو الإجراءات في ملف واحد action.yml ، ما يسهل الحفاظ على المنطق وإعادة استخدامه عبر مهام سير العمل.

فوائد الإجراءات المركبة:

إعادة الاستخدام - حدد الإجراءات مرة واحدة واستخدمها في مهام سير عمل متعددة.
قابلية الصيانة - تقليل الازدواجية من خلال مركزية المنطق في إجراء واحد.
نمطية - دمج أوامر shell متعددة أو إجراءات أخرى في وحدة واحدة.

تطوير إجراء لإعداد CLI على مشغلي GitHub Actions

تتطلب العديد من مهام سير عمل CI/CD إصدارا محددا من أداة CLI للتفاعل مع الخدمات السحابية أو إدارة البنية الأساسية أو تنفيذ البرامج النصية. بينما تأتي المشغلات المستضافة على GitHub مثبتة مسبقا مع العديد من الأدوات، إلا أنها قد لا تتضمن الإصدار الدقيق الذي يحتاجه سير العمل، خاصة إذا كان إصدارا قديما أو غير مدعوم. بدلا من تثبيت إصدار CLI المطلوب في كل سير عمل، يمكنك إنشاء إجراء GitHub قابل لإعادة الاستخدام :

يضمن التثبيت المتسق لإصدار CLI المطلوب عبر الوظائف.
يبسط مهام سير العمل عن طريق مركزية منطق التثبيت.
يحسن التخزين المؤقت لتنفيذ سير العمل بشكل أسرع.

كيفية تطوير إجراء إعداد CLI

إجراء إعداد CLI هو إجراء يستند إلى JavaScript يقوم بتثبيت وتكوين CLI على مشغل GitHub.

خطوات إنشاء الإجراء:

الخطوة 1: إعداد دليل الإجراءات

لإنشاء الدليل يدويا لإجراء إعداد CLI، اتبع الخطوات التالية:

انتقل إلى المستودع الخاص بك

لقطة شاشة لبنية مستودع الجذر التي تظهر لإجراء JavaScript.

إنشاء دليل جديد للإجراء
إنشاء دليل جديد باسم my-cli-action داخل .github/actions المجلد. وهذا يضمن تنظيم الإجراء الخاص بك ويتبع البنية الموصى بها ل GitHub للإجراءات المخصصة.
انتقل إلى الدليل الجديد
قم بالتغيير إلى الدليل الذي تم إنشاؤه حديثا لبدء إضافة ملفات للإجراء الخاص بك:
التحقق من بنية الدليل
بعد إنشاء الدليل، يجب أن تبدو بنية المستودع كما يلي:

your-repository/
├── .github/
│   ├── actions/
│   │   ├── my-cli-action/

لقطة شاشة لبنية الدليل لإجراء JavaScript داخل '.github/actions.'

أنت الآن جاهز للمتابعة في إنشاء الملف والملفات الضرورية action.yml الأخرى لإجراء إعداد CLI.

الخطوة 2: تعريف ملف بيانات التعريف action.yml

إنشاء ملف action.yml لوصف الإجراء.

name: "Setup MyCLI"
description: "Installs MyCLI and adds it to the PATH"
author: "Your Name"

inputs:
  version:
    description: "The CLI version to install"
    required: false
    default: "latest"

runs:
  using: "node16"
  main: "index.js"

لماذا تستخدم : node16؟ يقوم هذا الإجراء بتشغيل تعليمة JavaScript البرمجية باستخدام Node.js 16.

لقطة شاشة لملف بيانات تعريف YAML لإجراء JavaScript GitHub.

الخطوة 3: إنشاء برنامج نصي JavaScript لتثبيت CLI

في نفس الدليل، أنشئ ملفا باسم index.js وأضف التعليمات البرمجية التالية:

const core = require('@actions/core');
const { execSync } = require('child_process');

async function run() {
  try {
    const version = core.getInput('version') || 'latest';
    
    console.log(`Installing MyCLI version: ${version}...`);

    execSync(`curl -fsSL https://cli.example.com/install.sh | sh`, { stdio: 'inherit' });

    console.log("MyCLI installed successfully.");
  } catch (error) {
    core.setFailed(`Installation failed: ${error.message}`);
  }
}

run();

تستخدم التعليمات البرمجية JavaScript أعلاه core.getInput() لاسترداد إصدار CLI المحدد كمدخل. ثم ينفذ أمر curl لتنزيل وتثبيت CLI. إذا فشلت عملية التثبيت، يستخدم الإجراء core.setFailed() لوضع علامة على سير العمل على أنه فشل.

لقطة شاشة لرمز JavaScript index.js في إجراء GitHub.

الخطوة 4: اختبار الإجراء محليا

قبل استخدام الإجراء في سير العمل، اختبره على مشغل مستضاف على GitHub.
إنشاء ملف سير عمل (.github/workflows/test.yml) في المستودع الخاص بك:

name: Test MyCLI Setup

on:
  push:
    branches:
      - main
      - feature/*

1. تشغيل سير العمل
يتم تشغيل سير العمل على دفعات إلى الفرع الرئيسي وأي فرع يطابق نمط الميزة/* . يمكنك ضبط هذا لمطابقة استراتيجية التفريع الخاصة بمستودعك.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

2. استنساخ المستودع
يتم استخدام الإجراء actions/checkout@v4 لنسخ المستودع إلى المشغل. وهذا يضمن أن سير العمل لديه حق الوصول إلى ملفات المستودع.

      - name: Install MyCLI
        uses: ./.github/actions/my-cli-action
        with:
          version: '1.2.3'

3. تشغيل الإجراء المخصص
الاستخدامات: يشير سطر ./.github/actions/my-cli-action إلى الإجراء المخصص محليا. تأكد من إعداد دليل الإجراء وملف action.yml بشكل صحيح. يحدد إدخال الإصدار إصدار CLI المراد تثبيته - في هذه الحالة، الإصدار 1.2.3.

      - name: Verify CLI Installation
        run: |
          echo "Checking MyCLI version..."
          mycli --version

4. تحقق من تثبيت CLI
تقوم هذه الخطوة بتشغيل أمر shell للتحقق من تثبيت CLI بنجاح. يتحقق من إصدار CLI المثبت عن طريق تشغيل mycli --version.

لقطة شاشة لنتائج اختبار إجراء JavaScript GitHub.

اختبر بشكل محلي

لاختبار سير العمل هذا محليا، استخدم act أداة CLI:

act -j test

هذا يحاكي بيئة إجراءات GitHub على جهازك المحلي، مما يسمح لك بتصحيح سير العمل والتحقق من صحته قبل دفع التغييرات.

تلميح التحسين: التخزين المؤقت

لتحسين أداء سير العمل، قم بذاكرة التخزين المؤقت لدليل تثبيت CLI باستخدام actions/cache الإجراء :

      - name: Cache MyCLI
        uses: actions/cache@v4
        with:
          path: ~/.mycli
          key: mycli-${{ runner.os }}-${{ inputs.version }}

وهذا يضمن أن عمليات التشغيل اللاحقة تعيد استخدام تثبيت CLI المخزن مؤقتا، ما يقلل من وقت الإعداد.

أفضل الممارسات لإجراءات إعداد CLI

أفضل الممارسات	الوصف
استخدام تعيين الإصدار	السماح للمستخدمين بتحديد إصدار CLI عبر `inputs.version`.
معالجة الأخطاء بشكل صحيح	يستخدم `core.setFailed()` للخروج من الأخطاء.
تثبيت ذاكرة التخزين المؤقت CLI	تحسين أداء سير العمل باستخدام `actions/cache`.
توفير الوثائق	شرح الاستخدام والمدخلات في `README.md`.

استكشاف أخطاء إجراءات JavaScript وإصلاحها

عند العمل مع إجراءات GitHub المستندة إلى JavaScript، قد تواجه سلوكا أو أخطاء أو فشلا غير متوقع أثناء تنفيذ سير العمل. توفر هذه الوحدة تقنيات وأدوات لمساعدتك في تحديد المشكلات وحلها في إجراءات JavaScript.

سيناريوهات استكشاف الأخطاء وإصلاحها الشائعة

المشكلة	السبب المحتمل	الإصلاح المقترح
فشل الإجراء مع تتبع المكدس	خطأ في بناء الجملة أو وقت التشغيل في `index.js`	استخدام `console.log()` السجلات والتحقق منها
المدخلات هي `undefined`	اسم إدخال غير صحيح أو إدخال مفقود	التحقق من `action.yml` كيفية تمرير الإدخالات
لم يتم تعيين متغيرات البيئة	`core.exportVariable` أو `process.env` لم يتم استخدامها بشكل صحيح	مراجعة إعداد التعليمات البرمجية للمتغيرات
لم يتم العثور على الملف	المسارات النسبية المفقودة	استخدام `__dirname` أو المسارات الكاملة للملفات
لم تتم استعادة ذاكرة التخزين المؤقت	خطأ `key` أو `path` قيم	التحقق من تكوين ذاكرة التخزين المؤقت والمفاتيح

استخدام التسجيل لتصحيح الأخطاء

تسجيل الرسائل باستخدام `core.info`و `core.debug`و `console.log`

const core = require('@actions/core');

core.info("This is an info message");
core.debug("This is a debug message");
console.log("This is a raw console log");

✅ استخدم core.debug لسجلات تتبع الأخطاء — تظهر فقط عند تعيين ACTIONS_STEP_DEBUG إلى true.

تمكين تسجيل تتبع الأخطاء

يمكنك تمكين سجلات تتبع الأخطاء على مستوى الخطوة عن طريق تعيين السر التالي:

ACTIONS_STEP_DEBUG=true

لتمكين سجلات تشخيص المشغل، قم بتعيين:

ACTIONS_RUNNER_DEBUG=true

تعيين البيانات السرية لتصحيح الأخطاء

انتقل إلى مستودع GitHub الخاص بك.
انتقل إلى Settings>Secrets and variables>Actions.
أضف أسرارا جديدة بالأسماء والقيم التالية:
- ACTIONS_STEP_DEBUG: true
- ACTIONS_RUNNER_DEBUG: true

فحص سجلات سير العمل

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

عرض السجلات التفصيلية
التحقق من الإخراج القياسي (stdout)
راجع التعليمة البرمجية للخروج من البرامج النصية
تحديد الاستثناءات غير المعالجة

🔍 مثال على إخراج السجل

Error: Cannot find module '@actions/core'
Require stack:
- /home/runner/work/_actions/my-org/my-action/index.js

✅ إصلاح: قم بتشغيل تثبيت @actions/core npm وتثبيت node_modules (أو استخدام ncc لتجميع الإجراء).

اختبار الإجراء محليا

استخدام الفعل - أداة CLI لتشغيل إجراءات GitHub محليا. مثال:

act -j test

🛠 تأكد من محاكاة بيئة GitHub بشكل صحيح عند الاختبار محليا.

معالجة الأخطاء بأمان

التقاط الاستثناءات والفشل مع الرسائل المفيدة:

try {
  // your logic
} catch (error) {
  core.setFailed(`Action failed with error: ${error.message}`);
}

🔁 يضمن هذا أن GitHub يوقف سير العمل عند الخطأ ويوفر سجلات قابلة للقراءة.

أفضل الممارسات لتصحيح أخطاء إجراءات JavaScript

مارس	الوصف
استخدام core.debug()	إخفاء السجلات المطولة ما لم يتم تمكين تصحيح الأخطاء.
التحقق من صحة action.yml	تأكد من تحديد المدخلات والمخرجات بشكل صحيح.
رمز المجموعة	استخدم `@vercel/ncc` لتحويل JavaScript برمجيا إلى ملف واحد. وهذا يقلل من التبعيات ويضمن تضمين جميع الوحدات النمطية المطلوبة، ما يمنع أخطاء وقت التشغيل الناتجة عن الملفات المفقودة.
اختبار باستخدام الفعل	محاكاة يتم تشغيلها محليا للتكرارات الأسرع.
استخدام try/catch	منع مهام سير العمل من الفشل بصمت.

استكشاف أخطاء إجراءات حاوية Docker وإصلاحها

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

المشكلات الشائعة في إجراءات حاوية Docker

المشكلة	السبب	الإصلاح المقترح
فشل بدء الإجراء	`ENTRYPOINT` أو `CMD` تم تكوينه بشكل خاطئ	تأكيد استخدامات `ENTRYPOINT` Dockerfile بشكل صحيح
التبعيات المفقودة	التبعيات غير مثبتة أو تم تكوينها بشكل خاطئ	تأكد من تثبيت جميع الحزم في الصورة
لم يتم تلقي المدخلات	`INPUT_` لم يتم الوصول إلى متغيرات البيئة	استخدام `process.env.INPUT_<INPUT_NAME>` (أو مكافئ shell)
لم يتم العثور على الملف	مسار ملف غير صحيح داخل الحاوية	استخدام المسارات المطلقة أو التحقق من صحة بنية الدليل
تم رفض الإذن	الملف أو البرنامج النصي يفتقر إلى إذن التنفيذ	إضافة `RUN chmod +x <script>` في Dockerfile
حالات الفشل المتعلقة بالشبكة	الخدمات الخارجية غير قابلة للوصول	التحقق من صحة إعدادات الشبكة ومنطق إعادة المحاولة

فهم دورة حياة إجراء Docker

قبل استكشاف الأخطاء وإصلاحها، من المفيد فهم كيفية تشغيل إجراءات حاوية Docker.

1. مشغل سير العمل

يبدأ سير عمل GitHub Actions استجابة لحدث تم تكوينه - مثل pushأو pull_requestأو دليل workflow_dispatch.

2. إعداد المشغل

توفر GitHub جهازا ظاهريا جديدا ( المشغل) لتنفيذ سير العمل. يقوم المشغل بإعداد البيئة عن طريق تنزيل تعريفات الإجراءات وحل التبعيات.

3. حل الإجراء

إذا حدد runs.using: docker الإجراء في ملفه action.yml ، فإن GitHub يتعرف عليه كإجراء يستند إلى Docker.

4. إنشاء الصورة أو سحبها

ينشئ GitHub صورة Docker المحددة في الإجراء Dockerfile أو يسحب صورة تم إنشاؤها مسبقا إذا تم تحديدها. تحدد هذه الصورة البيئة التي يتم فيها تشغيل رمز الإجراء.

5. تنفيذ الحاوية

يقوم المشغل بتشغيل حاوية Docker، ويحمل مساحة العمل، ويدخل متغيرات البيئة، بما في ذلك البيانات السرية والمدخلات المحددة في سير العمل.

6. عمليات تشغيل نقطة الإدخال

ينفذ entrypoint GitHub الأمر من Dockerfile داخل الحاوية. هذا هو المكان الذي يتم فيه تشغيل منطق الإجراء المخصص، عادة ما يكون برنامج نصي أو تطبيق.

7. معالجة النتائج

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

ملاحظة: تعمل إجراءات حاوية Docker في بيئة نظيفة ومعزولة. يجب تعريف حالة نظام الملفات والأدوات المثبتة ومتغيرات البيئة داخل Dockerfile.

تقنيات تصحيح الأخطاء

1. إضافة تسجيل

استخدم عبارات echo أو printf أو logging في البرنامج النصي لنقطة الإدخال:

echo "Starting Docker action..."
echo "Input VALUE: $INPUT_VALUE"

سجل جميع المدخلات والخطوات الهامة لتشخيص مكان حدوث الفشل.

2. الإنشاء والاختبار محليا

استخدم Docker على جهازك لمحاكاة سلوك الحاوية:

docker build -t my-action .
docker run -e INPUT_NAME=value my-action

تأكد من أن متغيرات البيئة تحاكي تلك التي يعينها GitHub.

3. استخدام CLI الفعل لمحاكاة مهام سير عمل GitHub

تثبيت act لتشغيل مهام سير عمل GitHub محليا:

act -j test-job

رائع لاختبار إجراءات Docker في مهام سير العمل دون الدفع إلى GitHub.

4. التحقق من صحة تكوين Dockerfile

تأكد من تحديد إما ENTRYPOINT أو CMD. انسخ البرامج النصية إلى الصورة وامنحها إذن التنفيذ:

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

5. فحص سجلات GitHub

انقر فوق تشغيل سير عمل فاشل، وقم بتوسيع كل خطوة، وافحص:

سجلات بناء Docker
الإخراج القياسي والخطأ القياسي من الحاوية
غالبا ما تكشف رموز الخروج وتتبعات 🔍 المكدس السجلات عن الحزم المفقودة أو مشكلات بناء الجملة أو أخطاء الأذونات.

مثال: خطأ نقطة الإدخال

Error: container_linux.go:380: starting container process caused "exec: \"/entrypoint.sh\": permission denied"

✅ إصلاح: أضف RUN chmod +x /entrypoint.sh في Dockerfile.

تعيين متغير البيئة

إدخال GitHub	متغير بيئة Docker
`with: name: test`	`INPUT_NAME=test`
`GITHUB_WORKSPACE`	تم التعيين في `/github/workspace`
`GITHUB_EVENT_NAME`	الحدث الذي أدى إلى تشغيل سير العمل

echo "Input was $INPUT_NAME"
echo "Working dir: $GITHUB_WORKSPACE"

استخدام أسرار استكشاف الأخطاء وإصلاحها

تمكين التسجيل الإضافي عن طريق إضافة هذه الأسرار إلى المستودع أو المؤسسة:

سر	الوصف
`ACTIONS_STEP_DEBUG`	تمكين تسجيل تتبع الأخطاء
`ACTIONS_RUNNER_DEBUG`	تمكين تشخيصات المشغل

أفضل الممارسات لتصحيح أخطاء إجراء Docker

أفضل الممارسات	لماذا
استخدام التسجيل بسخاء	يساعد على تتبع نقاط الفشل
تعيين chmod +x دائما	تجنب أخطاء الأذونات على البرامج النصية shell
التحقق من صحة المدخلات في البرنامج النصي	التقاط المدخلات المفقودة أو التي تم تكوينها بشكل غير صحيح في وقت مبكر
تقليل تبعيات الحاوية	الصور الأصغر أسهل في تتبع الأخطاء
اختبار محليا باستخدام docker run أو act	تكرارات أسرع وملاحظات فورية

الملاحظات

هل كانت هذه الصفحة مفيدة؟