Разделы документации

Деплои из 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

  1. Компонент. Деплой привязывается к компоненту продукта. Откройте продукт и убедитесь, что у него есть компонент (например, todo-app) и к компоненту привязан репозиторий. Репозиторий нужен для lead time и отставания от production.
  2. Окружения. Настройки → Деплои из CI → Окружения. По умолчанию заведены dev, test, stage и prod. В событии указывается ключ окружения. В DORA попадают только окружения с типом «Production».
  3. Токен. На той же странице создайте токен для 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://.

Groovy · Jenkinsfile
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:

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. Проверьте

  1. Проверьте токен с агента Jenkins: ответ покажет название токена, его продукты и ключи окружений.

    Shell
    curl -fsS "https://archepelag.example.corp/ingest-api/v1/whoami" -H "Authorization: Bearer $ARCHEPELAG_TOKEN"
  2. Запустите сборку. В её логе не должно быть ошибок curl.

  3. Откройте продукт → Окружения. В таблице «Что где развёрнуто» у компонента появится коммит в нужном окружении, а в «Истории деплоев» — строка с источником 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: его передаёт фабрика.

Shell
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»
Задание JenkinsFreestyle todo-deploy-dev с параметрами COMMIT, BRANCH, ENVIRONMENT и ARCHEPELAG_EFFECT_KEY
eventIdjenkins-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. Сборки, которые запустила фабрика, задание не отправляет: они приходят в «Окружения» от самой фабрики.

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