# بوابة الإصدار في CI

> استدع بوابة الإصدار في AI CodeOps من GitHub Actions أو GitLab CI أو Bitbucket Pipelines أو Forgejo أو Gitea، وأفشل المهمة عند الرفض، واجعلها فحصا مطلوبا.

المصدر: https://aicodeops.dev/ar/docs/release-gate-ci

تجيب بوابة الإصدار عن سؤال واحد لخط CI لديك: هل يجوز إطلاق طلب السحب هذا؟ يرسل CI لديك عنوان طلب السحب إلى `POST /api/release/check` بمفتاح API لمساحة العمل. فينظر AI CodeOps إلى كل جلسة مست التغيير ويجيب بـ `allowed: true` أو `allowed: false`، مع أسباب مثل اختبارات فاشلة، أو ملاحظة مفتوحة بخطورة high أو critical، أو مراجعة لم تكتمل، أو عملية بناء للمستودع لم تنجح. ويرفض أيضا الجلسة التي غيّرت كودا وليست لها نتيجة اختبار فيها أعداد، ما لم يكن خيار **Don't run tests for this project** مفعلا في المشروع. وهذه هي القواعد نفسها المطبقة في [بوابات الجودة](https://aicodeops.dev/ar/docs/quality-gates) في لوحة التحكم.

يفتح AI CodeOps طلبات السحب الخاصة به من فروع اسمها `codeops/run-<id>`. وترفض البوابة التغيير الذي لم تمسه أي جلسة AI CodeOps، ولذلك لا تسأل المهام أدناه إلا عن تلك الفروع. وتبقى فحوصك الأخرى تعمل على كل طلب سحب.

## أنشئ مفتاح API

1. في لوحة التحكم، افتح **Configure → API Keys** وأنشئ مفتاحا. يبدأ السر بـ `sk-` ويعرض مرة واحدة.
2. خزنه في مخزن الأسرار لنظام 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://aicodeops.dev/ar/docs/api#workspace-api-keys).

تستدعي المهام أدناه العنوان `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`، وهذا محتواه:

```yaml
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`، وهذا نصها:

```yaml
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، كما يلي:

```yaml
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` على تسمية يحملها أحد المشغلات لديك، كما يلي:

```yaml
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`، هكذا:

```bash
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](https://aicodeops.dev/ar/docs/api)، وكل حقول الرد في [مرجع فحص الإصدار](https://aicodeops.dev/docs/api/release-check).

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

- [بوابات الجودة](https://aicodeops.dev/ar/docs/quality-gates)
- [API](https://aicodeops.dev/ar/docs/api)
- [الموافقات والسياسات](https://aicodeops.dev/ar/docs/approvals-and-policies)
- [النشر عبر البوابات](https://aicodeops.dev/ar/docs/gated-deploys)

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

### لماذا لا تسأل المهام إلا عن فروع codeops/؟

تحكم البوابة على جلسات AI CodeOps وترفض التغيير الذي لا جلسة له. وطلب السحب الذي فتحه شخص يدويا لا جلسة خلفه، فالسؤال عنه سيفشل دائما.

### هل يعود التغيير المرفوض بحالة خطأ؟

لا. تجيب نقطة النهاية بالحالة 200 عند السماح وعند الرفض. وتقرأ المهمة الحقل allowed وتفشل ما لم تكن قيمته true.

### ماذا يحدث إذا تعذر الوصول إلى البوابة؟

تفشل المهمة. كل مهمة في هذه الصفحة تعامل خطأ الشبكة أو المفتاح الخاطئ أو تجاوز حد المعدل على أنه فشل، فالفحص الذي لم يعمل لا يجيز تغييرا أبدا.
