Piloter depuis un outil externe
L'équipe d'Atelier Exemple veut déclencher et suivre les exécutions depuis son outil de suivi interne. Dominique crée une clé API personnelle limitée à ce besoin et écrit les appels.
Objectif#
Démarrer une exécution sur une issue, suivre son état et lire la consommation du projet depuis un script, sans jamais exposer la clé.
Rôles nécessaires#
| Personne | Rôle | Intervient pour |
|---|---|---|
| Dominique | Opérateur du projet Site vitrine | Créer la clé et l'utiliser |
Une clé ne donne jamais plus que les droits actuels de la personne qui l'a créée. Pour démarrer une exécution, il faut donc au moins le rôle Opérateur.
Prérequis#
- Le dépôt est actif, rattaché et surveillé, et l'issue visée est ouverte et suivie par la plateforme. Voir Embarquer une équipe sur un projet.
- L'outil sait conserver un secret (gestionnaire de secrets, variable protégée de CI).
Étapes#
Créer une clé à droits restreints#
- Dominique fait une vérification récente.
- Dans la barre Supervision, il ouvre Mes clés API, carte Créer une clé.
- Libellé :
outil-suivi-site-vitrine. Durée en jours :30. - Projets : il coche seulement Site vitrine.
- Droits de la clé : il coche Lire les projets, Lire les dépôts, Lire les exécutions, Démarrer une exécution et Lire la consommation. Rien d'autre.
- Il clique sur Créer la clé. Le Secret de la clé s'affiche une seule fois : il le copie dans le gestionnaire de secrets, puis clique sur Masquer le secret.
Voir Clés API personnelles et Authentification et scopes.
Retrouver le projet et le dépôt#
- Le script lit la clé depuis une variable d'environnement, jamais depuis le code :
export MAINTAIN_API_KEY="<secret lu depuis le gestionnaire>"
curl -sS https://maintenance.maintain.example/api/v1/projects \
-H "Authorization: Bearer $MAINTAIN_API_KEY"- Avec l'identifiant du projet, il liste les dépôts pour obtenir
repositoryId:
curl -sS https://maintenance.maintain.example/api/v1/projects/<projectId>/repositories \
-H "Authorization: Bearer $MAINTAIN_API_KEY"Démarrer une exécution, sans doublon#
- Il demande l'exécution de l'issue n° 42, avec une clé d'idempotence stable (8 à 128 caractères) :
curl -sS -i -X POST https://maintenance.maintain.example/api/v1/projects/<projectId>/runs \
-H "Authorization: Bearer $MAINTAIN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: site-vitrine-issue-42" \
-d '{"repositoryId":"<repositoryId>","issueNumber":42}'La réponse est 202 avec l'en-tête Location: /api/v1/runs/<runId>. Si le script renvoie la même requête (coupure réseau, nouvel essai), la même réponse est rejouée pendant 24 heures, avec l'en-tête Idempotent-Replayed: true. Une seule exécution est créée.
Notez aussi l'en-tête X-Correlation-Id : il retrouve la demande dans le journal des actions.
Suivre l'exécution#
- Le script interroge l'exécution à intervalle raisonnable :
curl -sS https://maintenance.maintain.example/api/v1/runs/<runId> \
-H "Authorization: Bearer $MAINTAIN_API_KEY"Le champ status évolue, par exemple de queued à running, puis prepared (correctif prêt) ou needs_input (précisions requises). Les réponses aux questions se font dans l'interface : elles n'ont pas de route d'API.
Lire la consommation#
- En fin de mois, le script exporte la consommation du projet :
curl -sS https://maintenance.maintain.example/api/v1/projects/<projectId>/usage \
-H "Authorization: Bearer $MAINTAIN_API_KEY"Un usage inconnu reste signalé comme tel, jamais converti en zéro. Voir Comprendre la consommation.
Réagir à un arrêt global#
- Pendant un incident, l'Administrateur active l'arrêt global. Une nouvelle demande d'exécution n'est pas refusée : elle répond
202, comme d'habitude, avec en plus le champwaiting:
{
"id": "<runId>",
"status": "queued",
"repositoryId": "<repositoryId>",
"issueNumber": 42,
"waiting": "organization_stop"
}L'exécution reste en file et démarrera une seule fois après la levée. Tant qu'elle attend, GET /api/v1/runs/<runId> porte le même champ waiting. Le script n'a rien à redemander : il signale l'attente et continue de suivre l'exécution. Un rejeu avec la même clé d'idempotence, pendant ou après l'arrêt, renvoie le même identifiant sans créer de second travail. Une demande d'audit se comporte de la même façon.
Résultat attendu#
- Une exécution créée une seule fois, même si la demande arrive pendant un arrêt global, visible dans la File de travail.
- Chaque appel inscrit au journal des actions avec le type d'acteur Clé API, le compte de Dominique et l'identifiant de la clé.
- La clé apparaît dans l'inventaire des clés avec sa date de dernière utilisation.
Si ça bloque#
| Code | Cause | Que faire |
|---|---|---|
401 | Clé absente, invalide, expirée ou révoquée, ou compte inactif. | Vérifiez la variable, créez une nouvelle clé. |
403 | Droit absent de la clé, ou rôle devenu insuffisant. | Vérifiez les droits de la clé et le rôle sur le projet. |
404 | Projet hors de la clé ou hors de vos droits. | Vérifiez le projet coché à la création. |
409 | Issue fermée, exécution déjà existante, ou clé d'idempotence réutilisée avec un autre corps. | Lisez le champ error. |
429 | Quota de 120 requêtes par minute, par clé et par projet, dépassé. | Attendez la durée indiquée par Retry-After. |
Voir aussi Erreurs, Idempotence et quotas et les recettes.
Pour continuer#
Pour la référence complète des routes, voyez Intégration API.