إعداد خط أنابيب CI/CD في Cursor: دليل شامل

تقوم خطوط أنابيب التكامل المستمر والنشر المستمر (CI/CD) بأتمتة عملية البناء والاختبار والإصدار، مما يتيح للفرق شحن الكود بأمان وبشكل متكرر. يمتد CI/CD الحديث عبر منصات متعددة — GitHub Actions للمشاريع المستضافة على GitHub، وGitLab CI لمستودعات GitLab، وJenkins لخطوط الأنابيب المستضافة ذاتيًا والقابلة للتخصيص بدرجة عالية. Cursor، بمساعده الذكي المدمج ونموذج الإضافات المتوافق مع VS Code، هو محرر ممتاز لإنشاء وصيانة تكوينات خطوط الأنابيب. يمكنه إنشاء سير العمل من مطالبات اللغة الطبيعية، والتحقق من صحة بناء جملة YAML، وإعادة هيكلة خطوط الأنابيب مع تطور مشروعك.

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

إعداد أدوات CI/CD في Cursor

الإضافات الأساسية

يرث Cursor نظام إضافات VS Code. ثبّت هذه لتسهيل كتابة خطوط الأنابيب:

1. YAML (من Red Hat) — التحقق من صحة المخطط لـ GitHub Actions وGitLab CI وملفات Docker Compose.
2. GitHub Actions — تمييز بناء الجملة ومقتطفات لملفات سير العمل.
3. GitLab Workflow — التحقق من صحة GitLab CI وإدارة MR.
4. Docker — كتابة Dockerfile ومساعدات بناء الصور.

تلميح

إضافة YAML تنزّل تلقائيًا مخططات JSON لأنواع الملفات المعروفة. عند إنشاء .github/workflows/deploy.yml، يتحقق Cursor من البنية مقابل مخطط GitHub Actions الرسمي ويوفر الإكمال التلقائي لكل حقل.

هيكل المشروع لـ CI/CD

يشتمل المشروع الجاهز لـ CI/CD عادةً على:

project/
  ├── .github/
  │   └── workflows/
  │       ├── ci.yml
  │       └── deploy.yml
  ├── .gitlab/
  │   └── ci/
  │       └── templates.yml
  ├── .jenkins/
  │   └── Jenkinsfile
  ├── src/
  ├── tests/
  ├── Dockerfile
  ├── docker-compose.yml
  └── package.json

GitHub Actions

إنشاء سير العمل الأول

يستخدم GitHub Actions ملفات YAML في .github/workflows/. سير عمل CI أساسي يعمل عند كل دفع وطلب سحب:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

permissions:
  contents: read

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run type-check

      - name: Run tests
        run: npm test -- --coverage

      - name: Upload coverage
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage/
          retention-days: 14

تلميح

استخدم npm ci بدلاً من npm install في CI. أمر ci يثبّت الإصدارات الدقيقة من ملف القفل، وينتج بنيات قابلة للتكرار ويفشل بسرعة عند انحراف ملف القفل.

بنيات المصفوفة

اختبر عبر إصدارات Node.js وأنظمة تشغيل متعددة باستخدام مصفوفة:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm
      - run: npm ci
      - run: npm test

التخزين المؤقت للاعتماديات

سرّع سير العمل من خلال التخزين المؤقت للاعتماديات ومخرجات البناء:

- name: Cache npm
  uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

warning

مفاتيح التخزين المؤقت المبنية فقط على تجزئة package-lock.json ستفوت عندما يتغير ملف القفل. أدرج نظام التشغيل وإصدار Node في المفتاح لتجنب التلوث المتبادل بين بيئات التشغيل.

سير العمل القابل لإعادة الاستخدام

قسّم سير العمل الكبير إلى مكونات قابلة لإعادة الاستخدام:

# .github/workflows/reusable-test.yml
name: Reusable Test

on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
      - run: npm ci
      - run: npm test

استدعه من سير عمل آخر:

jobs:
  test:
    uses: ./.github/workflows/reusable-test.yml
    with:
      node-version: 20

سير عمل النشر

مهمة نشر تعمل فقط على فرع main:

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: test
    environment:
      name: production
      url: https://app.example.com
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy
          aws-region: us-east-1

      - name: Login to ECR
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: |
            123456789012.dkr.ecr.us-east-1.amazonaws.com/app:latest
            123456789012.dkr.ecr.us-east-1.amazonaws.com/app:${{ github.sha }}

      - name: Deploy to ECS
        run: |
          aws ecs update-service --cluster app-cluster --service app-service --force-new-deployment

warning

استخدم GitHub Environments مع المراجعين المطلوبين لعمليات نشر الإنتاج. يضيف هذا بوابة موافقة يدوية قبل تشغيل مهمة النشر، مما يمنع الإصدارات العرضية.

GitLab CI

إعداد .gitlab-ci.yml

يستخدم GitLab CI ملف .gitlab-ci.yml واحدًا في جذر المستودع:

# .gitlab-ci.yml
stages:
  - lint
  - test
  - build
  - deploy

variables:
  NODE_VERSION: "20"
  IMAGE_TAG: $CI_COMMIT_SHORT_SHA

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/

lint:
  stage: lint
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run lint
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm test -- --coverage
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'

build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$IMAGE_TAG .
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker push $CI_REGISTRY_IMAGE:$IMAGE_TAG
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:production:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-ecs:latest
  script:
    - ecs update-task-definition --cluster app-cluster --service app-service --image $CI_REGISTRY_IMAGE:$IMAGE_TAG
  environment:
    name: production
    url: https://app.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  when: manual

تلميح

الكلمة المفتاحية rules في GitLab CI تحل محل بناء جملة only/except القديم. استخدم rules مع شروط if للتحكم الدقيق في وقت تشغيل المهام، وادمجها مع changes لتشغيل المهام فقط عند تعديل الملفات ذات الصلة.

قوالب GitLab CI

قسّم خطوط الأنابيب المعقدة إلى ملفات تضمين:

# .gitlab/ci/test.yml
.test-template:
  stage: test
  image: node:${NODE_VERSION}
  before_script:
    - npm ci
  script:
    - npm test

ضمّنها:

include:
  - local: .gitlab/ci/test.yml

unit-test:
  extends: .test-template
  script:
    - npm run test:unit

المهام المتوازية والمصفوفية

test:
  stage: test
  image: node:${NODE_VERSION}
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
        OS: ["alpine", "slim"]
  script:
    - npm ci
    - npm test

Jenkins

كتابة Jenkinsfile

تستخدم خطوط أنابيب Jenkins DSL قائم على Groovy في Jenkinsfile:

// Jenkinsfile
pipeline {
    agent {
        docker {
            image 'node:20-alpine'
            args '-v $HOME/.npm:/root/.npm'
        }
    }

    environment {
        NODE_ENV = 'production'
        DOCKER_IMAGE = "registry.example.com/app:${env.BUILD_NUMBER}"
    }

    options {
        timeout(time: 30, unit: 'MINUTES')
        disableConcurrentBuilds()
        buildDiscarder(logRotator(numToKeepStr: '20'))
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Install') {
            steps {
                sh 'npm ci'
            }
        }

        stage('Lint') {
            steps {
                sh 'npm run lint'
            }
        }

        stage('Test') {
            steps {
                sh 'npm test -- --coverage'
            }
            post {
                always {
                    junit 'reports/junit.xml'
                    publishHTML(target: [
                        reportDir: 'coverage/lcov-report',
                        reportFiles: 'index.html',
                        reportName: 'Coverage Report'
                    ])
                }
            }
        }

        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }

        stage('Deploy') {
            when {
                branch 'main'
            }
            steps {
                sh "docker build -t ${DOCKER_IMAGE} ."
                sh "docker push ${DOCKER_IMAGE}"
                sh "kubectl rollout restart deployment/app -n production"
            }
        }
    }

    post {
        failure {
            emailext subject: "Build failed: ${env.JOB_NAME} #${env.BUILD_NUMBER}",
                     body: "Check the build at ${env.BUILD_URL}",
                     to: '[email protected]'
        }
        success {
            slackSend channel: '#deploys',
                      message: "Build succeeded: ${env.JOB_NAME} #${env.BUILD_NUMBER}"
        }
    }
}

warning

تعمل Jenkinsfiles بأذونات متحكم Jenkins. لا تستخدم أبدًا sh لاستدعاء أوامر تتضمن مدخلات غير موثوقة، واقتبس دائمًا المتغيرات المُدمجة لمنع حقن الصدفة.

خط أنابيب تعريفي مقابل نصي

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

stage('Conditional Deploy') {
    steps {
        script {
            def env = params.ENVIRONMENT
            if (env == 'production') {
                input(message: 'Approve production deployment?', ok: 'Deploy')
            }
            sh "./deploy.sh ${env}"
        }
    }
}

مكتبات Jenkins المشتركة

لمنطق خط الأنابيب القابل لإعادة الاستخدام، حدّد مكتبة مشتركة:

// vars/npmPipeline.groovy
def call(Map config = [:]) {
    pipeline {
        agent any
        stages {
            stage('Install') {
                steps {
                    sh 'npm ci'
                }
            }
            stage('Test') {
                steps {
                    sh 'npm test'
                }
            }
            stage('Build') {
                steps {
                    sh 'npm run build'
                }
            }
        }
    }
}

استخدمها في Jenkinsfile:

@Library('my-shared-lib') _

npmPipeline(nodeVersion: '20')

الاختبار الآلي في خطوط الأنابيب

اختبارات الوحدة

- name: Run unit tests
  run: npm run test:unit -- --reporter=junit --outputFile=reports/junit.xml

انشر النتائج في GitHub Actions:

- name: Publish test results
  uses: dorny/test-reporter@v1
  if: always()
  with:
    name: Unit Tests
    path: reports/junit.xml
    reporter: java-junit

اختبارات التكامل

شغّل اختبارات التكامل مقابل حاوية خدمة قاعدة بيانات:

jobs:
  integration:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
          POSTGRES_DB: app_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run test:integration
        env:
          DATABASE_URL: postgresql://postgres:test@localhost:5432/app_test

تلميح

حاويات الخدمة في GitHub Actions توفر قواعد بيانات يمكن التخلص منها لاختبارات التكامل. أدرج دائمًا فحوصات الصحة (--health-cmd) حتى لا تبدأ اختباراتك قبل أن تكون قاعدة البيانات جاهزة.

اختبارات من النهاية إلى النهاية

شغّل اختبارات E2E لـ Playwright في CI:

e2e:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 20
    - run: npm ci
    - name: Install Playwright browsers
      run: npx playwright install --with-deps
    - name: Run E2E tests
      run: npx playwright test
    - name: Upload report
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: playwright-report
        path: playwright-report/

فحص الأمان

أضف فحص الاعتماديات والكود:

- name: Run audit
  run: npm audit --audit-level=high

- name: CodeQL analysis
  uses: github/codeql-action/init@v3
  with:
    languages: javascript-typescript

- name: Perform analysis
  uses: github/codeql-action/analyze@v3

- name: Trivy container scan
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: app:latest
    severity: CRITICAL,HIGH

إعداد خط الأنابيب بمساعدة الذكاء الاصطناعي

إنشاء سير العمل من المطالبات

ينشئ ذكاء Cursor الاصطناعي ملفات خط أنابيب كاملة من الأوصاف. افتح Ctrl+K في ملف .yml جديد وأدخل المطالبة:

Create a GitHub Actions workflow that: runs on push to main and on PRs,
sets up Node 20, installs dependencies with npm ci, runs lint, type-check,
and tests with coverage, builds a Docker image, pushes it to GitHub
Container Registry, and deploys to a Kubernetes cluster using kubectl.
Use caching and environment protections.

ينتج Cursor سير عمل كاملًا وصالحًا. راجع الأذونات والأسرار، ثم حسّن بطلب اختبار المصفوفة أو إشعارات Slack.

تلميح

عند إدخال مطالبات لتكوين CI/CD، حدد المنصة والإصدار الدقيقين. "GitHub Actions مع Node 20 وDocker buildx" ينتج مخرجات أفضل بكثير من "خط أنابيب CI لتطبيق Node الخاص بي".

تحسين خطوط الأنابيب الحالية

يمكن لـ Cursor تحليل وتحسين خطوط الأنابيب البطيئة. حدد ملف سير العمل وأدخل المطالبة:

Analyze this GitHub Actions workflow and suggest optimizations to reduce
runtime. Identify: missing cache opportunities, jobs that could run in
parallel, oversized images, and unnecessary steps.

التحسينات الشائعة التي يقترحها الذكاء الاصطناعي:

• إضافة التخزين المؤقت للاعتماديات.
• تقسيم lint والاختبار والبناء إلى مهام متوازية.
• استخدام التخزين المؤقت لطبقات Docker.
• إلغاء التشغيلات القديمة لنفس الفرع.

إنشاء اختبارات خط الأنابيب

استخدم act لتشغيل GitHub Actions محليًا قبل الدفع:

# Install act
brew install act

# Run a specific workflow locally
act -j test -W .github/workflows/ci.yml

أدخل مطالبة في Cursor: "أنشئ مجموعة من أحداث الاختبار والأسرار الوهمية لتشغيل سير العمل هذا محليًا باستخدام act."

إدارة الأسرار

أسرار GitHub Actions

خزّن الأسرار في إعدادات المستودع أو البيئة، وليس في الكود أبدًا:

- name: Deploy
  env:
    API_KEY: ${{ secrets.API_KEY }}
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
  run: ./deploy.sh

warning

يقوم GitHub بتمويه قيم الأسرار في السجلات، لكن التسجيل المنظم يمكن أن يسرّبها إذا ظهر السر كجزء من سلسلة أكبر. تجنب تسجيل أجسام الطلبات الكاملة التي قد تحتوي على رموز، واستخدم سياق secrets فقط في env أو with — وليس في نصوص run حيث قد يتم صدى الصدى.

متغيرات GitLab CI

deploy:
  variables:
    DATABASE_URL: $CI_DATABASE_URL
  script:
    - ./deploy.sh

ضع علامة "مموّهة" و"محمية" على المتغيرات في واجهة GitLab لتظهر فقط في الفروع المحمية.

بيانات اعتماد Jenkins

استخدم Credentials Store بدلاً من متغيرات البيئة:

withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
    sh './deploy.sh'
}

أفضل ممارسات CI/CD في Cursor

حافظ على سرعة خطوط الأنابيب

• تخزين الاعتماديات ومخرجات البناء مؤقتًا.
• تشغيل المهام المستقلة بالتوازي.
• استخدام التخزين المؤقت لطبقات Docker لبناء الصور.
• إلغاء التشغيلات الجارية عند دفع التزام جديد.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

الفشل السريع والمرئي

• تشغيل lint والتحقق من النوع قبل الاختبارات.
• استخدام fail-fast: true في مهام المصفوفة حيث يُبطل فشل واحد الباقي.
• إرسال إشعارات عند الفشل (Slack، البريد الإلكتروني، Teams).

تثبيت إصدارات الإجراءات

# تجنب — latest قد ينكسر بشكل غير متوقع
- uses: actions/checkout@v4

# فضل — التثبيت على SHA التزام لإعادة الإنتاج
- uses: actions/[email protected]

تلميح

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

استخدام Environments للترقية

يوفر GitHub Environments قواعد الحماية والمراجعين المطلوبين وتتبع النشر:

deploy:staging:
  environment: staging

deploy:production:
  needs: deploy:staging
  environment:
    name: production
    url: https://app.example.com

تصحيح أخطاء خطوط الأنابيب

إعادة تشغيل المهام الفاشلة

يتيح لك GitHub Actions إعادة تشغيل المهام الفاشلة فقط، مما يوفر الوقت وموارد الحوسبة:

gh run rerun <run-id> --failed

تمكين تسجيل التصحيح

- name: Debug step
  env:
    ACTIONS_STEP_DEBUG: true
  run: echo "Detailed logs enabled"

اضبط سر المستودع ACTIONS_STEP_DEBUG على true لسجلات تشغيل مفصلة.

التحقق من صحة YAML محليًا

استخدم إضافة YAML في Cursor للتحقق من بناء الجملة أثناء الكتابة. للتحقق الأعمق، استخدم actionlint:

brew install actionlint
actionlint .github/workflows/*.yml

تلميح

يمكن لـ Cursor تشغيل actionlint عند الحفظ باستخدام تكوين المهام. أضف إدخال .vscode/tasks.json يشغل actionlint على الملف الحالي ويعرض الأخطاء في لوحة المشاكل.

الأخطاء الشائعة وكيفية تجنبها

ذاكرات التخزين المؤقت القديمة

ذاكرة التخزين المؤقت التي لا تُبطل أبدًا يمكن أن تخفي تغييرات الاعتماديات. أدرج دائمًا تجزئة ملف القفل في المفتاح:

key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

نمو المهام غير المحدود

بدون تدوير السجلات، تتراكم البنيات القديمة. اضبط الاحتفاظ:

# GitHub: اضبط في إعدادات المستودع
# Jenkins:
options {
    buildDiscarder(logRotator(numToKeepStr: '20'))
}

نسيان if: always() على المصنوعات

لا يتم تحميل مصنوعات المهمة الفاشلة افتراضيًا. أضف if: always() لالتقاط تقارير الاختبار والتغطية حتى عند الفشل.

warning

احذر من if: always() في خطوات النشر — لا تريد النشر بعد فشل الاختبار. استخدم شروطًا محددة مثل if: success() && github.ref == 'refs/heads/main'.

الأسرار في السجلات

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

الخلاصة

Cursor هو محرر قوي لإنشاء وصيانة خطوط أنابيب CI/CD عبر GitHub Actions وGitLab CI وJenkins. توفر إضافة YAML التحقق من صحة المخطط، وتتيح حاويات الخدمة اختبار التكامل، وينشئ المساعد الذكي تكوينات خط الأنابيب ويحسّنها ويصحح أخطاءها من مطالبات اللغة الطبيعية. ابدأ بإنشاء سير عمل CI، وأضف الاختبار الآلي وفحص الأمان، ودع ذكاء Cursor الاصطناعي يتولى التكوين المتكرر بينما تركز على تسليم عمليات نشر موثوقة وسريعة وآمنة.