AI CodeOps

Barrière de livraison dans la CI

Appelez la barrière de livraison d'AI CodeOps depuis GitHub Actions, GitLab CI, Bitbucket Pipelines, Forgejo ou Gitea, faites échouer le job en cas de refus et faites-en une vérification requise.

La barrière de livraison répond à une question pour votre pipeline : cette pull request peut-elle être livrée ? Votre CI envoie l'URL de la pull request à POST /api/release/check avec une clé API de l'espace de travail. AI CodeOps examine chaque session qui a touché au changement et répond allowed: true ou allowed: false, avec des motifs tels que des tests en échec, un constat high ou critical ouvert, une revue qui ne s'est pas terminée ou un build du dépôt qui n'a pas réussi. Elle refuse aussi une session qui a modifié du code et n'a pas de résultat de test avec des décomptes, sauf si Don't run tests for this project est activé pour le projet. Ce sont les mêmes règles que celles des barrières qualité dans la console.

AI CodeOps ouvre ses pull requests depuis des branches nommées codeops/run-<id>. La barrière refuse un changement auquel aucune session AI CodeOps n'a touché : les jobs ci-dessous n'interrogent donc que ces branches. Vos autres vérifications s'exécutent toujours sur chaque pull request.

Créer une clé API

  1. Dans la console, ouvrez Configure → API Keys et créez une clé. Le secret commence par sk- et n'est affiché qu'une fois.
  2. Stockez-le dans le coffre de secrets de votre système de CI sous le nom AICODEOPS_API_KEY. Ne le placez pas dans le dépôt.
Système de CIOù placer le secret
GitHub ActionsSettings → Secrets and variables → Actions du dépôt, comme secret de dépôt
GitLab CISettings → CI/CD → Variables, masquée
Bitbucket PipelinesRepository settings → Repository variables, avec Secured coché
Forgejo et Gitea ActionsSettings → Actions → Secrets du dépôt

Sur GitLab, laissez Protect variable désactivé, sauf si vos branches codeops/* sont protégées. Une variable protégée n'est fournie qu'aux pipelines des branches protégées : le job recevrait donc une clé vide.

La clé agit au nom du membre qui l'a créée et nécessite la permission workspace:read. Lorsque votre offre inclut la limitation du périmètre des clés, un administrateur peut limiter la clé à la vérification de la barrière de livraison. Pour en savoir plus sur les clés, consultez Clés API de l'espace de travail.

Les jobs ci-dessous appellent https://console.aicodeops.dev. Utilisez l'hôte sur lequel vous ouvrez la console. La page Release gate de la console, sous Review & Gate, affiche les jobs GitHub Actions et GitLab CI avec votre adresse préremplie et un bouton Copy.

Ajouter le job

Chaque job envoie l'URL de la pull request, affiche le résumé et les motifs, et échoue sauf si la réponse est allowed: true. Le point de terminaison répond 200 pour un refus aussi : le job lit donc le champ, pas le code de statut. curl --fail transforme une mauvaise clé, une limite de débit ou une panne en job échoué.

GitHub Actions

Enregistrez ceci sous .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

Il envoie l'URL de la pull request et son commit de tête. Une session correspond sur l'un ou l'autre.

GitLab CI

Ajoutez ce job à .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

Le job s'exécute dans les pipelines de merge request. Sur une branche qu'AI CodeOps n'a pas ouverte, il réussit sans interroger la barrière, de sorte que le pipeline rapporte tout de même un résultat.

Bitbucket Pipelines

Ajoutez ceci à bitbucket-pipelines.yml. Le motif codeops/** limite l'étape aux pull requests issues de branches 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 et Gitea Actions

Enregistrez ceci sous .forgejo/workflows/aicodeops-release-gate.yml sur Forgejo, ou sous .gitea/workflows/aicodeops-release-gate.yml sur Gitea. Définissez runs-on sur un label que possède l'un de vos runners :

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; }

Celui-ci utilise grep à la place de jq : le runner n'a donc besoin que de curl. Le motif accepte des espaces autour des deux-points, de sorte qu'il lit la réponse de la même façon quel que soit son formatage. Il affiche la réponse entière, motifs compris.

Si le job échoue sur un changement qui devrait passer

  • « No workflow runs found for … » : l'URL que le job a envoyée n'est pas celle qu'AI CodeOps a enregistrée lorsqu'il a ouvert la pull request. Comparez l'URL du journal du job avec le lien de la pull request sur le changement dans la console. Une barre oblique finale est ignorée.
  • Le job échoue avant d'afficher un résumé : la clé est absente ou erronée, ou l'espace de travail a effectué plus de 60 vérifications en une minute. Vérifiez le nom du secret, et que la clé n'a pas été supprimée.

En faire une vérification requise

Un job en échec n'empêche pas une fusion à lui seul. Rendez-le obligatoire sur votre hébergeur Git :

  • GitHub. Dans la protection de branche ou un ruleset de votre branche par défaut, activez Require status checks to pass before merging et ajoutez AI CodeOps release gate. Une vérification apparaît dans la liste après s'être exécutée une fois. Sur les pull requests issues d'autres branches, le job est ignoré, et GitHub compte un job ignoré comme réussi.
  • GitLab. Sous Settings → Merge requests → Merge checks, activez Pipelines must succeed. Laissez Skipped pipelines are considered successful désactivé.
  • Bitbucket. Sous Repository settings → Branch restrictions, ajoutez la vérification de fusion exigeant un nombre minimal de builds réussis sans build en échec. Bloquer une fusion sur des vérifications de fusion non résolues nécessite l'offre Premium. Avec Standard, la vérification avertit et les personnes peuvent tout de même fusionner.
  • Forgejo et Gitea. Dans la règle de protection de branche de votre branche par défaut, activez Enable status check et ajoutez le job à Status check patterns. Exécutez d'abord le job une fois pour que son nom apparaisse.

Restreignez ensuite les personnes qui peuvent pousser vers les branches codeops/*, ou faites en sorte que les approbations soient réinitialisées lorsqu'une branche change. La barrière répond au sujet du changement de la session, pas au sujet d'un commit que quelqu'un ajoute ensuite à la branche.

Options utiles à connaître

Ajoutez des champs au corps JSON pour en demander davantage. Dans les jobs ci-dessus, c'est la ligne jq -n :

body=$(jq -n --arg pr "$PR_URL" '{pullRequestURL: $pr, blockingSeverity: "medium", minCoveragePct: 80}')
OptionValeur par défautCe qu'elle fait
blockingSeverityhighLa gravité la plus basse d'un constat ouvert qui entraîne un refus : critical, high, medium, low ou info
minCoveragePctnon définiUn seuil de couverture de 0 à 100. L'exécution de tests la plus récente ayant indiqué une couverture doit l'atteindre
blockOnInFlightfalseRefuser tant qu'une session ou un build du dépôt pour le changement est encore en cours
blockOnBuildFailuretrueUn build du dépôt portant sur le commit ou la pull request qui a échoué, dépassé le délai ou été annulé entraîne un refus. Définissez false pour exclure les builds

Le seuil de couverture refuse en cas de doute. Si vous définissez minCoveragePct et qu'aucune exécution de tests sur le changement n'a indiqué de couverture, la barrière refuse : « Coverage wasn't reported, so the 80% floor can't be checked ». Un seuil qu'elle ne peut pas vérifier ne passe pas. Définissez-le une fois que la commande de test de votre projet affiche un résumé de couverture, par exemple pytest --cov ou vitest run --coverage, et que la page d'exécution de la session affiche un chiffre de couverture.

Attendre une session en cours. Sans blockOnInFlight, un changement dont une session est terminée peut passer alors qu'une autre est encore en cours. Avec cette option, la barrière refuse jusqu'à ce que chaque session et chaque build du changement soient terminés. Un job qui doit attendre peut répéter l'appel avec une pause tant qu'un motif indique que quelque chose est encore en cours, et abandonner après sa propre limite de temps. Restez sous 60 vérifications par minute pour l'espace de travail.

Les workflows requis, les licences interdites, un déploiement antérieur requis et les autres champs sont décrits sur la page de l'API, et chaque champ de la réponse figure dans la référence de la vérification de livraison.

Étapes suivantes

Questions fréquentes

Pourquoi les jobs n'interrogent-ils que les branches codeops/ ?

La barrière juge les sessions AI CodeOps et refuse un changement qui n'en a aucune. Une pull request ouverte à la main par une personne n'a pas de session derrière elle, l'interroger à son sujet échouerait donc toujours.

Un changement refusé revient-il avec un statut d'erreur ?

Non. Le point de terminaison répond 200 pour une autorisation comme pour un refus. Le job lit le champ allowed et échoue sauf s'il vaut true.

Que se passe-t-il si la barrière est injoignable ?

Le job échoue. Chaque job de cette page traite une erreur réseau, une mauvaise clé ou une limite de débit comme un échec, de sorte qu'une vérification qui ne s'est pas exécutée ne valide jamais un changement.

Cette page vous a-t-elle été utile ?