إجراءات GitHub لـ Next.js: ذاكرة التخزين المؤقت والوبر والتحقق من الكتابة والاختبارات والحماية الرئيسية
الهدف
لن يدخل أي التزام إلى main ما لم يتم اجتياز اختبار Linter والتحقق من النوع والاختبارات. تتم عمليات التحقق بسرعة بسبب ذاكرة التخزين المؤقت ولا تضيع دقائق على إشعارات الدفع القديمة. يوجد أدناه إعدادات سير العمل والمستودع التي تحولها من توصية إلى متطلب إلزامي.
سير العمل
# .github/workflows/ci.yml
name: CI
on:
pull_request:
push:
branches: [main]
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
jobs:
quality:
name: lint-typecheck-test
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci
- name: Lint
run: npm run lint
- name: Typecheck
run: npx tsc --noEmit
- name: Unit tests
run: npm test -- --run
build:
name: build
runs-on: ubuntu-latest
needs: quality
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci
- uses: actions/cache@v4
with:
path: .next/cache
key: nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
restore-keys: |
nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-
- run: npm run buildما هو المهم هنا
`concurrency` مع `cancel-in-progress`. تؤدي ثلاث دفعات متتالية إلى فرع واحد إلى تشغيل ثلاث عمليات، ولا يلزم سوى الدفعة الأخيرة. يؤدي التجميع حسب github.ref إلى إرجاع المجموعات السابقة لنفس الفرع أو العلاقات العامة، لكنه لا يؤثر على الفروع الأخرى.
`permissions: contents: read`. بشكل افتراضي، يمكن لـ GITHUB_TOKEN الحصول على أذونات الكتابة. ليست هناك حاجة إليها لإجراء عمليات التحقق، وإذا تم اختراق التبعية التي يتم تشغيلها في CI، فإن الرمز المميز الأقل امتيازًا يحد من الضرر.
ذاكرة التخزين المؤقت npm. يقوم setup-node مع cache: npm بتخزين ذاكرة التخزين المؤقت للحزمة العامة باستخدام تجزئة ملف القفل. npm ci لا يزال يقوم بتثبيت node_modules من البداية، ولكن بدون التنزيل من الشبكة. لا يجب عليك تخزين node_modules نفسه: إذا قمت بتغيير إصدار العقدة، ستصبح الوحدات الأصلية غير متوافقة.
ذاكرة التخزين المؤقت `.next/cache`. يعيد Next.js استخدام نتائج البنية السابقة. يتضمن المفتاح التجزئة المصدر، ويتيح لك restore-keys أخذ أحدث ذاكرة تخزين مؤقت مع نفس ملف القفل إذا لم يكن هناك تطابق تام. بدون ذاكرة التخزين المؤقت هذه، يعرض next build في CI تحذيرًا بشأن غيابها.
`.nvmrc`. إصدار واحد من Node محليًا وفي CI. تعد الاختلافات في الإصدارات سببًا شائعًا لمشكلة "يعمل لصالحي".
البرامج النصية في package.json
{
"scripts": {
"lint": "eslint .",
"typecheck": "tsc --noEmit",
"test": "vitest",
"build": "next build"
}
}لقد تم إهمال الأمر next lint في الإصدارات الجديدة من Next.js، لذلك يتم استدعاء linter مباشرة. يقوم next build بنفسه بالتحقق من الأنواع، ولكن الخطوة المنفصلة tsc --noEmit في المهمة الأولى تفشل مسبقًا ولا تضيع الوقت في الإنشاء.
حماية الرئيسية
يعد سير العمل بدون قواعد المستودع مجرد مؤشر. قم بإعداد مجموعة القواعد (الإعدادات → القواعد → مجموعات القواعد) أو حماية الفرع الكلاسيكية:
- 1.يجب طلب سحب قبل الدمج - يُمنع الدفع المباشر في
main. - 2.يلزم اجتياز عمليات التحقق من الحالة - أضف عمليات التحقق
lint-typecheck-testوbuild. الأسماء مأخوذة من حقلnameالخاص بالمهمة؛ إذا قمت بإعادة تسمية المهمة، فستنتظر القاعدة فحصًا لن يأتي مرة أخرى أبدًا، وسيتعطل العلاقات العامة. - 3.المطالبة بأن تكون الفروع محدثة - يتم فحص العلاقات العامة باستخدام الحالة الأخيرة
main، وليس مع الحالة التي تم أخذها منها في السابق. - 4.دفعات قوة الحظر ومنع حذف الفرع.
- 5.لا تقم بإضافة نفسك إلى قواعد التجاوز "فقط في حالة": يتم استخدام التجاوز على وجه التحديد في المساء عندما تفشل الاختبارات.
أمان سير العمل
- يتم تشغيل الحدث
pull_requestللـ PRs من الشوكات دون الوصول إلى الأسرار - وهذا صحيح. لا تقم بتغييره إلىpull_request_targetمن أجل الأسرار: حيث يتم تنفيذ سير العمل في سياق الفرع الأساسي مع الحقوق، كما أن سحب التعليمات البرمجية من العلاقات العامة يمنح كود الأشخاص الآخرين الوصول إليهم. - إرفاق إجراءات الطرف الثالث من خلال SHA الكامل للالتزام، وليس من خلال العلامة: يمكن تجاوز العلامة. يعد
actions/*الرسمي للإصدار الرئيسي بمثابة حل وسط معقول. - الاحتفاظ بأسرار النشر في البيئات مع التأكيد الإلزامي، وليس في الأسرار العامة للمستودع.
التشخيص
- لا يتم دمج العلاقات العامة، والشيك هو "متوقع - في انتظار الحالة". اسم الشيك المطلوب لا يتطابق مع اسم المهمة، أو لم يبدأ سير العمل بسبب مرشح
paths. إذا لم يبدأ سير العمل مع مرشح المسار، فسيظل الفحص الإلزامي معلقًا. - لا تتم استعادة ذاكرة التخزين المؤقت. يتم عزل ذاكرات التخزين المؤقت حسب الفروع: يرى العلاقات العامة ذاكرة التخزين المؤقت للفرع الخاص به والفرع الأساسي، ولكن ليس للفرع الرئيسي المجاور. الجولة الأولى في فرع جديد تكون دائمًا باردة.
- الاختبارات معلقة حتى انتهاء المهلة. Vitest في وضع المراقبة ينتظر التغييرات. في CI، يتم تعيين المتغير
CI=trueتلقائيًا ويأخذ Vitest ذلك في الاعتبار، ولكن--runالصريح أكثر موثوقية.
##متى يكفي ومتى لا
بالنسبة لفريق مكون من شخصين، تغطي هذه المجموعة الأساسيات. تتم إضافة اختبارات E2E على Playwright كمهمة منفصلة مع needs: build عند ظهور سيناريوهات المستخدم المهمة. إذا استغرق CI أكثر من عشر دقائق، فقم بتقسيم الاختبارات إلى أجزاء من خلال المصفوفة بدلاً من تعطيلها.