Stages and promotion
Stages of an artifact (for example release), promotion between repositories and resolution of a stage to a version.
Operations of this group with their access rule, retry rule, parameters and answers. Every request carries a key: Authorization: Bearer <key> (see Authentication).
Operations
List the stages of an artifact
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/stages
Access: Repository permission: artifact.read; file keys: read · Retry: Safe to repeat (read)
Returns the current promotion stages of a published artifact (at most 16), each with the time it was added, the actor and the comment.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | up to 16 items |
items[].artifactId | string (uuid) | yes | — |
items[].stage | string | yes | matches ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | yes | — |
items[].actor | string | yes | — |
items[].comment | string | yes | up to 1024 characters; may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Add a stage to an artifact
PUT /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Access: Repository permission: artifact.promote, artifact.read; file keys: read, write · Retry: Safe to repeat: the same request has the same effect
Marks a published artifact with stage (1–32 lower-case letters, digits or _.-, starting with a letter or digit), with an optional comment of up to 1024 characters, and records the event in the promotion journal. Adding a stage the artifact already has changes nothing and keeps the original time, so to promote the same version again (for a rollback with order=promoted) remove the stage first. An artifact has at most 16 stages (409 stage_limit).
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
stage | path | string | yes | matches ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
comment | string | no | up to 1024 characters; may be null |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
artifactId | string (uuid) | yes | — |
stage | string | yes | matches ^[a-z0-9][a-z0-9_.-]{0,31}$ |
promotedAt | string (date-time) | yes | — |
actor | string | yes | — |
comment | string | yes | up to 1024 characters; may be null |
Responses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Remove a stage from an artifact
DELETE /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Access: Repository permission: artifact.promote, artifact.read; file keys: read, write · Retry: Safe to repeat: the same request has the same effect
Removes stage from a published artifact and records the event in the promotion journal; removing a stage the artifact does not have succeeds too. Package resolution by this stage stops choosing the artifact at once.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
stage | path | string | yes | matches ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Responses: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Example
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN"List the promotion history of an artifact
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/promotions
Access: Repository permission: artifact.read; file keys: read · Retry: Safe to repeat (read)
Returns the journal of one artifact, oldest first: stages added and removed, promotions to and from other repositories with the peer artifact, actor, comment and time. Pages hold limit events (1–100, default 50); continue with after set to next.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
after | query | string | no | a whole number in decimal digits, sent as a string |
limit | query | string | no | a whole number in decimal digits, sent as a string; At most 100. |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | up to 100 items |
items[].sequence | string | yes | a whole number in decimal digits, sent as a string |
items[].repository | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | yes | — |
items[].action | string | yes | one of stage.added, stage.removed, promoted, received |
items[].stage | string | yes | matches ^[a-z0-9][a-z0-9_.-]{0,31}$; may be null |
items[].mode | string | yes | one of copy, move, null; may be null |
items[].peerRepository | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$; may be null |
items[].peerArtifactId | string (uuid) | yes | may be null |
items[].actor | string | yes | — |
items[].comment | string | yes | up to 1024 characters; may be null |
items[].occurredAt | string (date-time) | yes | — |
next | string | yes | may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Promote an artifact to another repository
POST /api/v1/repositories/{repository}/artifacts/{id}/promote
Access: Repository permission: artifact.read, content.read; file keys: read · Retry: Safe to repeat: the same request has the same effect
Publishes the artifact in target without sending the bytes again, optionally with stages and a comment; the caller also needs artifact.promote in the target. mode copy (default) keeps the source; move, which needs artifact.promote here as well, retires the source in the same transaction, carries its stages over and is refused with 409 when the source cannot be deleted. The answer is 201 with the copy; a repeat returns the same copy with 200, and a target that already has this package version returns that artifact when the SHA-256 matches and a 409 version_exists when it does not. Build attachments and file paths are not carried over.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
target | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
mode | string | no | one of copy, move |
stages | array of string | no | up to 16 items; no repeated items; each: matches ^[a-z0-9][a-z0-9_.-]{0,31}$ |
comment | string | no | up to 1024 characters; may be null |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
repository | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
artifactId | string (uuid) | yes | — |
sourceRepository | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
sourceArtifactId | string (uuid) | yes | — |
mode | string | yes | one of copy, move |
created | boolean | yes | — |
stages | array of string | yes | up to 16 items; no repeated items; each: matches ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Responses: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
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>"}'List artifacts with stages
GET HEAD /api/v1/repositories/{repository}/stages
Access: Repository permission: artifact.list; file keys: read · Retry: Safe to repeat (read)
Lists the stage entries of the repository (artifact, stage, time, actor, comment) ordered by artifact and stage, optionally only stage, or only the artifacts in ids (1–100 comma-separated IDs, for example to show the stages of a page of packages at once). Pages hold limit entries (1–100, default 100); continue with after set to next (<artifactId>/<stage>).
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
stage | query | string | no | matches ^[a-z0-9][a-z0-9_.-]{0,31}$ |
after | query | string | no | — |
limit | query | string | no | a whole number in decimal digits, sent as a string; At most 100. |
ids | query | string | no | up to 3699 characters; Up to 100 comma-separated artifact ids. |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | up to 100 items |
items[].artifactId | string (uuid) | yes | — |
items[].stage | string | yes | matches ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | yes | — |
items[].actor | string | yes | — |
items[].comment | string | yes | up to 1024 characters; may be null |
next | string | yes | may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Follow the promotion journal of a repository
GET HEAD /api/v1/repositories/{repository}/promotions
Access: Repository permission: artifact.list; file keys: read · Retry: Safe to repeat (read)
Returns the stage and promotion events of every artifact in the repository, oldest first, for CI/CD to poll: stage added or removed, promoted to another repository, received from one. Pages hold limit events (1–100, default 50); store the last sequence and continue with after set to next.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | query | string | no | a whole number in decimal digits, sent as a string |
limit | query | string | no | a whole number in decimal digits, sent as a string; At most 100. |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | up to 100 items |
items[].sequence | string | yes | a whole number in decimal digits, sent as a string |
items[].repository | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | yes | — |
items[].action | string | yes | one of stage.added, stage.removed, promoted, received |
items[].stage | string | yes | matches ^[a-z0-9][a-z0-9_.-]{0,31}$; may be null |
items[].mode | string | yes | one of copy, move, null; may be null |
items[].peerRepository | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$; may be null |
items[].peerArtifactId | string (uuid) | yes | may be null |
items[].actor | string | yes | — |
items[].comment | string | yes | up to 1024 characters; may be null |
items[].occurredAt | string (date-time) | yes | — |
next | string | yes | may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Resolve a package version
GET HEAD /api/v1/repositories/{repository}/packages/resolve
Access: Repository permission: package.read; file keys: read · Retry: Safe to repeat (read)
Chooses one registered UPack version by the same rules as downloadPackageContent and returns it without the bytes: version, artifact ID, SHA-256, size, publication time and current stages. name is required, group defaults to the root group; select by exact version or SemVer range, optionally stage, prerelease=true and order=promoted (needs stage); without version and range it is the highest stable version. No match is a 404; download the result by artifact ID to stay on that version.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
group | query | string | no | up to 128 characters |
name | query | string | yes | 1–128 characters |
version | query | string | no | up to 128 characters; Exact version; excludes range. |
range | query | string | no | up to 256 characters; SemVer range: 1.2.3, ^1.2, ~1.2.3, 1.x, >=1.0.0 <2.0.0, a || b. |
stage | query | string | no | matches ^[a-z0-9][a-z0-9_.-]{0,31}$; Only versions promoted to this stage. |
prerelease | query | string | no | one of true, false; Include prereleases. |
order | query | string | no | one of version, promoted; promoted picks the most recently staged version and requires stage. |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
group | string | yes | — |
name | string | yes | — |
version | string | yes | — |
artifactId | string (uuid) | yes | — |
sha256 | string | yes | SHA-256: 64 lowercase hexadecimal digits |
size | string | yes | a whole number in decimal digits, sent as a string |
publishedAt | string (date-time) | yes | — |
stagedAt | string (date-time) | yes | may be null |
stages | array of string | yes | up to 16 items; no repeated items; each: matches ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/packages/resolve?name=$NAME" \
-H "Authorization: Bearer $ARKVORY_TOKEN"