Étapes et promotion
Étapes d’un artefact (par exemple release), promotion entre dépôts et résolution d’une étape en version.
Opérations de ce groupe, avec leur règle d’accès, leur règle de nouvelle tentative, leurs paramètres et leurs réponses. Chaque requête porte une clé : Authorization: Bearer <clé> (voir « Authentification »).
Opérations
Lister les étapes d’un artefact
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/stages
Accès: Autorisation sur le dépôt : artifact.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie les étapes de promotion actuelles d’un artefact publié (16 au plus), chacune avec sa date d’ajout, l’acteur et le commentaire.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
items | tableau de object | oui | jusqu’à 16 éléments |
items[].artifactId | string (uuid) | oui | — |
items[].stage | string | oui | correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | oui | — |
items[].actor | string | oui | — |
items[].comment | string | oui | jusqu’à 1024 caractères; peut être null |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Ajouter une étape à un artefact
PUT /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Accès: Autorisation sur le dépôt : artifact.promote, artifact.read; clés de fichier : read, write · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet
Marque un artefact publié avec stage (1–32 lettres minuscules, chiffres ou _.-, commençant par une lettre ou un chiffre), avec un comment facultatif de 1024 caractères au plus, et consigne l’événement dans le journal des promotions. Ajouter une étape que l’artefact possède déjà ne change rien et conserve la date d’origine : pour promouvoir de nouveau la même version (pour un retour arrière avec order=promoted), retirez d’abord l’étape. Un artefact a au plus 16 étapes (409 stage_limit).
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
stage | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Corps de la requête (application/json)
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
comment | string | non | jusqu’à 1024 caractères; peut être null |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
artifactId | string (uuid) | oui | — |
stage | string | oui | correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$ |
promotedAt | string (date-time) | oui | — |
actor | string | oui | — |
comment | string | oui | jusqu’à 1024 caractères; peut être null |
Réponses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemple
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Retirer une étape d’un artefact
DELETE /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Accès: Autorisation sur le dépôt : artifact.promote, artifact.read; clés de fichier : read, write · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet
Retire stage d’un artefact publié et consigne l’événement dans le journal des promotions ; retirer une étape que l’artefact n’a pas réussit aussi. La résolution de paquet par cette étape cesse aussitôt de choisir l’artefact.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
stage | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Réponses: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Lister l’historique des promotions d’un artefact
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/promotions
Accès: Autorisation sur le dépôt : artifact.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie le journal d’un artefact, du plus ancien au plus récent : étapes ajoutées et retirées, promotions vers d’autres dépôts et depuis ceux-ci, avec l’artefact correspondant, l’acteur, le commentaire et l’heure. Les pages contiennent limit événements (1–100, 50 par défaut) ; poursuivez avec after défini sur next.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
after | requête | string | non | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
limit | requête | string | non | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; At most 100. |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
items | tableau de object | oui | jusqu’à 100 éléments |
items[].sequence | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
items[].repository | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | oui | — |
items[].action | string | oui | une valeur parmi stage.added, stage.removed, promoted, received |
items[].stage | string | oui | correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$; peut être null |
items[].mode | string | oui | une valeur parmi copy, move, null; peut être null |
items[].peerRepository | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$; peut être null |
items[].peerArtifactId | string (uuid) | oui | peut être null |
items[].actor | string | oui | — |
items[].comment | string | oui | jusqu’à 1024 caractères; peut être null |
items[].occurredAt | string (date-time) | oui | — |
next | string | oui | peut être null |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Promouvoir un artefact vers un autre dépôt
POST /api/v1/repositories/{repository}/artifacts/{id}/promote
Accès: Autorisation sur le dépôt : artifact.read, content.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet
Publie l’artefact dans target sans renvoyer les octets, éventuellement avec stages et un comment ; l’appelant doit aussi détenir artifact.promote dans la cible. mode copy (par défaut) conserve la source ; move, qui exige aussi artifact.promote ici, retire la source dans la même transaction, reporte ses étapes et est refusé avec 409 lorsque la source ne peut pas être supprimée. La réponse est 201 avec la copie ; une répétition renvoie la même copie avec 200, et une cible qui a déjà cette version de paquet renvoie cet artefact si le SHA-256 correspond et un 409 version_exists sinon. Les pièces jointes de build et les chemins de fichiers ne sont pas reportés.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
Corps de la requête (application/json)
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
target | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
mode | string | non | une valeur parmi copy, move |
stages | tableau de string | non | jusqu’à 16 éléments; aucun élément répété; chaque élément : correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$ |
comment | string | non | jusqu’à 1024 caractères; peut être null |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
repository | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
artifactId | string (uuid) | oui | — |
sourceRepository | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
sourceArtifactId | string (uuid) | oui | — |
mode | string | oui | une valeur parmi copy, move |
created | boolean | oui | — |
stages | tableau de string | oui | jusqu’à 16 éléments; aucun élément répété; chaque élément : correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Réponses: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemple
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promote" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"target":"<target>"}'Lister les artefacts ayant des étapes
GET HEAD /api/v1/repositories/{repository}/stages
Accès: Autorisation sur le dépôt : artifact.list; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Liste les entrées d’étapes du dépôt (artefact, étape, heure, acteur, commentaire) triées par artefact et par étape, éventuellement seulement stage, ou seulement les artefacts de ids (1–100 ID séparés par des virgules, par exemple pour afficher d’un coup les étapes d’une page de paquets). Les pages contiennent limit entrées (1–100, 100 par défaut) ; poursuivez avec after défini sur next (<artifactId>/<stage>).
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
stage | requête | string | non | correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$ |
after | requête | string | non | — |
limit | requête | string | non | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; At most 100. |
ids | requête | string | non | jusqu’à 3699 caractères; Up to 100 comma-separated artifact ids. |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
items | tableau de object | oui | jusqu’à 100 éléments |
items[].artifactId | string (uuid) | oui | — |
items[].stage | string | oui | correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | oui | — |
items[].actor | string | oui | — |
items[].comment | string | oui | jusqu’à 1024 caractères; peut être null |
next | string | oui | peut être null |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Suivre le journal des promotions d’un dépôt
GET HEAD /api/v1/repositories/{repository}/promotions
Accès: Autorisation sur le dépôt : artifact.list; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie les événements d’étapes et de promotions de chaque artefact du dépôt, du plus ancien au plus récent, à interroger par le CI/CD : étape ajoutée ou retirée, promu vers un autre dépôt, reçu d’un autre. Les pages contiennent limit événements (1–100, 50 par défaut) ; conservez le dernier sequence et poursuivez avec after défini sur next.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | requête | string | non | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
limit | requête | string | non | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; At most 100. |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
items | tableau de object | oui | jusqu’à 100 éléments |
items[].sequence | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
items[].repository | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | oui | — |
items[].action | string | oui | une valeur parmi stage.added, stage.removed, promoted, received |
items[].stage | string | oui | correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$; peut être null |
items[].mode | string | oui | une valeur parmi copy, move, null; peut être null |
items[].peerRepository | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$; peut être null |
items[].peerArtifactId | string (uuid) | oui | peut être null |
items[].actor | string | oui | — |
items[].comment | string | oui | jusqu’à 1024 caractères; peut être null |
items[].occurredAt | string (date-time) | oui | — |
next | string | oui | peut être null |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Résoudre une version de paquet
GET HEAD /api/v1/repositories/{repository}/packages/resolve
Accès: Autorisation sur le dépôt : package.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Choisit une version UPack enregistrée selon les mêmes règles que downloadPackageContent et la renvoie sans les octets : version, ID de l’artefact, SHA-256, taille, date de publication et étapes actuelles. name est obligatoire, group vaut par défaut le groupe racine ; sélectionnez par version exacte ou plage SemVer range, éventuellement stage, prerelease=true et order=promoted (exige stage) ; sans version ni range, c’est la version stable la plus élevée. Une absence de correspondance donne 404 ; téléchargez le résultat par ID d’artefact pour rester sur cette version.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
group | requête | string | non | jusqu’à 128 caractères |
name | requête | string | oui | 1–128 caractères |
version | requête | string | non | jusqu’à 128 caractères; Exact version; excludes range. |
range | requête | string | non | jusqu’à 256 caractères; SemVer range: 1.2.3, ^1.2, ~1.2.3, 1.x, >=1.0.0 <2.0.0, a || b. |
stage | requête | string | non | correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$; Only versions promoted to this stage. |
prerelease | requête | string | non | une valeur parmi true, false; Include prereleases. |
order | requête | string | non | une valeur parmi version, promoted; promoted picks the most recently staged version and requires stage. |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
group | string | oui | — |
name | string | oui | — |
version | string | oui | — |
artifactId | string (uuid) | oui | — |
sha256 | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
size | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
publishedAt | string (date-time) | oui | — |
stagedAt | string (date-time) | oui | peut être null |
stages | tableau de string | oui | jusqu’à 16 éléments; aucun élément répété; chaque élément : correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/packages/resolve?name=$NAME" \
-H "Authorization: Bearer $ARKVORY_TOKEN"