بوابة الإصدار في CI
استدع بوابة الإصدار في AI CodeOps من GitHub Actions أو GitLab CI أو Bitbucket Pipelines أو Forgejo أو Gitea، وأفشل المهمة عند الرفض، واجعلها فحصا مطلوبا.
تجيب بوابة الإصدار عن سؤال واحد لخط CI لديك: هل يجوز إطلاق طلب السحب هذا؟ يرسل CI لديك عنوان طلب السحب إلى POST /api/release/check بمفتاح API لمساحة العمل. فينظر AI CodeOps إلى كل جلسة مست التغيير ويجيب بـ allowed: true أو allowed: false، مع أسباب مثل اختبارات فاشلة، أو ملاحظة مفتوحة بخطورة high أو critical، أو مراجعة لم تكتمل، أو عملية بناء للمستودع لم تنجح. ويرفض أيضا الجلسة التي غيّرت كودا وليست لها نتيجة اختبار فيها أعداد، ما لم يكن خيار Don't run tests for this project مفعلا في المشروع. وهذه هي القواعد نفسها المطبقة في بوابات الجودة في لوحة التحكم.
يفتح AI CodeOps طلبات السحب الخاصة به من فروع اسمها codeops/run-<id>. وترفض البوابة التغيير الذي لم تمسه أي جلسة AI CodeOps، ولذلك لا تسأل المهام أدناه إلا عن تلك الفروع. وتبقى فحوصك الأخرى تعمل على كل طلب سحب.
أنشئ مفتاح API
- في لوحة التحكم، افتح Configure → API Keys وأنشئ مفتاحا. يبدأ السر بـ
sk-ويعرض مرة واحدة. - خزنه في مخزن الأسرار لنظام CI لديك بالاسم
AICODEOPS_API_KEY. ولا تضعه في المستودع.
| نظام CI | أين يوضع السر |
|---|---|
| GitHub Actions | في Settings → Secrets and variables → Actions الخاصة بالمستودع، بوصفه سرا للمستودع |
| GitLab CI | في Settings → CI/CD → Variables، مع تفعيل الحجب (masked) |
| Bitbucket Pipelines | في Repository settings → Repository variables، مع وضع علامة على Secured |
| Forgejo and Gitea Actions | في Settings → Actions → Secrets الخاصة بالمستودع |
على GitLab، اترك Protect variable موقوفا ما لم تكن فروع codeops/* لديك محمية. فالمتغير المحمي لا يعطى إلا لخطوط التنفيذ على الفروع المحمية، فتحصل المهمة على مفتاح فارغ.
يتصرف المفتاح بصفة العضو الذي أنشأه ويحتاج إلى الصلاحية workspace:read. وحيث تتضمن خطتك تحديد نطاق المفاتيح، يستطيع مسؤول قصر المفتاح على فحص بوابة الإصدار. والمزيد عن المفاتيح في مفاتيح API لمساحة العمل.
تستدعي المهام أدناه العنوان https://console.aicodeops.dev. استخدم العنوان الذي تفتح عليه لوحة التحكم. وتعرض صفحة Release gate في لوحة التحكم، ضمن Review & Gate، مهمتي GitHub Actions و GitLab CI وقد ملئ فيهما عنوانك، مع زر Copy للنسخ.
أضف المهمة
ترسل كل مهمة عنوان طلب السحب، وتطبع الملخص والأسباب، وتفشل ما لم يكن الجواب allowed: true. وتجيب نقطة النهاية بالحالة 200 عند الرفض أيضا، ولذلك تقرأ المهمة الحقل لا رمز الحالة. ويحول curl --fail المفتاح الخاطئ أو تجاوز حد المعدل أو الانقطاع إلى مهمة فاشلة.
GitHub Actions
احفظ ما يلي باسم .github/workflows/aicodeops-release-gate.yml، وهذا محتواه:
name: AI CodeOps release gate
on:
pull_request:
permissions:
contents: read
jobs:
release-gate:
name: AI CodeOps release gate
# AI CodeOps opens its pull requests from codeops/run-<id> branches.
if: startsWith(github.head_ref, 'codeops/run-')
runs-on: ubuntu-latest
steps:
- name: Ask the release gate
env:
AICODEOPS_API_KEY: ${{ secrets.AICODEOPS_API_KEY }}
AICODEOPS_URL: https://console.aicodeops.dev
PR_URL: ${{ github.event.pull_request.html_url }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
run: |
body=$(jq -n --arg pr "$PR_URL" --arg sha "$HEAD_SHA" '{pullRequestURL: $pr, commitSHA: $sha}')
response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
-H "Authorization: Bearer $AICODEOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "$body") || { echo "::error::Release check unavailable: failing closed"; exit 1; }
echo "$response" | jq -r '.summary, ((.reasons // [])[] | "- " + .)'
if [ "$(echo "$response" | jq -r '.allowed')" != "true" ]; then
echo "::error::AI CodeOps release gate denied this change"
exit 1
fi
ترسل المهمة عنوان طلب السحب وإيداعه الرأسي (head commit). وتطابق الجلسة أيا منهما.
GitLab CI
أضف المهمة التالية إلى .gitlab-ci.yml، وهذا نصها:
aicodeops-release-gate:
image: alpine:3.20
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
variables:
AICODEOPS_URL: https://console.aicodeops.dev
before_script:
- apk add --no-cache curl jq
script:
- |
case "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" in
codeops/run-*) ;;
*) echo "Not an AI CodeOps branch: nothing to check."; exit 0 ;;
esac
body=$(jq -n --arg pr "$CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID" '{pullRequestURL: $pr}')
response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
-H "Authorization: Bearer $AICODEOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "$body") || { echo "Release check unavailable: failing closed"; exit 1; }
echo "$response" | jq -r '.summary, ((.reasons // [])[] | "- " + .)'
if [ "$(echo "$response" | jq -r '.allowed')" != "true" ]; then
echo "AI CodeOps release gate denied this change"
exit 1
fi
تعمل المهمة في خطوط التنفيذ الخاصة بطلبات الدمج. وعلى فرع لم يفتحه AI CodeOps تنجح دون أن تسأل، فيبقى خط التنفيذ يعطي نتيجة.
Bitbucket Pipelines
أضف ما يلي إلى bitbucket-pipelines.yml. ويقصر النمط codeops/** الخطوة على طلبات السحب القادمة من فروع AI CodeOps، كما يلي:
pipelines:
pull-requests:
"codeops/**":
- step:
name: AI CodeOps release gate
image: alpine:3.20
script:
- apk add --no-cache curl jq
- |
AICODEOPS_URL="https://console.aicodeops.dev"
body=$(jq -n --arg pr "https://bitbucket.org/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG/pull-requests/$BITBUCKET_PR_ID" '{pullRequestURL: $pr}')
response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
-H "Authorization: Bearer $AICODEOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "$body") || { echo "Release check unavailable: failing closed"; exit 1; }
echo "$response" | jq -r '.summary, ((.reasons // [])[] | "- " + .)'
if [ "$(echo "$response" | jq -r '.allowed')" != "true" ]; then
echo "AI CodeOps release gate denied this change"
exit 1
fi
Forgejo and Gitea Actions
احفظ ما يلي باسم .forgejo/workflows/aicodeops-release-gate.yml على Forgejo، أو باسم .gitea/workflows/aicodeops-release-gate.yml على Gitea. واضبط runs-on على تسمية يحملها أحد المشغلات لديك، كما يلي:
name: AI CodeOps release gate
on:
pull_request:
jobs:
release-gate:
runs-on: docker
steps:
- name: Ask the release gate
env:
AICODEOPS_API_KEY: ${{ secrets.AICODEOPS_API_KEY }}
AICODEOPS_URL: https://console.aicodeops.dev
PR_URL: ${{ github.server_url }}/${{ github.repository }}/pulls/${{ github.event.number }}
BRANCH: ${{ github.head_ref }}
run: |
set -eu
case "$BRANCH" in
codeops/run-*) ;;
*) echo "Not an AI CodeOps branch: nothing to check."; exit 0 ;;
esac
response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
-H "Authorization: Bearer $AICODEOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"pullRequestURL\":\"$PR_URL\"}") || { echo "Release check unavailable: failing closed"; exit 1; }
echo "$response"
printf '%s' "$response" | grep -Eq '"allowed"[[:space:]]*:[[:space:]]*true' || { echo "AI CodeOps release gate denied this change"; exit 1; }
تستخدم هذه المهمة grep بدلا من jq، فلا يحتاج المشغل إلا إلى curl. ويسمح النمط بمسافات حول النقطتين، فيقرأ الجواب بالطريقة نفسها أيا كان تنسيقه. وتطبع الجواب كله، ومعه الأسباب.
إذا فشلت المهمة على تغيير ينبغي أن ينجح
- "No workflow runs found for …": العنوان الذي أرسلته المهمة ليس العنوان الذي خزنه AI CodeOps حين فتح طلب السحب. قارن العنوان في سجل المهمة برابط طلب السحب على التغيير في لوحة التحكم. والشرطة المائلة الأخيرة تهمل.
- تفشل المهمة قبل أن تطبع ملخصا: المفتاح مفقود أو خاطئ، أو أجرت مساحة العمل أكثر من 60 فحصا في دقيقة. تحقق من اسم السر، ومن أن المفتاح لم يحذف.
اجعلها فحصا مطلوبا
المهمة الفاشلة لا توقف الدمج بحد ذاتها. اشترطها على خدمة استضافة Git لديك:
- GitHub. في حماية الفروع أو في ruleset لفرعك الافتراضي، فعّل Require status checks to pass before merging وأضف AI CodeOps release gate. ويظهر الفحص في القائمة بعد أن يعمل مرة واحدة. وعلى طلبات السحب القادمة من فروع أخرى تتخطى المهمة، ويحتسب GitHub المهمة المتخطاة ناجحة.
- GitLab. ضمن Settings → Merge requests → Merge checks، فعّل Pipelines must succeed. واترك Skipped pipelines are considered successful موقوفا.
- Bitbucket. ضمن Repository settings → Branch restrictions، أضف فحص الدمج الخاص بحد أدنى من عمليات البناء الناجحة دون عمليات بناء فاشلة. ومنع الدمج عند وجود فحوص دمج غير محلولة يحتاج إلى خطة Premium. وعلى خطة Standard يحذر الفحص ويبقى بوسع الأشخاص الدمج.
- Forgejo and Gitea. في قاعدة حماية الفرع لفرعك الافتراضي، فعّل Enable status check وأضف المهمة إلى Status check patterns. وشغّل المهمة مرة واحدة أولا ليظهر اسمها.
ثم قيد من يستطيع الدفع إلى فروع codeops/*، أو اجعل الموافقات تعاد إلى البداية حين يتغير الفرع. فالبوابة تجيب عن تغيير الجلسة، لا عن إيداع يضيفه أحد إلى الفرع بعد ذلك.
خيارات يحسن أن تعرفها
أضف حقولا إلى جسم JSON لتطلب أكثر. وفي المهام أعلاه يكون ذلك في سطر jq -n، هكذا:
body=$(jq -n --arg pr "$PR_URL" '{pullRequestURL: $pr, blockingSeverity: "medium", minCoveragePct: 80}')
| الخيار | الافتراضي | ما يفعله |
|---|---|---|
blockingSeverity | high | أدنى درجة خطورة لملاحظة مفتوحة تسبب الرفض: critical أو high أو medium أو low أو info |
minCoveragePct | غير مضبوط | حد أدنى للتغطية من 0 إلى 100. ويجب أن يستوفيه أحدث تشغيل اختبار ذكر التغطية |
blockOnInFlight | false | الرفض ما دامت جلسة أو عملية بناء للمستودع خاصة بالتغيير لا تزال تعمل |
blockOnBuildFailure | true | عملية بناء للمستودع خاصة بالإيداع أو بطلب السحب فشلت أو انتهت مهلتها أو ألغيت تسبب الرفض. اضبطه على false لاستبعاد عمليات البناء |
الحد الأدنى للتغطية يغلق عند الخطأ. إذا ضبطت minCoveragePct ولم يذكر أي تشغيل اختبار على التغيير التغطية، ترفض البوابة برسالة: "Coverage wasn't reported, so the 80% floor can't be checked". فالحد الذي لا يمكن فحصه لا ينجح. اضبطه بعد أن يصير أمر الاختبار في مشروعك يطبع ملخص تغطية، مثل pytest --cov أو vitest run --coverage، وتعرض صفحة تشغيل الجلسة رقم تغطية.
انتظار جلسة جارية. من دون blockOnInFlight، قد ينجح تغيير له جلسة منتهية واحدة بينما جلسة أخرى لا تزال تعمل. ومعه ترفض البوابة إلى أن تنتهي كل جلسة وكل عملية بناء خاصة بالتغيير. والمهمة التي ينبغي أن تنتظر تستطيع تكرار الاستدعاء مع توقف قصير ما دام أحد الأسباب يذكر أن شيئا لا يزال يعمل، ثم تكف بعد حدها الزمني الخاص. وابق دون 60 فحصا في الدقيقة لمساحة العمل.
مسارات سير العمل المطلوبة، والتراخيص المحظورة، وعملية النشر السابقة المطلوبة، وبقية الحقول موجودة في صفحة API، وكل حقول الرد في مرجع فحص الإصدار.
الخطوات التالية
الأسئلة الشائعة
لماذا لا تسأل المهام إلا عن فروع codeops/؟
تحكم البوابة على جلسات AI CodeOps وترفض التغيير الذي لا جلسة له. وطلب السحب الذي فتحه شخص يدويا لا جلسة خلفه، فالسؤال عنه سيفشل دائما.
هل يعود التغيير المرفوض بحالة خطأ؟
لا. تجيب نقطة النهاية بالحالة 200 عند السماح وعند الرفض. وتقرأ المهمة الحقل allowed وتفشل ما لم تكن قيمته true.
ماذا يحدث إذا تعذر الوصول إلى البوابة؟
تفشل المهمة. كل مهمة في هذه الصفحة تعامل خطأ الشبكة أو المفتاح الخاطئ أو تجاوز حد المعدل على أنه فشل، فالفحص الذي لم يعمل لا يجيز تغييرا أبدا.