AI CodeOps

L'API

Ce que vous pouvez appeler par programme aujourd'hui : vérification de la barrière de livraison pour la CI, avec une clé API, et clés publiques des dossiers de preuves. L'API est limitée en bêta.

AI CodeOps s'utilise dans le navigateur. Pendant la bêta ouverte, l'API par programme est volontairement réduite : un point de terminaison pour la CI, plus les clés publiques qui permettent à chacun de vérifier un dossier de preuves. Tout le reste de la console nécessite une session de navigateur connectée et n'est pas une API prise en charge.

Clés API de l'espace de travail

Créez une clé sous Configure → API Keys. Donnez-lui un nom ; le secret (il commence par sk-) n'est affiché qu'une fois, copiez-le donc à ce moment-là. AI CodeOps ne stocke qu'une empreinte.

  • Une clé agit au nom du membre qui l'a créée, avec le rôle actuel de ce membre. Si le membre est retiré ou si son rôle perd une permission, la clé la perd aussi.
  • Les rôles Owner, Admin, Developer et Member peuvent créer des clés. Le rôle Viewer ne le peut pas.
  • Les Admins voient toutes les clés de l'espace de travail ; les autres voient les leurs.
  • Delete révoque une clé immédiatement. Les intégrations qui l'utilisent cessent de fonctionner aussitôt.

Lorsque votre offre inclut la limitation du périmètre des clés, un administrateur peut choisir Scope pour limiter une clé à une liste d'adresses IP autorisées (plages CIDR), à une limite de débit par minute, à une date d'expiration et à ce pour quoi elle peut être utilisée : les appels à la passerelle de modèles, la vérification de la barrière de livraison, ou les deux (la valeur par défaut).

Envoyez la clé comme Bearer token :

Authorization: Bearer sk-...

Vérification de la barrière de livraison

POST /api/release/check répond à une question pour votre CI : cette pull request ou ce commit peut-il être livré ? Il applique les mêmes contrôles que les barrières qualité sur l'ensemble des sessions qui ont touché au changement. La clé nécessite la permission 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"}'

Utilisez le même hôte que celui sur lequel vous ouvrez la console. Barrière de livraison dans la CI propose des jobs à copier pour GitHub Actions, GitLab CI, Bitbucket Pipelines, et Forgejo et Gitea Actions.

Champs de la requête

ChampTypeValeur par défaut
pullRequestURLURLl'un de ces deux champs est obligatoire
commitSHAchaîne, 7 caractères ou plus
blockingSeveritycritical, high, medium, low, infohigh
blockOnTestFailurebooléen : des tests en échec bloquent, tout comme un changement de code sans résultat de testtrue
blockOnBuildFailurebooléen : un build du dépôt qui n'a pas réussi bloquetrue
minCoveragePctnombre de 0 à 100 : un seuil de couverture ; refuse si aucune couverture n'a été indiquéenon contrôlé
requiredWorkflowstableau de chaînesaucun
disallowedLicensestableau de chaînes, vérifié par rapport au SBOM du projetaucun
requireDeployedTonom d'environnement, p. ex. stagingaucun
blockOnInFlightbooléen : refuser tant qu'une exécution est encore en coursfalse
lookbackMsjusqu'où remonter dans le temps, en millisecondes14 jours
workspaceIDidentifiant de l'espace de travail : uniquement lorsque vous appelez avec une session de consolel'espace de travail de la clé API

GET /api/release/check accepte les mêmes noms comme paramètres de requête (listes séparées par des virgules).

Preuve par les tests. Avec blockOnTestFailure activé, ce qui est la valeur par défaut, chaque session qui a modifié du code dans un projet a besoin d'un résultat de test avec des décomptes. Si aucun test ne s'est exécuté pour elle, ou si la commande de test s'est exécutée sans indiquer de décomptes, la vérification refuse : « The test command ran but reported no test counts, so nothing shows a test passed. Check the project's test command ». Une absence de preuve n'est pas une réussite. Pour un projet sans suite de tests, activez Don't run tests for this project dans les réglages du projet, sous Plan → Projects ; la vérification ne demande alors aucun résultat de test. La règle ne s'applique pas non plus à une session qui n'a modifié aucun code, ni lorsque vous envoyez "blockOnTestFailure": false.

Seuil de couverture. Lorsque minCoveragePct est défini, l'exécution de tests la plus récente ayant indiqué une couverture doit l'atteindre. Si aucune exécution de tests sur le changement n'a indiqué de couverture, la vérification refuse : « Coverage wasn't reported, so the 80% floor can't be checked ». Un seuil qui ne peut pas être vérifié ne passe pas. Faites en sorte que la commande de test du projet affiche un résumé de couverture avant de définir un seuil. Omettez minCoveragePct et la couverture n'est pas contrôlée.

Appeler avec une session de console. Une clé API porte son espace de travail : la CI n'envoie donc pas de workspaceID. Une session de console connectée peut aussi appeler le point de terminaison, et elle doit nommer l'espace de travail : ajoutez ?workspaceID=<id> à l'URL, ou placez workspaceID dans le corps JSON d'un POST. Sans cela, la réponse est 400. L'identifiant est la partie qui suit /workspace/ dans l'adresse de la console.

Réponse

Le point de terminaison renvoie 200 dans les deux cas. Lisez allowed :

  • allowed : true ou false
  • summary et reasons : des explications en anglais simple
  • blockingFindings, testFailures, testEvidenceMissing, coverageShortfall, coverageNotReported, licenseViolations, licenseEvidenceMissing : les détails qui motivent un refus (licenseEvidenceMissing liste les projets sans SBOM à vérifier lorsque vous transmettez disallowedLicenses)
  • testEvidenceMissing : un { "workflowRunID", "reason" } pour chaque session qui a modifié du code et n'a pas de résultat de test avec des décomptes ; une liste vide lorsque rien ne manque
  • coverageNotReported : { "required": 80 } lorsque vous définissez un seuil et qu'aucune exécution de tests n'a indiqué de couverture ; null lorsqu'un chiffre de couverture existe ou qu'aucun seuil n'est défini
  • runsConsidered : les sessions sur lesquelles le verdict s'est fondé

Un changement sans session correspondante est refusé (« No workflow runs found for … »). Il en va de même pour un changement de code sans résultat de test, comme décrit sous Preuve par les tests ci-dessus. Si l'évaluation échoue, vous obtenez allowed: false avec le résumé « Evaluation failed », de sorte qu'une vérification défaillante ne valide jamais un changement.

Erreurs

StatutSignification
400JSON invalide ou champs invalides. Avec une session de console : workspaceID est manquant, et le message l'indique
401Ni clé API ni session de console, ou la clé n'est pas valide
403Le périmètre de la clé ou le rôle de son créateur ne le permet pas, ou la clé appartient à un autre espace de travail. Avec une session : vous n'êtes pas membre de l'espace de travail
429Plus de 60 vérifications par minute pour l'espace de travail ; voir Retry-After

La même vérification se trouve dans la console sous Review & Gate → Release gate, avec un job de CI à copier.

Clés des dossiers de preuves

GET /api/evidence?action=keys est public et ne nécessite aucune clé. Il renvoie les clés publiques Ed25519 qui signent les dossiers de preuves, ce qui vous permet de vérifier un dossier hors ligne. Télécharger un dossier nécessite un membre connecté ayant l'accès à l'audit ; ce n'est pas possible avec une clé API.

Référence de l'API

Une page par point de terminaison, générée à partir de la spécification OpenAPI :

Étapes suivantes

Questions fréquentes

Existe-t-il une API REST complète pour les sessions et les projets ?

Pas encore. Pendant la bêta ouverte, la console est le moyen d'exécuter des sessions et de gérer des projets. Les points de terminaison de cette page sont ceux qui acceptent un accès par programme.

Les clés API expirent-elles ?

Pas par défaut. Une clé fonctionne jusqu'à ce qu'elle soit supprimée, que son créateur quitte l'espace de travail ou qu'une date d'expiration définie dans son périmètre soit dépassée.

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