إنتقل إلى المحتوى الرئيسي

استخدام Bugbot لمراجعة الكود المؤتمتة في Cursor

Bugbot

Bugbot هو وكيل مراجعة الكود المؤتمتة المدمج في Cursor والذي يتكامل مباشرة مع مستودعات GitHub الخاصة بك. عند فتح طلب سحب، يقوم Bugbot بتحليل الفروقات، وتحديد الأخطاء المحتملة، واقتراح التحسينات، وترك تعليقات داخلية على طلب السحب الخاص بك. يغطي هذا الدليل كل شيء من الإعداد الأولي إلى التكوين المتقدم، بما في ذلك مشكلات توجيه PR وتكامل GitHub Teams التي يواجهها مستخدمو المنتدى بشكل متكرر.

ما الذي يفعله Bugbot​

يقوم Bugbot بتنفيذ عدة طبقات من التحليل على كل طلب سحب:

  • اكتشاف الأخطاء - يحدد أخطاء المنطق، ومخاطر المرجع الفارغ، والحالات الحدية
  • فحص الأمان - يضع علامات على الثغرات المحتملة مثل حقن SQL أو الأسرار المشفرة بشكل ثابت
  • الأسلوب والاتساق - يتحقق من الانحرافات عن أنماط قاعدة الكود الخاصة بك
  • تلميحات الأداء - يبرز الأنماط غير الفعالة مثل استعلامات N+1
  • تغطية الاختبار - يلاحظ عندما تفتقر التغييرات إلى الاختبارات المقابلة
تلميح

يعمل Bugbot بالكامل في السحابة. لا تحتاج إلى إبقاء Cursor مفتوحاً لتتم المراجعات. بمجرد التفعيل على مستودع، يقوم Bugbot بمراجعة كل PR تلقائياً، سواء كنت على مكتبك أم لا.

المتطلبات الأساسية​

قبل إعداد Bugbot، تأكد من أن لديك:

  1. خطة Cursor Pro أو Business - Bugbot غير متاح في الفئة المجانية
  2. مستودع GitHub مع تمكين عمليات سحب الطلبات
  3. وصول المسؤول أو المشرف إلى المستودع (مطلوب لتثبيت التطبيق)
  4. GitHub Teams مكونة إذا كنت تريد توجيه PR قائم على الفريق

تفعيل Bugbot على مستودع​

المشكلة الأكثر شيوعاً التي يبلغ عنها مستخدمو المنتدى هي Bugbot يقول "disabled for this repository". يعود هذا دائماً تقريباً إلى تخطي خطوة تثبيت GitHub App أو إكمالها جزئياً.

الخطوة 1: تثبيت Cursor GitHub App​

يعمل Bugbot من خلال GitHub App. إذا لم تقم بتثبيته:

  1. افتح Cursor وانتقل إلى Settings > Features > Bugbot
  2. انقر على Connect GitHub Account
  3. ستتم إعادة توجيهك إلى GitHub لتفويض تطبيق Cursor
  4. اختر النطاق:
    • All repositories - يمكن لـ Cursor مراجعة أي مستودع في حسابك
    • Selected repositories - اختر مستودعات محددة للمراجعة
warning

إذا اخترت مستودعات محددة أثناء التثبيت وأنشأت لاحقاً مستودعاً جديداً، لن يعمل Bugbot على المستودع الجديد حتى تضيفه صراحة. هذا هو السبب الأول لخطأ "disabled for this repository". لإصلاح ذلك، اذهب إلى GitHub > Settings > Integrations > Applications > Cursor > Configure، وأضف المستودع الجديد.

الخطوة 2: تفعيل Bugbot في إعدادات Cursor​

بعد تثبيت تطبيق GitHub:

  1. افتح Cursor Settings (Cmd/Ctrl + ,)
  2. انتقل إلى Features > Bugbot
  3. بدّل Enable Bugbot إلى ON
  4. اختر المستودعات التي تريد تفعيل Bugbot عليها

الخطوة 3: التحقق من الاتصال​

أنشئ طلب سحب اختباري وتحقق مما إذا كان Bugbot يستجيب:

# Create a test branch
git checkout -b test-bugbot-connection

# Make a small change
echo "// Bugbot test" >> README.md
git add README.md
git commit -m "test: verify bugbot connection"
git push origin test-bugbot-connection

افتح PR على GitHub. خلال 30-60 ثانية، يجب أن ينشر Bugbot تعليقاً. إذا لم يفعل، انتقل إلى قسم استكشاف الأخطاء أدناه.

توجيه PR وتعيين المراجعين​

يمكن لـ Bugbot توجيه طلبات السحب إلى مراجعين محددين بناءً على مسارات الملفات أو ملكية الكود أو عضوية الفريق. يبلغ مستخدمو المنتدى أن توجيه PR لا يعمل دائماً كما هو متوقع، خاصة مع GitHub Teams.

فهم توجيه PR​

يحدد توجيه PR من يتلقى طلب المراجعة عندما يحلل Bugbot PR. يتبع منطق التوجيه هذه الأولوية:

  1. ملف CODEOWNERS - إذا كان موجوداً، يصبح مالكو الملفات المتغيرة مراجعين
  2. تعيين GitHub Teams - توجيه قائم على الفريق عبر تكوين Bugbot
  3. التراجع - يتلقى جميع المشرفين طلب المراجعة

تكوين CODEOWNERS​

أنشئ ملف CODEOWNERS في جذر مستودعك (أو .github/CODEOWNERS):

# Default owners
*                           @team-leads

# Frontend files
src/components/             @frontend-team
src/pages/                  @frontend-team
src/styles/                 @frontend-team

# Backend files
src/api/                    @backend-team
src/models/                 @backend-team
src/middleware/             @backend-team

# Infrastructure
terraform/                  @devops-team
docker/                     @devops-team
.github/workflows/           @devops-team

# Security-sensitive files
src/auth/                   @security-team @team-leads
.env*                       @security-team

تكامل GitHub Teams​

للتوجيه القائم على الفريق، يقرأ Bugbot عضوية GitHub Teams الخاصة بك. للتكوين:

  1. تأكد من أن مؤسسة GitHub لديها فرق مُعدة تحت Org Settings > Teams
  2. أضف أعضاء إلى كل فريق
  3. أشر إلى أسماء الفرق (مع بادئة @) في CODEOWNERS
  4. في Cursor، اذهب إلى Settings > Features > Bugbot > Advanced
  5. فعّل Use GitHub Teams for routing
تلميح

يجب أن تتطابق أسماء فرق GitHub في CODEOWNERS تماماً. من الأخطاء الشائعة استخدام أسماء العرض بدلاً من slug الفريق. على سبيل المثال، إذا كان اسم فريقك "Frontend Engineers" مع slug frontend-engineers، يجب أن يكون إدخال CODEOWNERS @frontend-engineers، وليس @Frontend Engineers.

مشكلات توجيه PR الشائعة​

مشكلة: تم توجيه PR إلى فريق خاطئ​

العرَض: يتم توجيه PR يغير ملفات الواجهة الخلفية إلى فريق الواجهة الأمامية.

السبب: تداخل أنماط CODEOWNERS. النمط المطابق الأول يفوز، وتُقيّم الأنماط من الأعلى إلى الأسفل.

الحل: أعد ترتيب ملف CODEOWNERS بحيث تأتي الأنماط الأكثر تحديداً قبل العامة:

# Specific first
src/auth/                   @security-team @team-leads
src/api/                    @backend-team

# Then general
src/                        @all-developers
*                           @team-leads

مشكلة: الفريق لا يتلقى طلبات المراجعة​

العرَض: يراجع Bugbot الـ PR ولكن لا تتم إضافة أي أعضاء من فريق GitHub كمراجعين.

السبب: فريق GitHub مضبوط على "secret" (غير مرئي) أو ليس لديه أعضاء.

الحل: اذهب إلى GitHub > Organization > Teams > [اسم الفريق] > Settings. تأكد من أن رؤية الفريق ليست مضبوطة على "Secret" إذا كنت تريد أن يتلقى طلبات المراجعة. تحقق من أن الفريق لديه أعضاء نشطون.

تكوين Bugbot​

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

صرامة المراجعة​

تحكم في مدى صرامة Bugbot مع نتائجه:

{
  "bugbot.severity": "balanced",
  "bugbot.maxComments": 20,
  "bugbot.autoResolve": false
}
الصرامةالسلوك
strictيبلغ عن جميع النتائج، بما في ذلك مشكلات الأسلوب البسيطة
balancedيبلغ عن الأخطاء ومشكلات الأمان ومشكلات الأسلوب الكبيرة (الافتراضي)
lenientيبلغ فقط عن الأخطاء والثغرات الأمنية

استبعادات الملفات​

منع Bugbot من مراجعة الملفات المُنشأة أو المُورّدة:

{
  "bugbot.excludePaths": [
    "**/*.min.js",
    "**/*.min.css",
    "node_modules/**",
    "dist/**",
    "build/**",
    "*.lock",
    "package-lock.json",
    "yarn.lock"
  ]
}

تكوين وكيل الأمان​

يتضمن Bugbot وكيل أمان مخصص يفحص الثغرات. قم بتكوينه بشكل مستقل:

{
  "bugbot.securityAgent": {
    "enabled": true,
    "sensitivityLevel": "high",
    "scanForSecrets": true,
    "scanForDependencies": true,
    "ignorePatterns": [
      "test/**",
      "__mocks__/**"
    ]
  }
}
warning

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

عمليات الاعتماد​

يتكامل Bugbot مع نظام اعتماد مراجعة GitHub. يمكنك تكوين ما إذا كانت نتائج Bugbot تمنع دمج PR.

تعيين المراجعات المطلوبة​

في إعدادات مستودع GitHub الخاص بك:

  1. اذهب إلى Settings > Branches > Branch protection rules
  2. حرر قاعدة الفرع الرئيسي الخاص بك
  3. تحت Require pull request reviews before merging:
    • عيّن عدد المراجعات المعتمدة المطلوبة (مثلاً 2)
    • فعّل Dismiss stale pull request approvals عند دفع التزامات جديدة
    • فعّل Require review from Code Owners

Bugbot كمراجع مطلوب​

يمكنك تكوين Bugbot ليعمل كمراجع مطلوب. عند التفعيل، لا يمكن دمج PRs حتى يكمل Bugbot مراجعته ويعتمدها أو يتم رفض المراجعة.

في Cursor:

  1. Settings > Features > Bugbot > Workflow
  2. فعّل Block merge on critical findings
  3. عيّن عتبة الصرامة للمنع (الافتراضي: critical و high)
تلميح

استخدم ميزة المنع بحكمة. إذا عينت العتبة منخفضة جداً (المنع عند نتائج صرامة منخفضة)، قد يحبط المطورون عندما تمنع مشكلات الأسلوب الدمج. ابدأ بـ "critical و high" وعدّل بناءً على تجربة فريقك.

التعامل مع خلافات Bugbot​

أحياناً يضع Bugbot علامة على شيء يعتقد المطور أنه إيجابية كاذبة. سير العمل الموصى به:

  1. انقر على Resolve conversation على تعليق Bugbot في GitHub
  2. أضف تعليقاً يشرح لماذا هي إيجابية كاذبة
  3. إذا كانت إيجابية كاذبة متكررة على نفس النمط، أضف تعليق // bugbot-ignore:
# bugbot-ignore: This is intentionally using eval for a DSL interpreter
result = eval(user_expression)

استكشاف أخطاء "Disabled for This Repository"​

هذه هي مشكلة Bugbot الأكثر إبلاغاً. اتبع هذا المخطط التشخيصي.

خطوة تشخيصية 1: التحقق من تثبيت GitHub App​

# Check if the Cursor app has access to your repo
gh api repos/{owner}/{repo}/installation --jq '.id'

إذا أعاد 404، فإن GitHub App غير مثبت لهذا المستودع.

الحل: اذهب إلى GitHub > Settings > Integrations > Applications > Cursor > Configure، وأضف المستودع.

خطوة تشخيصية 2: التحقق من إعدادات المستودع في Cursor​

  1. افتح إعدادات Cursor
  2. انتقل إلى Features > Bugbot
  3. ابحث عن مستودعك في القائمة المُفعّلة
  4. إذا لم يكن هناك، انقر على Add Repository وحدده

خطوة تشخيصية 3: التحقق من قواعد حماية الفرع​

يتطلب Bugbot أن يسمح مستودعك لتطبيق GitHub بنشر تعليقات المراجعة. إذا كانت قواعد حماية الفرع الخاصة بك مقيدة جداً:

  1. اذهب إلى GitHub > Settings > Branches
  2. حرر قاعدة حماية الفرع الخاصة بك
  3. تأكد من أن Allow specified actors to bypass requirements يتضمن تطبيق Cursor
  4. تأكد من أن التطبيق غير محظور بواسطة Restrict who can push to matching branches

خطوة تشخيصية 4: التحقق من التطبيقات المتعارضة​

إذا كانت لديك أدوات مراجعة مؤتمتة أخرى مثبتة (CodeRabbit، GitHub Copilot، SonarQube)، فقد تتعارض مع Bugbot.

الحل: عطّل بوتات المراجعة الأخرى مؤقتاً وتحقق مما إذا كان Bugbot يبدأ بالعمل. إذا كان كذلك، ستحتاج إلى تكوين الأدوات للتعايش، مما قد يتطلب تعديل إعدادات webhook أو محفزات المراجعة.

خطوة تشخيصية 5: التحقق من حالة Bugbot​

# Check Cursor service status
curl -s https://status.cursor.sh/api/v2/incidents.json | jq '.incidents[] | select(.status != "resolved")'

إذا كان هناك حادث نشط، انتظر حله وأعد المحاولة.

warning

يظهر Bugbot أحياناً كـ "disabled" فوراً بعد تحديث Cursor. هذه مشكلة معروفة حيث يحتاج رمز GitHub إلى إعادة المصادقة. اذهب إلى Settings > Features > Bugbot، انقر على Disconnect، ثم Reconnect حساب GitHub الخاص بك. هذا ينعش الرمز دون فقدان التكوين الخاص بك.

تحليل معمق لتكامل Bugbot و GitHub Teams​

مزامنة عضوية الفريق​

يقوم Bugbot بتخزين عضوية فريق GitHub مؤقتاً للأداء. إذا أضفت أو أزلت عضواً في الفريق، قد لا ينعكس التغيير فوراً.

لفرض المزامنة:

  1. افتح إعدادات Cursor
  2. اذهب إلى Features > Bugbot > Advanced
  3. انقر على Sync GitHub Teams
  4. انتظر إكمال المزامنة (عادة أقل من 30 ثانية)

عضوية فرق متعددة​

عندما ينتمي مطور إلى فرق متعددة، يقوم Bugbot بالتوجيه بناءً على مطابقة CODEOWNERS. إذا كان ملف مملوكاً لفرق متعددة والمطوّر في كلاهما، يتلقى طلب مراجعة واحد، وليس مكررات.

سياسات المراجعة القائمة على الفريق​

يمكنك تكوين متطلبات مراجعة مختلفة لكل فريق:

{
  "bugbot.teamPolicies": {
    "security-team": {
      "requiredReviews": 2,
      "blockOnHighSeverity": true,
      "additionalScanners": ["dependency-check"]
    },
    "frontend-team": {
      "requiredReviews": 1,
      "blockOnHighSeverity": false
    }
  }
}

أداء وحدود Bugbot​

سرعة المراجعة​

يكمل Bugbot عادةً المراجعة خلال 30-90 ثانية من فتح أو تحديث PR. عوامل تؤثر على السرعة:

العاملالتأثير
حجم PR (الأسطر المتغيرة)الفروقات الكبيرة تستغرق وقتاً أطول للتحليل
عدد الملفاتكل ملف يتطلب تحليلاً فردياً
حجم المستودعقواعد الكود الأكبر تتطلب جمع سياق أكثر
الحمل الحاليأوقات الذروة قد ترى استجابات أبطأ

حد التعليقات​

بشكل افتراضي، ينشر Bugbot بحد أقصى 20 تعليقاً لكل مراجعة. هذا يمنع إغراق صاحب PR. يمكنك تعديل ذلك:

{
  "bugbot.maxComments": 50
}
تلميح

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

حدود المعدل​

يحترم Bugbot حدود معدل GitHub API. إذا كانت مؤسستك تفتح العديد من PRs في وقت واحد، قد تصطف المراجعات في الانتظار. يعالج Bugbot بالترتيب، وتكتمل جميع المراجعات في النهاية.

أفضل الممارسات لتبني Bugbot​

ابدأ في وضع القراءة فقط​

عند تفعيل Bugbot لأول مرة على مستودع موجود، ابدأ في وضع القراءة فقط (بدون منع الدمج). هذا يتيح للفريق رؤية ما يجده Bugbot دون تعطيل سير العمل. بعد أسبوع أو أسبوعين من مراجعة النتائج، عدّل التكوين وفعّل منع الدمج إذا كان ذلك مناسباً.

استخدم نتائج Bugbot كأدوات تعلم​

نتائج Bugbot ليست فقط حول إصلاح PR الحالي. إنها فرص تعلم:

  1. تتبع أنواع النتائج المتكررة (مثلاً: "خطر المرجع الفارغ" يظهر في 30% من PRs)
  2. أنشئ إدخالات .cursor/rules لمنع النمط في الكود المستقبلي
  3. شارك النتائج المثيرة في قنوات الفريق

مراجعة التكوين المنتظمة​

راجع تكوين Bugbot شهرياً:

  • هل استبعادات الملفات لا تزال مناسبة؟
  • هل عتبات الصرامة مضبوطة بشكل صحيح؟
  • هل هناك أنماط إيجابية كاذبة جديدة لقمعها؟
  • هل حد التعليقات مناسب لأحجام PR الحالية؟

الخلاصة​

يجلب Bugbot مراجعة كود مؤتمتة وذكية إلى كل طلب سحب في مستودعات GitHub المتصلة بـ Cursor. المشكلة الأكثر شيوعاً، "disabled for this repository"، يتم حلها دائماً تقريباً بالتحقق من نطاق تثبيت GitHub App وضمان إضافة المستودع صراحةً. من خلال تكوين توجيه PR مع CODEOWNERS، وضبط وكيل الأمان، وتبني نهج تزايدي لمنع الدمج، يمكن لفريقك الاستفادة من Bugbot كخط دفاع أول موثوق ضد الأخطاء والثغرات الأمنية.