github pages deploy action
v4.7.2
نشر مشروعك تلقائيًا على صفحات github مع إجراءات github. يمكن تكوين هذا الإجراء لدفع التعليمات البرمجية جاهزة للإنتاج في أي فرع تريده ، بما في ذلك صفحات GH ومستندات . يمكنه أيضًا التعامل مع عمليات نشر المستودع المتقاطع ويعمل مع GitHub Enterprise أيضًا.
أصبح الحفاظ على هذا المشروع ممكنًا من قبل جميع المساهمين والرعاة. إذا كنت ترغب في رعاية هذا المشروع وأن يكون شعار الرمزية أو شركتك يظهر أدناه ، فانقر هنا. ؟
يمكنك تضمين الإجراء في سير العمل الخاص بك للتشغيل على أي حدث تدعمه إجراءات GitHub. إذا كان الفرع البعيد الذي ترغب في نشره إليه غير موجود بالفعل ، فسيقوم الإجراء بإنشائه لك. سيحتاج سير العمل أيضًا إلى تضمين خطوة actions/checkout قبل تشغيل سير العمل هذا حتى يعمل النشر. إذا كنت تنوي إجراء عمليات نشر متعددة في تتابع سريع ، فقد تحتاج إلى الاستفادة من معلمة التزامن في سير العمل الخاص بك لمنع التداخل.
يمكنك عرض مثال على هذا أدناه.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build-and-deploy :
concurrency : ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build # The folder the action should deploy. ملحوظة
يجب عليك تكوين مستودعك للنشر من الفرع الذي تضغط عليه. للقيام بذلك ، انتقل إلى إعدادات المستودع الخاص بك ، وانقر على Pages ، واختر Deploy from a Branch من منسدلة Source . من هناك حدد الفرع الذي قمت بتزويده بالحركة. في معظم الحالات ، سيكون هذا هو gh-pages لأن هذا هو الافتراضي.
إذا كنت ترغب في صنعه ، فإن سير العمل يؤدي فقط إلى أحداث الدفع إلى فروع محددة ، فيمكنك تعديل القسم on .
on :
push :
branches :
- main تحذير
إذا لم تقم بتزويد الإجراء برمز الوصول أو مفتاح SSH ، فيجب عليك الوصول إلى إعدادات المستودعات الخاصة بك وتقديم Read and Write Permissions إلى GITHUB_TOKEN المقدمة ، وإلا فإنك ستواجه مشكلات إذن. بدلاً من ذلك ، يمكنك تعيين ما يلي في ملف سير العمل الخاص بك لمنح الإجراء الأذونات التي يحتاجها.
permissions :
contents : write يجب تكوين with من سير العمل قبل أن يعمل الإجراء. يمكنك إضافة هذه في with الموجود في الأمثلة أعلاه. يجب الرجوع إلى أي secrets باستخدام بناء جملة القوس وتخزينه في قائمة Settings/Secrets مستودع GitHub. يمكنك معرفة المزيد حول ضبط متغيرات البيئة مع إجراءات github هنا.
يجب تكوين الخيارات التالية من أجل إجراء نشر.
| مفتاح | معلومات القيمة | يكتب | مطلوب |
|---|---|---|---|
folder | المجلد في مستودعك الذي تريد نشره. إذا كان البرنامج النصي للبناء الخاص بك يجمع إلى دليل يسمى build ، فستضعه هنا. إذا كنت ترغب في نشر دليل الجذر ، يمكنك وضع . هنا. يمكنك أيضًا الاستفادة من مسارات الملف المطلقة عن طريق إعداد ~ إلى مسار المجلد الخاص بك. لاحظ أنه لن يتم نشر أي ملفات/مجلدات مطابقة .gitignore بعض الأدوات تلقائيًا ملف .gitignore للبناء. | with | نعم |
بشكل افتراضي ، لا يحتاج الإجراء إلى أي تكوين رمز ويستخدم رمز Github Github Scroped Scroped لإجراء النشر. إذا كنت بحاجة إلى مزيد من التخصيص ، فيمكنك تعديل نوع النشر باستخدام الخيارات التالية.
| مفتاح | معلومات القيمة | يكتب | مطلوب |
|---|---|---|---|
token | هذا الخيار الافتراضي إلى الرمز المميز GitHub Scroped. ومع ذلك ، إذا كنت بحاجة إلى مزيد من الأذونات لأشياء مثل نشر مستودع آخر ، فيمكنك إضافة رمز وصول شخصي (PAT) هنا. يجب تخزين هذا في secrets / with القائمة كسرية . نوصي باستخدام حساب خدمة بأقل أذونات ضرورية ونوصي عند إنشاء PAT جديد تقوم بتحديد أقل نطاقات الإذن اللازمة. تعرف على المزيد حول إنشاء الأسرار المشفرة واستخدامها هنا. | with | لا |
ssh-key | يمكنك تكوين الإجراء للنشر باستخدام SSH عن طريق تعيين هذا الخيار على مفتاح SSH الخاص المخزن كسر . يمكن أيضًا true على استخدام تكوين عميل SSH موجود. لمزيد من المعلومات التفصيلية حول كيفية إضافة زوج مفتاح SSH العام/الخاص ، يرجى الرجوع إلى قسم مفاتيح Deploy في هذا ReadMe. | with | لا |
| مفتاح | معلومات القيمة | يكتب | مطلوب |
|---|---|---|---|
branch | هذا هو الفرع الذي ترغب في نشره ، على سبيل المثال ، gh-pages أو docs . الإعدادات الافتراضية gh-pages . | with | لا |
git-config-name | يتيح لك تخصيص الاسم المرفق بتكوين Git الذي يتم استخدامه عند الضغط على النشر. إذا لم يتم تضمين ذلك ، فسيستخدم الاسم في سياق GitHub ، يليه اسم الإجراء. | with | لا |
git-config-email | يتيح لك تخصيص البريد الإلكتروني المرفق بتكوين Git الذي يتم استخدامه عند الضغط على النشر. إذا لم يتم تضمين ذلك ، فسيستخدم البريد الإلكتروني في سياق github ، يليه بريد إلكتروني عام github عام. يمكنك تضمين <> للقيمة إذا كنت ترغب في حذف هذا الحقل تمامًا ودفع الالتزامات دون بريد إلكتروني. | with | لا |
repository-name | يتيح لك تحديد مسار مستودع مختلف طالما أن لديك أذونات للدفع إليه. يجب أن يتم تنسيق هذا مثل: JamesIves/github-pages-deploy-action . ستحتاج إلى استخدام PAT في إدخال token لخيار التكوين هذا للعمل بشكل صحيح. | with | لا |
target-folder | إذا كنت ترغب في دفع محتويات مجلد النشر إلى دليل معين على فرع النشر ، يمكنك تحديده هنا. | with | لا |
commit-message | إذا كنت بحاجة إلى تخصيص رسالة الالتزام بتكامل ، فيمكنك القيام بذلك. | with | لا |
clean | يمكنك استخدام هذا الخيار لحذف الملفات من وجهة النشر التي لم تعد موجودة في مصدر النشر الخاص بك. إحدى حالات الاستخدام هي إذا قام مشروعك بإنشاء ملفات تجزئة تختلف من الإنشاء إلى الإنشاء. لن يؤثر استخدام clean .git أو .github أو .ssh . يتم تشغيل هذا الخيار بشكل افتراضي ويمكن تبديله عن طريق ضبطه على false . | with | لا |
clean-exclude | إذا كنت بحاجة إلى استخدام clean ولكنك ترغب في الحفاظ على بعض الملفات أو المجلدات ، فيمكنك استخدام هذا الخيار. يجب أن يحتوي هذا على كل نمط كخط واحد في سلسلة متعددة. | with | لا |
dry-run | لا تقم فعليًا بالتراجع ، ولكن استخدم --dry-run على git push Invocations بدلاً من ذلك. | with | لا |
single-commit | يمكن تبديل هذا الخيار إلى true إذا كنت تفضل أن يكون لديك التزام واحد في فرع النشر بدلاً من الحفاظ على التاريخ الكامل. سيؤدي استخدام هذا الخيار أيضًا إلى قضاء أي تاريخ موجود من فرع النشر . | with | لا |
force | قوة النشر الجديدة للكتابة فوق الإصدار السابق ؛ خلاف ذلك ، حاول إعادة نشر عمليات نشر جديدة على أي نشرات موجودة. يتم تشغيل هذا الخيار بشكل افتراضي ويمكن تبديله عن طريق تعيينه على false ، والذي قد يكون مفيدًا إذا كانت هناك عمليات نشر متعددة في فرع واحد. | with | لا |
attempt-limit | كم عدد محاولات Rebase قبل تعليق الوظيفة. هذا الخيار يتخلف عن 3 وقد يكون مفيدًا للزيادة عندما يكون هناك عمليات نشر متعددة في فرع واحد. | with | لا |
silent | إسكات الإجراء الذي يمنعه من عرض رسائل GIT. | with | لا |
tag | أضف علامة إلى الالتزام. يعمل فقط عندما لا يتم استخدام dry-run . | with | لا |
من خلال الإجراء الذي تم تكوينه بشكل صحيح ، يجب أن ترى سير العمل يثير النشر في ظل الشروط التي تم تكوينها.
سيقوم الإجراء بتصدير متغير بيئة يسمى deployment_status الذي يمكنك استخدامه في سير العمل الخاص بك لتحديد ما إذا كان النشر ناجحًا أم لا. يمكنك العثور على شرح لكل نوع حالة أدناه.
| حالة | وصف |
|---|---|
success | تشير حالة success إلى أن الإجراء كان قادرًا على النشر بنجاح في الفرع. |
failed | تشير الحالة failed إلى أن الإجراء واجه خطأً أثناء محاولة النشر. |
skipped | تشير الحالة skipped إلى أن الإجراء خرج مبكرًا لأنه لم يكن هناك شيء جديد للنشر. |
تم تعيين هذه القيمة أيضًا كخطوة للإخراج deployment-status .
إذا كنت تفضل استخدام مفتاح نشر SSH بدلاً من الرمز المميز ، فيجب عليك أولاً إنشاء مفتاح SSH جديد عن طريق تشغيل الأمر الطرفي التالي ، واستبدال البريد الإلكتروني مع واحد متصل بحساب github الخاص بك.
ssh-keygen -t rsa -m pem -b 4096 -C " [email protected] " -N " " بمجرد إنشاء زوج المفاتيح ، يجب عليك إضافة محتويات المفتاح العام ضمن قائمة مفاتيح نشر المستودع الخاص بك. يمكنك العثور على هذا الخيار من خلال الانتقال إلى Settings > Deploy Keys ، يمكنك تسمية المفتاح العام كل ما تريد ، لكنك تحتاج إلى منحه للوصول إلى الكتابة. بعد ذلك ، أضف محتويات المفتاح الخاص إلى قائمة Settings > Secrets كـ DEPLOY_KEY .
مع هذا التكوين ، يمكنك بعد ذلك تعيين جزء ssh-key من الإجراء على مفتاحك الخاص المخزنة كسر.
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : site
ssh-key : ${{ secrets.DEPLOY_KEY }} name : Build and Deploy
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txt
ssh-key : ${{ secrets.DEPLOY_KEY }} بدلاً من ذلك ، إذا قمت بالفعل بتكوين عميل SSH ضمن خطوة سابقة ، فيمكنك تعيين خيار ssh-key على true للسماح له بالنشر باستخدام عميل SSH موجود. بدلاً من ضبط تكوين العميل ، سيتم التبديل ببساطة إلى استخدام نقاط نهاية SSH الخاصة بـ Github.
تم تطوير هذا الإجراء بشكل أساسي باستخدام Ubuntu. في تكوين وظيفة سير العمل الخاص بك ، يوصى بتعيين خاصية runs-on على ubuntu-latest .
jobs :
build-and-deploy :
runs-on : ubuntu-latest إذا كنت تستخدم نظام تشغيل مثل Windows ، فيمكنك حل هذا باستخدام القطع الأثرية. في تكوين سير العمل الخاص بك ، يمكنك الاستفادة من actions/upload-artifact / actions/download-artifact لنقل مشروعك المبني على وظيفة Windows إلى وظيفة ثانوية ستتعامل مع النشر.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build :
runs-on : windows-latest # The first job utilizes windows-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Upload Artifacts ? # The project is then uploaded as an artifact named 'site'.
uses : actions/upload-artifact@v1
with :
name : site
path : build
deploy :
concurrency : ci-${{ github.ref }}
needs : [build] # The second job must depend on the first one to complete before running and uses ubuntu-latest instead of windows.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Download Artifacts ? # The built project is downloaded into the 'site' folder.
uses : actions/download-artifact@v1
with :
name : site
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : ' site ' # The deployment folder should match the name of the artifact. Even though our project builds into the 'build' folder the artifact name of 'site' must be placed here. إذا كنت تستخدم حاوية في سير العمل الخاص بك ، فقد تحتاج إلى تشغيل خطوة إضافية لتثبيت rsync لأن هذا الإجراء يعتمد عليه. يمكنك عرض مثال على هذا أدناه.
- name : Install rsync
run : |
apt-get update && apt-get install -y rsync
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4 إذا كنت تستخدم مجالًا مخصصًا وتتطلب ملفًا CNAME ، أو إذا كنت بحاجة إلى استخدام ملف .nojekyll ، يمكنك ارتكاب هذه الملفات بأمان مباشرة في فرع النشر دون تجاوزها بعد كل نشر ، بالإضافة إلى ذلك ، يمكنك تضمين هذه الملفات في مجلد النشر الخاص بك لتحديثها. إذا كنت بحاجة إلى إضافة ملفات إضافية إلى النشر الذي يجب تجاهله من خلال خطوات التنظيف ، فيمكنك استخدام خيار clean-exclude .
name : Build and Deploy
permissions :
contents : write
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txtإذا كنت ترغب في إزالة هذه الملفات ، فيجب عليك الذهاب إلى فرع النشر مباشرة لإزالتها. هذا هو منع التغييرات العرضية في البرنامج النصي للنشر من إنشاء تغييرات كسر.
