- Accueil
- Documentation
- L'API
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
| Champ | Type | Valeur par défaut |
|---|---|---|
pullRequestURL | URL | l'un de ces deux champs est obligatoire |
commitSHA | chaîne, 7 caractères ou plus | |
blockingSeverity | critical, high, medium, low, info | high |
blockOnTestFailure | booléen : des tests en échec bloquent, tout comme un changement de code sans résultat de test | true |
blockOnBuildFailure | booléen : un build du dépôt qui n'a pas réussi bloque | true |
minCoveragePct | nombre de 0 à 100 : un seuil de couverture ; refuse si aucune couverture n'a été indiquée | non contrôlé |
requiredWorkflows | tableau de chaînes | aucun |
disallowedLicenses | tableau de chaînes, vérifié par rapport au SBOM du projet | aucun |
requireDeployedTo | nom d'environnement, p. ex. staging | aucun |
blockOnInFlight | booléen : refuser tant qu'une exécution est encore en cours | false |
lookbackMs | jusqu'où remonter dans le temps, en millisecondes | 14 jours |
workspaceID | identifiant de l'espace de travail : uniquement lorsque vous appelez avec une session de console | l'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:trueoufalsesummaryetreasons: des explications en anglais simpleblockingFindings,testFailures,testEvidenceMissing,coverageShortfall,coverageNotReported,licenseViolations,licenseEvidenceMissing: les détails qui motivent un refus (licenseEvidenceMissingliste les projets sans SBOM à vérifier lorsque vous transmettezdisallowedLicenses)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 manquecoverageNotReported:{ "required": 80 }lorsque vous définissez un seuil et qu'aucune exécution de tests n'a indiqué de couverture ;nulllorsqu'un chiffre de couverture existe ou qu'aucun seuil n'est définirunsConsidered: 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
| Statut | Signification |
|---|---|
| 400 | JSON invalide ou champs invalides. Avec une session de console : workspaceID est manquant, et le message l'indique |
| 401 | Ni clé API ni session de console, ou la clé n'est pas valide |
| 403 | Le 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 |
| 429 | Plus 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 :
- Vérifier si une pull request ou un commit peut être livré
- Les clés qui signent les dossiers de preuves
- Vérifier un dossier de preuves
- Liveness et readiness
- État des composants
É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.