Деплои из Jenkins
Jenkins после раскатки отправляет событие деплоя в Archepelag. Токен, окружения, шаг Jenkinsfile, проверка и пример на TODO-стенде AI Factory.
Archepelag сам ничего не раскатывает. Сборку и выкатку делает ваш Jenkins, а после выкатки отправляет в Archepelag событие: какой компонент, в какое окружение, какой коммит и чем закончилось. По этим событиям Archepelag показывает, что где развёрнуто (вкладка «Окружения» у продукта и компонента), считает отставание окружений от production и DORA-метрики.
Jenkins: сборка → выкатка ── POST /ingest-api/v1/deployments ──▶ Archepelag ──▶ «Окружения», DORA
Authorization: Bearer it_…На каждую сборку Jenkins отправляет два события: in_progress в начале выкатки и success или failed в конце. У обоих один eventId, поэтому Archepelag обновляет тот же деплой, а не создаёт второй.
1. Подготовьте Archepelag
- Компонент. Деплой привязывается к компоненту продукта. Откройте продукт и убедитесь, что у него есть компонент (например,
todo-app) и к компоненту привязан репозиторий. Репозиторий нужен для lead time и отставания от production. - Окружения. Настройки → Деплои из CI → Окружения. По умолчанию заведены
dev,test,stageиprod. В событии указывается ключ окружения. В DORA попадают только окружения с типом «Production». - Токен. На той же странице создайте токен для CI. Ограничьте его продуктами, которые раскатывает этот Jenkins. Токен
it_…показывается один раз.
2. Сохраните токен в Jenkins
Manage Jenkins → Credentials → (global) → Add Credentials:
- Kind: Secret text
- Secret: токен
it_… - ID:
archepelag-ingest-token
Не пишите токен в Jenkinsfile, параметры задания и переменные окружения агента. Оттуда он попадёт в логи и в конфигурацию задания.
3. Добавьте шаг в Jenkinsfile
Замените адрес, продукт, компонент и окружение на свои. Адрес — PUBLIC_URL Archepelag, только https://.
def reportDeployment(String status) {
withCredentials([string(credentialsId: 'archepelag-ingest-token', variable: 'ARCHEPELAG_TOKEN')]) {
def event = [
eventId : env.BUILD_TAG, // один на сборку: повтор обновляет тот же деплой
component : [product: 'AI TODO', name: 'todo-app'],
repository : env.GIT_URL,
environment: 'dev',
commitSha : env.GIT_COMMIT,
status : status, // in_progress, success, failed, rolled_back
source : 'jenkins',
url : env.BUILD_URL,
triggeredBy: env.BUILD_USER_ID ?: 'jenkins',
]
if (status != 'in_progress') event.finishedAt = new Date().format("yyyy-MM-dd'T'HH:mm:ssXXX", TimeZone.getTimeZone('UTC'))
writeFile file: 'archepelag-deployment.json', text: groovy.json.JsonOutput.toJson(event)
// Сбой отправки не роняет сборку: выкатка уже прошла, событие можно дослать повтором.
sh(script: '''curl -fsS --max-time 15 -X POST "https://archepelag.example.corp/ingest-api/v1/deployments" \
-H "Authorization: Bearer $ARCHEPELAG_TOKEN" -H "Content-Type: application/json" \
--data @archepelag-deployment.json''', returnStatus: true)
}
}
pipeline {
agent any
stages {
stage('Deploy') {
steps {
script { reportDeployment('in_progress') }
sh './deploy.sh dev' // ваша выкатка
}
}
}
post {
success { script { reportDeployment('success') } }
failure { script { reportDeployment('failed') } }
}
}- Команда
shв одинарных кавычках внутриwithCredentials: токен подставляет shell, Groovy его не видит, а Jenkins скрывает значение в логе. - Если в событии нет
GIT_COMMIT(сборка не из git), передайтеversion, например номер релиза. Нужно хотя бы одно из двух. - Компонент можно указать по id:
component: [id: '<uuid>']. Если репозиторий входит ровно в один компонент,componentможно не передавать, хватитrepository.
Готовые шаги для Jenkinsfile, GitLab CI, GitHub Actions и curl с адресом вашей установки есть на странице Настройки → Деплои из CI.
Freestyle-задание
В задании без Jenkinsfile подключите токен через Build Environment → Use secret text(s) or file(s) (плагин Credentials Binding) в переменную ARCHEPELAG_TOKEN и добавьте в начало шага Execute shell:
report() {
curl -fsS --max-time 15 -o /dev/null -X POST "https://archepelag.example.corp/ingest-api/v1/deployments" \
-H "Authorization: Bearer $ARCHEPELAG_TOKEN" -H "Content-Type: application/json" \
--data "{\"eventId\":\"$BUILD_TAG\",\"component\":{\"product\":\"AI TODO\",\"name\":\"todo-app\"},\"environment\":\"dev\",\"commitSha\":\"$COMMIT\",\"status\":\"$1\",\"source\":\"jenkins\",\"url\":\"$BUILD_URL\"}" \
|| echo "Archepelag: событие $1 не принято"
}
on_exit() { code=$?; if [ "$code" -eq 0 ]; then report success; else report failed; fi; exit "$code"; }
report in_progress
trap on_exit EXIT
# дальше — ваша выкатка4. Проверьте
-
Проверьте токен с агента Jenkins: ответ покажет название токена, его продукты и ключи окружений.
Shell curl -fsS "https://archepelag.example.corp/ingest-api/v1/whoami" -H "Authorization: Bearer $ARCHEPELAG_TOKEN" -
Запустите сборку. В её логе не должно быть ошибок
curl. -
Откройте продукт → Окружения. В таблице «Что где развёрнуто» у компонента появится коммит в нужном окружении, а в «Истории деплоев» — строка с источником
jenkins.
Если событие не принято, curl -fsS выведет код ответа:
| Ответ | Что проверить |
|---|---|
401 | Токен неверный или отозван |
403 insecure_transport | Адрес Archepelag начинается не с https:// |
403 out_of_scope | Продукт компонента не входит в область токена |
422 environment_not_found | Ключ окружения не заведён в «Деплои из CI → Окружения» |
422 component_not_found, product_not_found | Название продукта или компонента не совпадает с каталогом |
422 component_ambiguous | Репозиторий входит в несколько компонентов: передайте component |
409 event_conflict | Тот же eventId уже записан для другого компонента или окружения |
Сборки, которые запускает AI Factory
Если задание запускает AI Factory (шаг потока «Раскатка после PR»), фабрика сама записывает деплой, когда сборка закончилась. Чтобы одна сборка не дала два деплоя, пропускайте отправку, когда задан параметр ARCHEPELAG_EFFECT_KEY: его передаёт фабрика.
report() {
[ -n "${ARCHEPELAG_EFFECT_KEY:-}" ] && return 0 # сборку запустила AI Factory — деплой запишет она
# … отправка, как выше
}Пример: TODO-стенд AI Factory
Так мы настроили свой тестовый стенд. AI Factory берёт задачу из Jira и делает PR в репозиторий AIF/todo-app, а Jenkins раскатывает приложение на стенд dev. Если запустить раскатку вручную, деплой отправит сам Jenkins.
| Что | Значение |
|---|---|
| Продукт → компонент | «AI TODO» → todo-app, к компоненту привязан репозиторий AIF/todo-app |
| Окружение | dev (тип Development) |
| Токен | «Jenkins тестового стенда (todo-deploy-dev)», ограничен продуктом «AI TODO» |
| Задание Jenkins | Freestyle todo-deploy-dev с параметрами COMMIT, BRANCH, ENVIRONMENT и ARCHEPELAG_EFFECT_KEY |
eventId | jenkins-todo-deploy-dev-<номер сборки> |
Ручной запуск выглядит в логе сборки так:
Archepelag: деплой in_progress записан (jenkins-todo-deploy-dev-44, dev)
Раскатка 29406a7c… (master, задача —) на стенд todo-dev
Стенд отвечает: http://localhost:3300
Archepelag: деплой success записан (jenkins-todo-deploy-dev-44, dev)После этого в продукте «AI TODO» на вкладке «Окружения» видно todo-app в dev с коммитом 29406a7c. Сборки, которые запустила фабрика, задание не отправляет: они приходят в «Окружения» от самой фабрики.