Estágios e promoção
Estágios de um artefato (por exemplo, release), promoção entre repositórios e resolução de um estágio para uma versão.
Operações deste grupo com a regra de acesso, a regra de repetição, os parâmetros e as respostas. Toda solicitação leva uma chave: Authorization: Bearer <chave> (consulte “Autenticação”).
Operações
Listar os estágios de um artefato
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/stages
Acesso: Permissão no repositório: artifact.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)
Retorna os estágios de promoção atuais de um artefato publicado (no máximo 16), cada um com a hora em que foi adicionado, o ator e o comentário.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | sim | até 16 itens |
items[].artifactId | string (uuid) | sim | — |
items[].stage | string | sim | corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | sim | — |
items[].actor | string | sim | — |
items[].comment | string | sim | até 1024 caracteres; pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Adicionar um estágio a um artefato
PUT /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Acesso: Permissão no repositório: artifact.promote, artifact.read; chaves em arquivo: read, write · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Marca um artefato publicado com stage (1–32 letras minúsculas, dígitos ou _.-, começando por uma letra ou um dígito), com um comment opcional de até 1024 caracteres, e registra o evento no diário de promoções. Adicionar um estágio que o artefato já tem não altera nada e mantém a hora original; portanto, para promover a mesma versão novamente (para um rollback com order=promoted), remova o estágio primeiro. Um artefato tem no máximo 16 estágios (409 stage_limit).
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
stage | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
comment | string | não | até 1024 caracteres; pode ser null |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
artifactId | string (uuid) | sim | — |
stage | string | sim | corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$ |
promotedAt | string (date-time) | sim | — |
actor | string | sim | — |
comment | string | sim | até 1024 caracteres; pode ser null |
Respostas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Remover um estágio de um artefato
DELETE /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Acesso: Permissão no repositório: artifact.promote, artifact.read; chaves em arquivo: read, write · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Remove stage de um artefato publicado e registra o evento no diário de promoções; remover um estágio que o artefato não tem também tem sucesso. A resolução de pacotes por esse estágio deixa de escolher o artefato imediatamente.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
stage | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Listar o histórico de promoções de um artefato
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/promotions
Acesso: Permissão no repositório: artifact.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)
Retorna o diário de um artefato, do mais antigo para o mais recente: estágios adicionados e removidos, promoções para outros repositórios e a partir deles, com o artefato correspondente, o ator, o comentário e a hora. As páginas contêm limit eventos (1–100, padrão 50); continue com after definido como next.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
after | consulta | string | não | um número inteiro em dígitos decimais, enviado como string |
limit | consulta | string | não | um número inteiro em dígitos decimais, enviado como string; At most 100. |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | sim | até 100 itens |
items[].sequence | string | sim | um número inteiro em dígitos decimais, enviado como string |
items[].repository | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | sim | — |
items[].action | string | sim | um destes: stage.added, stage.removed, promoted, received |
items[].stage | string | sim | corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$; pode ser null |
items[].mode | string | sim | um destes: copy, move, null; pode ser null |
items[].peerRepository | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$; pode ser null |
items[].peerArtifactId | string (uuid) | sim | pode ser null |
items[].actor | string | sim | — |
items[].comment | string | sim | até 1024 caracteres; pode ser null |
items[].occurredAt | string (date-time) | sim | — |
next | string | sim | pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Promover um artefato para outro repositório
POST /api/v1/repositories/{repository}/artifacts/{id}/promote
Acesso: Permissão no repositório: artifact.read, content.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Publica o artefato em target sem enviar os bytes novamente, opcionalmente com stages e um comment; o chamador também precisa de artifact.promote no destino. mode copy (padrão) mantém a origem; move, que exige artifact.promote também aqui, retira a origem na mesma transação, leva seus estágios junto e é recusado com 409 quando a origem não pode ser excluída. A resposta é 201 com a cópia; uma repetição retorna a mesma cópia com 200, e um destino que já tem esta versão do pacote retorna esse artefato quando o SHA-256 coincide e 409 version_exists quando não coincide. Os anexos de build e os caminhos de arquivo não são transferidos.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
target | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
mode | string | não | um destes: copy, move |
stages | array de string | não | até 16 itens; sem itens repetidos; cada item: corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$ |
comment | string | não | até 1024 caracteres; pode ser null |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
repository | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
artifactId | string (uuid) | sim | — |
sourceRepository | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
sourceArtifactId | string (uuid) | sim | — |
mode | string | sim | um destes: copy, move |
created | boolean | sim | — |
stages | array de string | sim | até 16 itens; sem itens repetidos; cada item: corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Respostas: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
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 artefatos com estágios
GET HEAD /api/v1/repositories/{repository}/stages
Acesso: Permissão no repositório: artifact.list; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)
Lista as entradas de estágio do repositório (artefato, estágio, hora, ator, comentário) ordenadas por artefato e estágio, opcionalmente apenas stage ou apenas os artefatos em ids (1–100 IDs separados por vírgula, por exemplo para mostrar de uma só vez os estágios de uma página de pacotes). As páginas contêm limit entradas (1–100, padrão 100); continue com after definido como next (<artifactId>/<stage>).
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
stage | consulta | string | não | corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$ |
after | consulta | string | não | — |
limit | consulta | string | não | um número inteiro em dígitos decimais, enviado como string; At most 100. |
ids | consulta | string | não | até 3699 caracteres; Up to 100 comma-separated artifact ids. |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | sim | até 100 itens |
items[].artifactId | string (uuid) | sim | — |
items[].stage | string | sim | corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | sim | — |
items[].actor | string | sim | — |
items[].comment | string | sim | até 1024 caracteres; pode ser null |
next | string | sim | pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Acompanhar o diário de promoções de um repositório
GET HEAD /api/v1/repositories/{repository}/promotions
Acesso: Permissão no repositório: artifact.list; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)
Retorna os eventos de estágio e de promoção de todos os artefatos do repositório, do mais antigo para o mais recente, para consulta periódica por CI/CD: estágio adicionado ou removido, promovido para outro repositório, recebido de outro. As páginas contêm limit eventos (1–100, padrão 50); guarde o último sequence e continue com after definido como next.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | consulta | string | não | um número inteiro em dígitos decimais, enviado como string |
limit | consulta | string | não | um número inteiro em dígitos decimais, enviado como string; At most 100. |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | sim | até 100 itens |
items[].sequence | string | sim | um número inteiro em dígitos decimais, enviado como string |
items[].repository | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | sim | — |
items[].action | string | sim | um destes: stage.added, stage.removed, promoted, received |
items[].stage | string | sim | corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$; pode ser null |
items[].mode | string | sim | um destes: copy, move, null; pode ser null |
items[].peerRepository | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$; pode ser null |
items[].peerArtifactId | string (uuid) | sim | pode ser null |
items[].actor | string | sim | — |
items[].comment | string | sim | até 1024 caracteres; pode ser null |
items[].occurredAt | string (date-time) | sim | — |
next | string | sim | pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Resolver uma versão de pacote
GET HEAD /api/v1/repositories/{repository}/packages/resolve
Acesso: Permissão no repositório: package.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)
Escolhe uma versão UPack registrada pelas mesmas regras de downloadPackageContent e a retorna sem os bytes: versão, ID do artefato, SHA-256, tamanho, data de publicação e estágios atuais. name é obrigatório e group usa por padrão o grupo raiz; selecione por version exata ou por range SemVer, opcionalmente stage, prerelease=true e order=promoted (exige stage); sem version e range, é a versão estável mais alta. Sem correspondência, é um 404; baixe o resultado pelo ID do artefato para permanecer nessa versão.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
group | consulta | string | não | até 128 caracteres |
name | consulta | string | sim | 1–128 caracteres |
version | consulta | string | não | até 128 caracteres; Exact version; excludes range. |
range | consulta | string | não | até 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 | não | corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$; Only versions promoted to this stage. |
prerelease | consulta | string | não | um destes: true, false; Include prereleases. |
order | consulta | string | não | um destes: version, promoted; promoted picks the most recently staged version and requires stage. |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
group | string | sim | — |
name | string | sim | — |
version | string | sim | — |
artifactId | string (uuid) | sim | — |
sha256 | string | sim | SHA-256: 64 dígitos hexadecimais minúsculos |
size | string | sim | um número inteiro em dígitos decimais, enviado como string |
publishedAt | string (date-time) | sim | — |
stagedAt | string (date-time) | sim | pode ser null |
stages | array de string | sim | até 16 itens; sem itens repetidos; cada item: corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/packages/resolve?name=$NAME" \
-H "Authorization: Bearer $ARKVORY_TOKEN"