Etapas y promoción
Etapas de un artefacto (por ejemplo, release), promoción entre repositorios y resolución de una etapa a una versión.
Operaciones de este grupo con su regla de acceso, su regla de reintento, sus parámetros y sus respuestas. Cada solicitud lleva una clave: Authorization: Bearer <clave> (consulte «Autenticación»).
Operaciones
Listar las etapas de un artefacto
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/stages
Acceso: Permiso de repositorio: artifact.read; claves de archivo: read · Reintento: Se puede repetir (lectura)
Devuelve las etapas de promoción actuales de un artefacto publicado (como máximo 16), cada una con la hora en que se añadió, el actor y el comentario.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | sí | hasta 16 elementos |
items[].artifactId | string (uuid) | sí | — |
items[].stage | string | sí | coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | sí | — |
items[].actor | string | sí | — |
items[].comment | string | sí | hasta 1024 caracteres; puede ser null |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Añadir una etapa a un artefacto
PUT /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Acceso: Permiso de repositorio: artifact.promote, artifact.read; claves de archivo: read, write · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Marca un artefacto publicado con stage (1–32 letras minúsculas, dígitos o _.-, empezando por una letra o un dígito), con un comment opcional de hasta 1024 caracteres, y registra el evento en el diario de promociones. Añadir una etapa que el artefacto ya tiene no cambia nada y conserva la hora original, por lo que, para promover de nuevo la misma versión (para una reversión con order=promoted), quite primero la etapa. Un artefacto tiene como máximo 16 etapas (409 stage_limit).
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
stage | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
comment | string | no | hasta 1024 caracteres; puede ser null |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
artifactId | string (uuid) | sí | — |
stage | string | sí | coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$ |
promotedAt | string (date-time) | sí | — |
actor | string | sí | — |
comment | string | sí | hasta 1024 caracteres; puede ser null |
Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Quitar una etapa de un artefacto
DELETE /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Acceso: Permiso de repositorio: artifact.promote, artifact.read; claves de archivo: read, write · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Quita stage de un artefacto publicado y registra el evento en el diario de promociones; quitar una etapa que el artefacto no tiene también se completa con éxito. La resolución de paquetes por esta etapa deja de elegir el artefacto de inmediato.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
stage | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Respuestas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Ejemplo
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Listar el historial de promociones de un artefacto
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/promotions
Acceso: Permiso de repositorio: artifact.read; claves de archivo: read · Reintento: Se puede repetir (lectura)
Devuelve el diario de un artefacto, del más antiguo al más reciente: etapas añadidas y quitadas, promociones hacia y desde otros repositorios con el artefacto correspondiente, actor, comentario y hora. Las páginas contienen limit eventos (1–100, 50 por defecto); continúe pasando next como after.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
after | consulta | string | no | un número entero en dígitos decimales, enviado como cadena |
limit | consulta | string | no | un número entero en dígitos decimales, enviado como cadena; At most 100. |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | sí | hasta 100 elementos |
items[].sequence | string | sí | un número entero en dígitos decimales, enviado como cadena |
items[].repository | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | sí | — |
items[].action | string | sí | uno de stage.added, stage.removed, promoted, received |
items[].stage | string | sí | coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$; puede ser null |
items[].mode | string | sí | uno de copy, move, null; puede ser null |
items[].peerRepository | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$; puede ser null |
items[].peerArtifactId | string (uuid) | sí | puede ser null |
items[].actor | string | sí | — |
items[].comment | string | sí | hasta 1024 caracteres; puede ser null |
items[].occurredAt | string (date-time) | sí | — |
next | string | sí | puede ser null |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Promover un artefacto a otro repositorio
POST /api/v1/repositories/{repository}/artifacts/{id}/promote
Acceso: Permiso de repositorio: artifact.read, content.read; claves de archivo: read · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Publica el artefacto en target sin volver a enviar los bytes, opcionalmente con stages y un comment; quien llama necesita además artifact.promote en el destino. mode copy (por defecto) conserva el origen; move, que requiere también artifact.promote aquí, retira el origen en la misma transacción, transfiere sus etapas y se rechaza con 409 cuando el origen no se puede eliminar. La respuesta es 201 con la copia; una repetición devuelve la misma copia con 200, y un destino que ya tiene esta versión del paquete devuelve ese artefacto cuando el SHA-256 coincide y un 409 version_exists cuando no. Los adjuntos de compilación y las rutas de archivo no se transfieren.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
target | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
mode | string | no | uno de copy, move |
stages | array de string | no | hasta 16 elementos; sin elementos repetidos; cada elemento: coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$ |
comment | string | no | hasta 1024 caracteres; puede ser null |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
repository | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
artifactId | string (uuid) | sí | — |
sourceRepository | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
sourceArtifactId | string (uuid) | sí | — |
mode | string | sí | uno de copy, move |
created | boolean | sí | — |
stages | array de string | sí | hasta 16 elementos; sin elementos repetidos; cada elemento: coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Respuestas: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
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>"}'Listar artefactos con etapas
GET HEAD /api/v1/repositories/{repository}/stages
Acceso: Permiso de repositorio: artifact.list; claves de archivo: read · Reintento: Se puede repetir (lectura)
Enumera las entradas de etapa del repositorio (artefacto, etapa, hora, actor, comentario) ordenadas por artefacto y etapa, opcionalmente solo stage, o solo los artefactos de ids (de 1 a 100 IDs separados por comas, por ejemplo para mostrar de una vez las etapas de una página de paquetes). Las páginas contienen limit entradas (1–100, 100 por defecto); continúe pasando next como after (<artifactId>/<stage>).
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
stage | consulta | string | no | coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$ |
after | consulta | string | no | — |
limit | consulta | string | no | un número entero en dígitos decimales, enviado como cadena; At most 100. |
ids | consulta | string | no | hasta 3699 caracteres; Up to 100 comma-separated artifact ids. |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | sí | hasta 100 elementos |
items[].artifactId | string (uuid) | sí | — |
items[].stage | string | sí | coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | sí | — |
items[].actor | string | sí | — |
items[].comment | string | sí | hasta 1024 caracteres; puede ser null |
next | string | sí | puede ser null |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Seguir el diario de promociones de un repositorio
GET HEAD /api/v1/repositories/{repository}/promotions
Acceso: Permiso de repositorio: artifact.list; claves de archivo: read · Reintento: Se puede repetir (lectura)
Devuelve los eventos de etapa y de promoción de todos los artefactos del repositorio, del más antiguo al más reciente, para que CI/CD los sondee: etapa añadida o quitada, promovido a otro repositorio, recibido de uno. Las páginas contienen limit eventos (1–100, 50 por defecto); guarde el último sequence y continúe pasando next como after.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | consulta | string | no | un número entero en dígitos decimales, enviado como cadena |
limit | consulta | string | no | un número entero en dígitos decimales, enviado como cadena; At most 100. |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | sí | hasta 100 elementos |
items[].sequence | string | sí | un número entero en dígitos decimales, enviado como cadena |
items[].repository | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | sí | — |
items[].action | string | sí | uno de stage.added, stage.removed, promoted, received |
items[].stage | string | sí | coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$; puede ser null |
items[].mode | string | sí | uno de copy, move, null; puede ser null |
items[].peerRepository | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$; puede ser null |
items[].peerArtifactId | string (uuid) | sí | puede ser null |
items[].actor | string | sí | — |
items[].comment | string | sí | hasta 1024 caracteres; puede ser null |
items[].occurredAt | string (date-time) | sí | — |
next | string | sí | puede ser null |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Resolver una versión de paquete
GET HEAD /api/v1/repositories/{repository}/packages/resolve
Acceso: Permiso de repositorio: package.read; claves de archivo: read · Reintento: Se puede repetir (lectura)
Elige una versión de UPack registrada con las mismas reglas que downloadPackageContent y la devuelve sin los bytes: versión, ID del artefacto, SHA-256, tamaño, hora de publicación y etapas actuales. name es obligatorio y group es por defecto el grupo raíz; seleccione por version exacta o por range SemVer, opcionalmente stage, prerelease=true y order=promoted (requiere stage); sin version ni range se elige la versión estable más alta. Si no hay coincidencia, es un 404; descargue el resultado por ID de artefacto para quedarse en esa versión.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
group | consulta | string | no | hasta 128 caracteres |
name | consulta | string | sí | 1–128 caracteres |
version | consulta | string | no | hasta 128 caracteres; Exact version; excludes range. |
range | consulta | string | no | hasta 256 caracteres; SemVer range: 1.2.3, ^1.2, ~1.2.3, 1.x, >=1.0.0 <2.0.0, a || b. |
stage | consulta | string | no | coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$; Only versions promoted to this stage. |
prerelease | consulta | string | no | uno de true, false; Include prereleases. |
order | consulta | string | no | uno de version, promoted; promoted picks the most recently staged version and requires stage. |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
group | string | sí | — |
name | string | sí | — |
version | string | sí | — |
artifactId | string (uuid) | sí | — |
sha256 | string | sí | SHA-256: 64 dígitos hexadecimales en minúsculas |
size | string | sí | un número entero en dígitos decimales, enviado como cadena |
publishedAt | string (date-time) | sí | — |
stagedAt | string (date-time) | sí | puede ser null |
stages | array de string | sí | hasta 16 elementos; sin elementos repetidos; cada elemento: coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/packages/resolve?name=$NAME" \
-H "Authorization: Bearer $ARKVORY_TOKEN"