تخصيص سير العمل باستخدام متغيرات البيئة

مكتمل

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

لتنفيذ هذه العملية، ستتعلم كيفية:

• استخدم متغيرات البيئة الافتراضية والمخصصة.
• الوصول إلى المعلومات السياقية في مهام سير العمل.
• تعيين متغيرات البيئة في نطاقات سير عمل مختلفة.
• استخدم البرامج النصية المخصصة مع الكلمة الأساسية run.
• تطبيق حماية البيئة على عمليات التوزيع.

متغيرات البيئة والسياقات الافتراضية

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

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

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

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

يستخدم هذا المثال github.ref السياق للتحقق من الفرع الذي أطلق سير العمل. إذا كان الفرع هو main، يتم تنفيذ المشغل وطباعة "النشر إلى خادم الإنتاج على الفرع $GITHUB_REF." يتم استخدام متغير $GITHUB_REF البيئة الافتراضي في المشغل للإشارة إلى الفرع. لاحظ أن متغيرات البيئة الافتراضية كلها كبيرة؛ بينما متغيرات السياق كلها صغيرة.

المعلومات السياقية المتوفرة في سير العمل

استخدم السياقات للوصول إلى معلومات حول عمليات تشغيل سير العمل والمتغيرات وبيئات المشغل والمهام والخطوات. كل سياق هو كائن يحتوي على خصائص يمكن أن تكون كائنات أو سلاسل أخرى. تتضمن githubالسياقات المتوفرة و envو varsو jobjobsو stepsو runnerوsecretsstrategymatrixneeds.inputs

يسرد الجدول التالي سياقات سير العمل ووصفه:

سياق	‏‏الوصف
github	معلومات حول تشغيل سير العمل. لمزيد من المعلومات، راجع github السياق.
env	يحتوي على المتغيرات التي قمت بتعيينها في سير عمل أو مهمة أو خطوة. لمزيد من المعلومات، راجع env السياق.
vars	يحتوي على متغيرات قمت بتعيينها على مستوى المستودع أو المؤسسة أو البيئة. لمزيد من المعلومات، راجع vars السياق.
job	معلومات حول الوظيفة قيد التشغيل حاليا. لمزيد من المعلومات، راجع job السياق.
jobs	بالنسبة إلى مهام سير العمل القابلة لإعادة الاستخدام فقط، يحتوي على مخرجات الوظائف من سير العمل القابل لإعادة الاستخدام. لمزيد من المعلومات، راجع jobs السياق.
steps	معلومات حول الخطوات التي تم تشغيلها في الوظيفة الحالية. لمزيد من المعلومات، راجع steps السياق.
runner	معلومات حول المشغل الذي يقوم بتشغيل المهمة الحالية. لمزيد من المعلومات، راجع runner السياق.
secrets	يحتوي على أسماء وقيم الأسرار المتوفرة لتشغيل سير العمل. لمزيد من المعلومات، راجع secrets السياق.
strategy	معلومات حول استراتيجية تنفيذ المصفوفة للوظيفة الحالية. لمزيد من المعلومات، راجع strategy السياق.
matrix	يحتوي على خصائص المصفوفة المعرفة في سير العمل التي تنطبق على المهمة الحالية. لمزيد من المعلومات، راجع matrix السياق.
needs	يحتوي على مخرجات جميع الوظائف التي يتم تعريفها على أنها تبعية للوظيفة الحالية. لمزيد من المعلومات، راجع needs السياق.
inputs	يحتوي على مدخلات سير عمل قابل لإعادة الاستخدام أو يتم تشغيله يدويا. لمزيد من المعلومات، راجع inputs السياق.

تتوفر سياقات مختلفة في أوقات مختلفة في تشغيل سير العمل. على سبيل المثال، يمكنك استخدام secrets السياق فقط في أماكن معينة في وظيفة. يمكنك أيضا استخدام بعض الدالات، مثل الدالة hashFiles ، فقط في أماكن معينة.

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

مفتاح سير العمل	سياق	دوال خاصة
run-name	github، ، inputsvars	اي
concurrency	github، ، inputsvars	اي
env	github، ، secrets، inputsvars	اي
jobs.<job_id>.concurrency	github، needs، strategy، matrix، ، inputsvars	اي
jobs.<job_id>.container	github، needs، strategy، matrix، ، varsinputs	اي
jobs.<job_id>.container.credentials	github، needs، strategy، matrix، env، vars، ، secrets، inputs	اي
jobs.<job_id>.container.env.<env_id>	github، needs، strategy، matrix، job، runner، env، vars، ، secretsinputs	اي
jobs.<job_id>.container.image	github، needs، strategy، matrix، ، varsinputs	اي
jobs.<job_id>.continue-on-error	github، needs، strategy، vars، ، matrixinputs	اي
jobs.<job_id>.defaults.run	github، needs، strategy، matrix، env، ، varsinputs	اي
jobs.<job_id>.env	github، needs، strategy، matrix، vars، ، secretsinputs	اي
jobs.<job_id>.environment	github، needs، strategy، matrix، ، varsinputs	اي
jobs.<job_id>.environment.url	github، needs، strategy، matrix، job، runner، env، vars، ، stepsinputs	اي
jobs.<job_id>.if	github، ، needs، varsinputs	always، ، canceled، successfailure
jobs.<job_id>.name	github، needs، strategy، matrix، ، varsinputs	اي
jobs.<job_id>.outputs.<output_id>	github، needs، strategy، matrix، job، runner، env، vars، secrets، ، ، ، stepsinputs	اي
jobs.<job_id>.runs-on	github، needs، strategy، matrix، ، varsinputs	اي
jobs.<job_id>.secrets.<secrets_id>	github، needs، strategy، matrix، secrets، ، inputsvars	اي
jobs.<job_id>.services	github، needs، strategy، matrix، ، varsinputs	اي
jobs.<job_id>.services.<service_id>.credentials	github، needs، strategy، matrix، env، vars، ، secrets، inputs	اي
jobs.<job_id>.services.<service_id>.env.<env_id>	github، needs، strategy، matrix، job، runner، env، vars، ، secretsinputs	اي
jobs.<job_id>.steps.continue-on-error	github، needs، strategy، matrix، job، runner، env، vars، secrets، ، ، ، stepsinputs	ملفات التجزئة
jobs.<job_id>.steps.env	github، needs، strategy، matrix، job، runner، env، vars، secrets، ، ، ، stepsinputs	hashFiles
jobs.<job_id>.steps.if	github، needs، strategy، matrix، job، runner، env، vars، ، stepsinputs	always، canceled، success، ، failurehashFiles
jobs.<job_id>.steps.name	github، needs، strategy، matrix، job، runner، env، vars، secrets، ، ، ، stepsinputs	hashFiles
jobs.<job_id>.steps.run	github، needs، strategy، matrix، job، runner، env، vars، secrets، ، ، ، stepsinputs	hashFiles
jobs.<job_id>.steps.timeout-minutes	github، needs، strategy، matrix، job، runner، env، vars، secrets، ، ، ، stepsinputs	hashFiles
jobs.<job_id>.steps.with	github، ، needsstrategy، matrix، job، ، runner، env، vars، secrets، ، steps،inputs	hashFiles
jobs.<job_id>.steps.working-directory	github، ، needsstrategy، matrix، job، ، runner، env، vars، secrets، ، steps،inputs	hashFiles
jobs.<job_id>.strategy	github، احتياجات، vars، ، inputs	اي
jobs.<job_id>.timeout-minutes	github، needs، strategy، matrix، ، varsinputs	اي
jobs.<job_id>.with.<with_id>	github، needs، strategy، matrix، ، inputsvars	اي
on.workflow_call.inputs.<inputs_id>.default	github، ، inputsvars	اي
on.workflow_call.outputs.<output_id>.value	github، الوظائف، ، varsinputs	اي

متغيرات البيئة المخصصة

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

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

تعيين متغيرات البيئة المخصصة في سير عمل

يمكنك تعريف متغيرات البيئة التي يتم تحديد نطاقها لسير العمل بأكمله باستخدام env في المستوى الأعلى من ملف سير العمل. حدد نطاق محتويات مهمة ضمن سير عمل باستخدام jobs.<job_id>.env. يمكنك تحديد نطاق متغير بيئة في خطوة معينة داخل وظيفة باستخدام jobs.<job_id>.steps[*].env.

فيما يلي مثال يوضح جميع السيناريوهات الثلاثة في ملف سير العمل:

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

استخدام سياق افتراضي في سير عمل

يعين النظام الأساسي GitHub متغيرات البيئة الافتراضية. لا يتم تعريفها في سير عمل، ولكن يمكنك استخدام متغير بيئة افتراضي في سير عمل في السياق المناسب. تبدأ معظم هذه المتغيرات، بخلاف CI، ب GITHUB_* أو RUNNER_*. لا يمكن الكتابة فوق النوعين الأخيرين. أيضا، تحتوي هذه المتغيرات الافتراضية على خاصية سياق مقابلة وبالمثل مسماة. على سبيل المثال، RUNNER_* سلسلة المتغيرات الافتراضية لها خاصية سياق مطابقة ل runner.*.

فيما يلي مثال على كيفية الوصول إلى المتغيرات الافتراضية في سير العمل من خلال تطبيق هذه الطرق:

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

لمزيد من المعلومات، راجع متغيرات البيئة الافتراضية.

تمرير متغيرات البيئة المخصصة إلى سير عمل

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

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

إليك مثال:

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'

إضافة حماية البيئة

يمكنك إضافة قواعد حماية للبيئات المحددة لمستودع GitHub الخاص بك.

لإضافة بيئة، في المستودع الخاص بك:

1. حدد الإعدادات.

   

2. في الجزء الأيمن، حدد Environment.

   

3. حدد الزر New environment لإضافة بيئة وتكوينها وإضافة الحماية.

   

حول البيئات

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

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

عندما يشير سير العمل إلى بيئة، تظهر البيئة في عمليات نشر المستودع.

قواعد حماية البيئة

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

فيما يلي شرح لقواعد الحماية هذه:

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

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

  لمزيد من المعلومات حول مراجعة المهام التي تشير إلى بيئة مع المراجعين المطلوبين، راجع مراجعة عمليات النشر.

• قواعد إسقاط مؤقت الانتظار. يمكنك استخدام قاعدة حماية مؤقت الانتظار لتأخير مهمة لفترة زمنية محددة بعد تشغيل المهمة في البداية قبل متابعة نشر البيئة. يجب أن يكون الوقت (بالدقائق) عددا صحيحا بين 1 و43200 (30 يوما). لا يتم احتساب وقت الانتظار في وقت الفوترة.

• قواعد حماية الفروع والعلامات. يمكنك استخدام فرع النشر وقواعد حماية العلامات لتقييد الفروع والعلامات المستخدمة للتوزيع في البيئة. لديك العديد من الخيارات لفرع النشر وقواعد حماية العلامات لبيئة ما.

  • لا يوجد قيد يحدد أي قيود على الفرع أو العلامة التي يمكن نشرها في البيئة.
  • تسمح الفروع المحمية فقط بالفروع مع تمكين قواعد حماية الفروع للنشر في البيئة. إذا لم يتم تعريف قواعد حماية الفرع لأي فرع في المستودع، فيمكن نشر جميع الفروع. يضمن إعداد الفروع والعلامات المحددة نشر الفروع والعلامات التي تطابق أنماط الاسم المحددة فقط في البيئة.
  • إذا حددت releases/* كفرع نشر أو قاعدة علامة، يمكن فقط للفرع أو العلامة التي تحمل اسما يبدأ بالنشر releases/ في البيئة. (لا تتطابق أحرف البدل مع /. لمطابقة الفروع أو العلامات التي تبدأ ب release/ وتحتوي على شرطة مائلة واحدة أخرى، استخدم release/*/*.) إذا قمت بإضافة main كقاعدة فرع، يمكن للفرع المسمى main أيضا النشر إلى البيئة.

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

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

  

إشعار

إذا كان لديك خطة GitHub Free أو GitHub Pro أو GitHub Team، فإن قواعد إسقاط توزيع البيئة متاحة فقط للمستودعات العامة؛ باستثناء قواعد حماية الفرع والعلامة. بالنسبة للمستخدمين الذين لديهم خطط GitHub Pro أو GitHub Team، تتوفر قواعد حماية الفروع والعلامات أيضا للمستودعات الخاصة.

البرامج النصية في سير العمل

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

jobs:
  example-job:
    steps:
      - run: npm install -g bats

في هذا المثال، يمكنك استخدام npm لتثبيت حزمة bats اختبار البرنامج باستخدام run الكلمة الأساسية . يمكنك أيضاً تشغيل برنامج نصي كإجراء. يمكنك تخزين البرنامج النصي في المستودع الخاص بك، وغالباً ما يتم ذلك في دليل .github/scripts/، ثم توفير المسار ونوع الغلاف باستخدام الكلمة الأساسية run.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash