Стадии и продвижение

Сборка идёт от CI до продакшена шагами: проверена, одобрена, выпущена. В Arkvory для этого есть два инструмента. Стадия — это отметка на сборке, например qa или release. Продвижение публикует сборку в другом репозитории без повторной отправки байтов. Используйте любой из них или оба вместе.

Стадии и репозитории

• Стадия говорит, где сборка одобрена. У сборки может быть несколько стадий, до 16. Стадии принадлежат сборке в одном репозитории. Менять их могут только операции со стадиями, и каждое изменение попадает в журнал с автором и необязательным комментарием.
• Продвижение копирует или переносит сборку из одного репозитория в другой, например из dev в staging, а затем в prod. Копия — это новый артефакт в целевом репозитории. Байты не загружаются.
• Метка — это просто свободный тег без истории. Стадия — это управляемая отметка, на которую может опираться развёртывание. См. Файлы по пути.

Имя стадии содержит от 1 до 32 символов: строчные буквы, цифры, ., _ или -; оно начинается с буквы или цифры. Сборку со стадией нельзя удалить, и правила хранения её сохраняют. Сначала снимите стадию.

Добавление и удаление стадий

В консоли откройте артефакт в разделе Свойства артефакта. Блок Продвижение показывает Стадии сборки. В поле Стадия введите имя стадии и, если хотите, в поле Комментарий (необязательно) — комментарий, затем нажмите Добавить стадию. У каждой стадии есть кнопка удаления, и консоль просит подтвердить действие: развёртывания, которые запрашивают эту стадию, выберут другую версию.

Стадии также видны в каталоге, в виде значков в каждой строке, и в столбце Стадии раздела Пакеты.

arkvoryctl stages add 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 qa --comment "smoke passed" --repository dev
arkvoryctl stages list 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 --repository dev
arkvoryctl stages remove 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 qa --repository dev
arkvoryctl stages artifacts --stage release --repository prod

stages artifacts перечисляет все сборки, у которых есть стадия, или сборки одной стадии, по 100 за раз. Передайте next как --after.

В API:

curl -X PUT "$ARKVORY/api/v1/repositories/dev/artifacts/$ID/stages/qa" \
  -H "Authorization: Bearer $ARKVORY_KEY" -H "Content-Type: application/json" \
  -d '{"comment":"smoke passed"}'
curl -X DELETE "$ARKVORY/api/v1/repositories/dev/artifacts/$ID/stages/qa" \
  -H "Authorization: Bearer $ARKVORY_KEY"

await dev.stages.add(id, 'qa', 'smoke passed');
const { items } = await prod.stages.artifacts({ stage: 'release' });

Операции: setArtifactStage, removeArtifactStage, listArtifactStages и listStagedArtifacts. Добавление уже существующей стадии ничего не меняет: время и комментарий первого добавления сохраняются. Удаление отсутствующей стадии завершается успешно. Сборка с 16 стадиями отклоняет ещё одну с ошибкой 409 stage_limit.

Продвижение в другой репозиторий

В консоли откройте артефакт. Форма Продвинуть в репозиторий появляется, когда вы можете читать сборку и продвигать её хотя бы в один другой репозиторий. В поле Целевой репозиторий выберите один из этих репозиториев. В поле Стадии в целевом репозитории введите через запятую стадии, которые нужно назначить в целевом репозитории, а в поле Комментарий (необязательно) — комментарий. Нажмите Продвинуть. Если ни один другой репозиторий этого не позволяет, консоль сообщает: Нет других репозиториев, в которые вы можете продвигать.

arkvoryctl promote 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 --repository staging --to prod --stage release --comment CAB-142
arkvoryctl promote 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 --repository staging --to prod --move

--repository — источник, --to — цель. В результате есть repository цели, новый artifactId, sourceArtifactId, mode, created и stages.

curl -X POST "$ARKVORY/api/v1/repositories/staging/artifacts/$ID/promote" \
  -H "Authorization: Bearer $ARKVORY_KEY" -H "Content-Type: application/json" \
  -d '{"target":"prod","mode":"copy","stages":["release"],"comment":"CAB-142"}'

await staging.promotions.promote(id, { target: 'prod', mode: 'copy', stages: ['release'] });

Ответ — 201 для новой копии и 200, если в целевом репозитории она уже была. Операция — promoteArtifact.

Копирование или перенос

	Копирование (по умолчанию)	Перенос
Источник	Остаётся	Удаляется в том же шаге, в котором публикуется копия
Стадии источника	Остаются на источнике	Переходят на копию, помимо стадий, которые вы задаёте
В консоли		Отметьте Перенести: убрать сборку из этого репозитория после продвижения. Консоль просит подтверждения
Блокируется, если		Источник ещё используется внешней ссылкой, путём к файлу или привязкой вложения. Ничего не публикуется

Что получает копия, а что нет:

• Она получает метки, метаданные и коллекции источника, его идентичность UPack и стадии, которые вы задаёте. Это новый артефакт с новым ID. Его SHA-256 тот же.
• Она не получает вложений и указателей путей. Привяжите их заново в целевом репозитории.
• Байты не загружаются. На одном сервере сохранённый файл остаётся общим, пока существует хотя бы один артефакт, который его использует.
• Она учитывается в квоте целевого репозитория как новая загрузка.
• Повторное продвижение возвращает ту же копию. Если в целевом репозитории уже есть пакет с той же группой, именем, версией и контрольной суммой, возвращается этот артефакт. При других байтах сервер отвечает 409 version_exists.
• Цель должна отличаться от источника. Зеркало не может быть целью, потому что оно доступно только для чтения. См. Репозитории.

Прерванное продвижение оставляет краткосрочное резервирование. Чтобы продолжить, запустите то же продвижение снова от имени той же учётной записи.

История продвижений

Страница артефакта в консоли содержит блок История: в нём сначала идут старые записи — кто добавил или убрал стадию, кто скопировал или перенёс сборку в другой репозиторий и откуда получена принятая копия. Кнопка Показать ещё загружает следующие записи.

arkvoryctl promotions history 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 --repository prod
arkvoryctl promotions journal --repository prod --after 120 --json

Журнал репозитория предназначен для CI. Опрашивайте его, передавая последний увиденный sequence как --after, и вы получите новые события по порядку. У события есть sequence, action (stage.added, stage.removed, promoted или received), stage, mode, парный репозиторий и артефакт, actor, comment и время. На странице до 100 событий. Операции: listArtifactPromotions и listRepositoryPromotions.

Выбор сборки для развёртывания

Агент развёртывания запрашивает «самую новую сборку пакета app, которая входит в диапазон ^1.4 и имеет стадию release». Arkvory отвечает ровно одной версией или 404, если подходящей нет.

arkvoryctl packages resolve app --group acme/game --range ^1.4 --stage release --repository prod --json
arkvoryctl packages download app ./app.upack --group acme/game --range ^1.4 --stage release --repository prod

resolve выводит выбор, не скачивая его:

{
  "group": "acme/game",
  "name": "app",
  "version": "1.4.7",
  "artifactId": "3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11",
  "sha256": "…",
  "size": "73400320",
  "publishedAt": "2026-10-01T09:30:00.000Z",
  "stagedAt": "2026-10-02T12:00:00.000Z",
  "stages": ["qa", "release"]
}

В HTTP resolvePackage возвращает то же самое, а downloadPackageContent отправляет байты того же выбора одним вызовом:

curl -fL -G -H "Authorization: Bearer $DEPLOY_KEY" -o app.upack \
  --data-urlencode "name=app" --data-urlencode "group=acme/game" \
  --data-urlencode "range=^1.4" --data-urlencode "stage=release" \
  "$ARKVORY/api/v1/repositories/prod/packages/content"

const found = await prod.packages.resolve({ name: 'app', range: '^1.4', stage: 'release' });

Фильтры одинаковы во всех инструментах: name пакета, group (пусто, если у пакета нет группы), точная версия или диапазон, stage, включать ли предрелизы и порядок. Диапазоны объяснены в разделе Пакеты UPack.

По умолчанию побеждает самая новая версия по SemVer. С --order promoted (order=promoted в HTTP) побеждает версия, которую отметили стадией последней, даже если её номер ниже. Для этого нужна стадия.

Имя разрешается при каждом запросе, поэтому два вызова могут вернуть разные сборки, если между ними кто-то продвинул сборку. Для скачивания, которое должно продолжаться, возьмите artifactId из resolve и скачивайте его.

Откат

С порядком promoted откат — обычный шаг. Снимите стадию с неисправной версии, и выбором станет версия, получившая стадию раньше. Чтобы снова сделать текущей более старую версию, снимите с неё стадию и добавьте ещё раз: повторное добавление стадии, которая уже есть, время не обновляет.

arkvoryctl stages remove <ID неисправного артефакта> release --repository prod
arkvoryctl packages download app ./app.upack --stage release --order promoted --repository prod

Права

Действие	Ключи: действия над репозиторием	Люди: доступ через группу
Чтение стадий и истории сборки	artifact.read	Чтение
Список сборок со стадиями и журнал	artifact.list	Чтение
Добавление или удаление стадии	artifact.promote вместе с artifact.read	Запись
Продвижение с копированием	Источник: artifact.read и content.read. Цель: artifact.promote	Чтение в источнике, запись в цели
Продвижение с переносом	То же и artifact.promote в источнике	Запись в обоих
Поиск версии	package.read	Чтение
Скачивание выбранной версии по имени	content.read	Чтение

Ключу для агента развёртывания, который только скачивает, нужен content.read в репозитории, из которого он читает. Для arkvoryctl packages download нужны также package.read и artifact.read. См. Права.

Серверы могут обмениваться сборками и сами: репозиторий может импортировать из репозитория другого сервера версии, у которых есть определённые стадии. См. Зеркала.

Связанные страницы

• Пакеты UPack и Репозитории
• Учётные записи и доступ
• Командная строка (arkvoryctl)
• Справочник API: Стадии и продвижение