AI CodeOps

واجهة API

ما تستطيع استدعاءه برمجيا اليوم: فحص بوابة الإصدار لخطوط CI بمفتاح API لمساحة العمل، والمفاتيح العامة لحزم الأدلة. والواجهة محدودة في مرحلة بيتا.

يستخدم AI CodeOps في المتصفح. وخلال مرحلة بيتا المفتوحة، واجهة API البرمجية صغيرة عن قصد: نقطة نهاية واحدة لخطوط CI، مع المفاتيح العامة التي تتيح لأي شخص فحص حزمة أدلة. وكل ما عدا ذلك في لوحة التحكم يحتاج إلى جلسة متصفح مسجل الدخول فيها وليس واجهة API مدعومة.

مفاتيح API لمساحة العمل

أنشئ مفتاحا من Configure → API Keys. أعطه اسما؛ ويعرض السر (يبدأ بـ sk-) مرة واحدة، فانسخه عندها. ولا يخزن AI CodeOps إلا تجزئة له.

  • يتصرف المفتاح بصفة العضو الذي أنشأه، بدور ذلك العضو الحالي. وإذا أزيل العضو أو فقد دوره صلاحية، يفقدها المفتاح أيضا.
  • يستطيع المالكون والمسؤولون والمطورون والأعضاء إنشاء المفاتيح. ولا يستطيع ذلك المشاهدون.
  • يرى المسؤولون كل مفتاح في مساحة العمل؛ ويرى الآخرون مفاتيحهم.
  • الزر Delete يلغي المفتاح فورا. وتتوقف التكاملات التي تستخدمه عن العمل حالا.

حيث تتضمن خطتك تحديد نطاق المفاتيح، يستطيع مسؤول اختيار Scope لقصر المفتاح على قائمة سماح لعناوين IP (نطاقات CIDR)، وحد للمعدل في الدقيقة، وتاريخ انتهاء، وما يجوز استخدامه فيه: استدعاءات بوابة النماذج، أو فحص بوابة الإصدار، أو كليهما (وهو الافتراضي).

أرسل المفتاح في صورة Bearer token، هكذا:

Authorization: Bearer sk-...

فحص بوابة الإصدار

تجيب نقطة النهاية POST /api/release/check عن سؤال واحد لخط CI لديك: هل يجوز إطلاق طلب السحب هذا أو هذا الإيداع؟ وتطبق الفحوص نفسها المطبقة في بوابات الجودة عبر كل جلسة مست التغيير. ويحتاج المفتاح إلى الصلاحية workspace:read.

curl -sf -X POST "https://console.aicodeops.dev/api/release/check" \
  -H "Authorization: Bearer $WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pullRequestURL":"https://github.com/acme/api/pull/42"}'

استخدم العنوان نفسه الذي تفتح عليه لوحة التحكم. وفي بوابة الإصدار في CI مهام جاهزة للنسخ لكل من GitHub Actions و GitLab CI و Bitbucket Pipelines و Forgejo and Gitea Actions.

حقول الطلب

الحقلالنوعالافتراضي
pullRequestURLعنوان URLأحد هذين الحقلين مطلوب
commitSHAسلسلة نصية، 7 أحرف أو أكثر
blockingSeveritycritical, high, medium, low, infohigh
blockOnTestFailureقيمة منطقية: الاختبارات الفاشلة تمنع، وكذلك تغيير الكود الذي لا نتيجة اختبار لهtrue
blockOnBuildFailureقيمة منطقية: عملية بناء للمستودع لم تنجح تمنعtrue
minCoveragePctرقم من 0 إلى 100: حد أدنى للتغطية؛ ويرفض إذا لم تذكر أي تغطيةبلا شرط
requiredWorkflowsمصفوفة سلاسل نصيةلا شيء
disallowedLicensesمصفوفة سلاسل نصية، تفحص على قائمة SBOM الخاصة بالمشروعلا شيء
requireDeployedToاسم بيئة، مثل stagingلا شيء
blockOnInFlightقيمة منطقية: الرفض ما دام تشغيل لا يزال جارياfalse
lookbackMsالمدى الزمني الذي ينظر فيه إلى الخلف، بالمللي ثانية14 يوما
workspaceIDمعرف مساحة العمل: فقط حين تستدعي بجلسة لوحة التحكممساحة عمل مفتاح API

تقبل نقطة النهاية GET /api/release/check الأسماء نفسها بوصفها معاملات استعلام (والقوائم مفصولة بفواصل).

دليل الاختبار. مع تفعيل blockOnTestFailure، وهو الافتراضي، تحتاج كل جلسة غيّرت كودا في مشروع إلى نتيجة اختبار فيها أعداد. وإذا لم يعمل لها أي اختبار، أو عمل أمر الاختبار دون أن يذكر أعداد اختبارات، يرفض الفحص برسالة: "The test command ran but reported no test counts, so nothing shows a test passed. Check the project's test command". فغياب الدليل ليس نجاحا. وللمشروع الذي لا مجموعة اختبارات له، فعّل Don't run tests for this project في إعدادات المشروع من Plan → Projects؛ وعندها لا يطلب الفحص نتيجة اختبار. ولا تسري القاعدة أيضا على جلسة لم تغير كودا، ولا حين ترسل "blockOnTestFailure": false.

الحد الأدنى للتغطية. مع ضبط minCoveragePct، يجب أن يستوفيه أحدث تشغيل اختبار ذكر التغطية. وإذا لم يذكر أي تشغيل اختبار على التغيير التغطية، يرفض الفحص برسالة: "Coverage wasn't reported, so the 80% floor can't be checked". فالحد الذي لا يمكن فحصه لا ينجح. اجعل أمر الاختبار في المشروع يطبع ملخص تغطية قبل أن تضبط حدا. واترك minCoveragePct خارج الطلب فلا تكون التغطية شرطا.

الاستدعاء بجلسة لوحة التحكم. مفتاح API يحمل مساحة عمله، فلا يرسل CI الحقل workspaceID. وتستطيع جلسة لوحة تحكم مسجل الدخول فيها استدعاء نقطة النهاية أيضا، ويجب أن تسمي مساحة العمل: أضف ?workspaceID=<id> إلى العنوان، أو ضع workspaceID في جسم JSON لطلب POST. ومن دونه يكون الجواب 400. والمعرف هو الجزء الذي بعد /workspace/ في عنوان لوحة التحكم.

الرد

تعيد نقطة النهاية 200 في النتيجتين كلتيهما. فاقرأ الحقل allowed، وهذه حقول الرد:

  • الحقل allowed: القيمة true أو false
  • الحقلان summary و reasons: شروح بإنجليزية بسيطة
  • الحقول blockingFindings و testFailures و testEvidenceMissing و coverageShortfall و coverageNotReported و licenseViolations و licenseEvidenceMissing: التفاصيل التي خلف الرفض (ويسرد licenseEvidenceMissing المشاريع التي لا قائمة SBOM لها تفحص حين ترسل disallowedLicenses)
  • الحقل testEvidenceMissing: عنصر { "workflowRunID", "reason" } لكل جلسة غيّرت كودا وليست لها نتيجة اختبار فيها أعداد؛ وقائمة فارغة حين لا ينقص شيء
  • الحقل coverageNotReported: القيمة { "required": 80 } حين تضبط حدا ولا يذكر أي تشغيل اختبار التغطية؛ والقيمة null حين يوجد رقم تغطية أو لا يكون حد مضبوطا
  • الحقل runsConsidered: الجلسات التي بني عليها الحكم

التغيير الذي لا جلسات مطابقة له يرفض ("No workflow runs found for …"). وكذلك تغيير الكود الذي لا نتيجة اختبار له، كما سبق في فقرة دليل الاختبار. وإذا فشل التقييم، تحصل على allowed: false مع الملخص "Evaluation failed"، فالفحص المعطل لا يجيز تغييرا أبدا.

الأخطاء

الحالةالمعنى
400صيغة JSON غير صالحة أو حقول غير صالحة. ومع جلسة لوحة التحكم: الحقل workspaceID مفقود، وتذكر الرسالة ذلك
401لا مفتاح API ولا جلسة لوحة تحكم، أو المفتاح غير صالح
403نطاق المفتاح أو دور منشئه لا يسمح بذلك، أو المفتاح يخص مساحة عمل أخرى. ومع جلسة: لست عضوا في مساحة العمل
429أكثر من 60 فحصا في الدقيقة لمساحة العمل؛ انظر الترويسة Retry-After

والفحص نفسه موجود في لوحة التحكم في Review & Gate → Release gate، مع مهمة CI جاهزة للنسخ.

مفاتيح حزم الأدلة

نقطة النهاية GET /api/evidence?action=keys عامة ولا تحتاج إلى مفتاح. وتعيد مفاتيح Ed25519 العامة التي توقّع حزم الأدلة، فتستطيع التحقق من حزمة دون اتصال بالشبكة. وتنزيل حزمة يحتاج إلى عضو مسجل الدخول له صلاحية التدقيق؛ وهو غير متاح بمفتاح API.

مرجع API

صفحة لكل نقطة نهاية، مولدة من مواصفة OpenAPI:

الخطوات التالية

الأسئلة الشائعة

هل توجد واجهة REST API كاملة للجلسات والمشاريع؟

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

هل تنتهي صلاحية مفاتيح API؟

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

هل كانت هذه الصفحة مفيدة؟