# 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.

Source: https://aicodeops.dev/fr/docs/release-gate-ci

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é](https://aicodeops.dev/fr/docs/quality-gates) 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 CI            | Où placer le secret                                                            |
| ------------------------ | ------------------------------------------------------------------------------ |
| GitHub Actions           | **Settings → Secrets and variables → Actions** du dépôt, comme secret de dépôt |
| GitLab CI                | **Settings → CI/CD → Variables**, masquée                                      |
| Bitbucket Pipelines      | **Repository settings → Repository variables**, avec **Secured** coché         |
| Forgejo et Gitea Actions | **Settings → 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](https://aicodeops.dev/fr/docs/api#workspace-api-keys).

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` :

```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
```

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` :

```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
```

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 :

```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 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 :

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

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` :

```bash
body=$(jq -n --arg pr "$PR_URL" '{pullRequestURL: $pr, blockingSeverity: "medium", minCoveragePct: 80}')
```

| Option                | Valeur par défaut | Ce qu'elle fait                                                                                                                                                       |
| --------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blockingSeverity`    | `high`            | La gravité la plus basse d'un constat ouvert qui entraîne un refus : `critical`, `high`, `medium`, `low` ou `info`                                                    |
| `minCoveragePct`      | non défini        | Un seuil de couverture de 0 à 100. L'exécution de tests la plus récente ayant indiqué une couverture doit l'atteindre                                                 |
| `blockOnInFlight`     | `false`           | Refuser tant qu'une session ou un build du dépôt pour le changement est encore en cours                                                                               |
| `blockOnBuildFailure` | `true`            | Un 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](https://aicodeops.dev/fr/docs/api), et chaque champ de la réponse figure dans la [référence de la vérification de livraison](https://aicodeops.dev/docs/api/release-check).

## Étapes suivantes

- [Barrières qualité](https://aicodeops.dev/fr/docs/quality-gates)
- [API](https://aicodeops.dev/fr/docs/api)
- [Approbations et politiques](https://aicodeops.dev/fr/docs/approvals-and-policies)
- [Déploiements sous contrôle](https://aicodeops.dev/fr/docs/gated-deploys)

## 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.
