Миграция Jenkins на Java 21: обновление узлов Mac в 2026

Что именно меняется при переходе на Java 21

Согласно официальной политике Java для Jenkins, начиная с LTS 2.555.1 контроллер и Agent JVM должны использовать Java 21 или Java 25. Это не означает, что каждый проект обязан компилироваться на той же версии Java: Jenkins отдельно указывает, что JVM агента и JDK, используемый сборкой, можно управлять независимо через инструменты и настройки задания. Политика поддержки Java в Jenkins и руководство по обновлению Jenkins 2.555 должны быть исходной точкой для плана.

В типичной Mac-инфраструктуре одновременно существуют четыре разных слоя:

Главная ошибка миграции — заменить Java на Mac, а затем считать задачу завершённой, потому что узел появился в интерфейсе Jenkins. Онлайн-статус подтверждает только наличие соединения в данный момент. Он не доказывает, что узел переживёт перезапуск хоста, повторное подключение, очистку рабочего каталога или полный Pipeline с подписью.

Вторая проблема связана с плагинами. Core Jenkins может запуститься после изменения JVM, но отдельный плагин для Pipeline, учётных данных, аутентификации или мониторинга узлов способен иметь собственные ограничения. Например, плагин Versions Node Monitors добавляет отображение версий на узлах, однако его наличие не заменяет проверку фактической JVM и поведения заданий.

Третья скрытая стоимость — отсутствие однозначного отката. Если одновременно обновить контроллер, Java Agent, плагины и Xcode, при сбое будет трудно определить, какой слой нарушил работу. Поэтому до начала окна изменений сохраняются не только файлы конфигурации Jenkins, но и параметры запуска агентов, метки, переменные окружения, маршрутизация заданий и версия JDK, выбранная каждым критичным Pipeline.

До окна изменений: инвентаризация и исходная точка

За несколько рабочих дней до миграции формируется таблица активов. В неё входят контроллер Jenkins, все Mac Agent, их метки, способ подключения, версия macOS, Xcode, JVM агента и назначение узла. Узел, который используется для подписи или публикации, нельзя считать обычным исполнителем: для него нужны отдельные условия допуска и отдельный сценарий возврата.

На контроллере фиксируются:

• текущая версия Jenkins и целевая LTS-версия;
• JVM контроллера и параметры её запуска;
• плагины ядра, Pipeline, аутентификации, учётных данных и управления узлами;
• резервная копия конфигурации и перечень заданий, привязанных к Mac-меткам;
• порядок остановки, восстановления и проверки контроллера.

На каждом Mac Agent фиксируются:

• версия Java, которой фактически запускается агент;
• команда или сервис автозапуска;
• адрес контроллера, идентификатор узла и метки;
• версия Xcode и путь к инструментам командной строки;
• доступ к рабочему каталогу, Keychain и сертификатам;
• задания, которые разрешено выполнять на этом узле.

Минимальная проверка версии на Mac может выглядеть так:

echo "$JAVA_HOME"
"$JAVA_HOME/bin/java" -version
xcodebuild -version

Команда не доказывает совместимость всей цепочки, но помогает обнаружить распространённую ошибку: оболочка показывает одну Java, а служба агента запущена с другим путём. Для проверки инструментов Xcode следует сверяться с официальным справочником Xcode Command Line Tools, а не только с результатом графического запуска Xcode.

План миграции по контрольным точкам

Миграция Jenkins Java 21 должна идти как последовательность разрешений на следующий этап, а не как одно большое обновление. Для каждой группы узлов заранее задаются критерии остановки.

Шаг 1. Создайте базовую копию состояния

Сохраните конфигурацию контроллера, список плагинов и параметры каждого Mac Agent. Отдельно экспортируйте сведения о метках и маршрутах: без них после отката Jenkins может начать отправлять задание на узел с неподходящей версией Xcode или сертификатами.

Резервная копия должна отвечать на три разных вопроса:

1. как вернуть прежнюю версию контроллера;
2. как запустить Agent JVM старым способом;
3. как временно запретить заданиям использовать изменённый узел.

Такой раздельный план лучше полного отката вслепую. Документация Jenkins по управлению узлами описывает операции подключения и управления узлами, но конкретные параметры автозапуска и восстановления зависят от конфигурации Mac.

Шаг 2. Проверьте целевую Java и плагины

Для Jenkins LTS 2.555.1 целевой JVM контроллера и агента выбирается из поддерживаемых Java 21 или Java 25. В этой статье рассматривается Java 21, поскольку она должна быть проверена отдельно на контроллере, Mac Agent и в системных службах.

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

• запуск Pipeline;
• получение исходного кода;
• доступ к учётным данным;
• распределение заданий по Mac-меткам;
• публикация артефактов и отчётов.

Официальный журнал изменений LTS и руководство обновления нужно сопоставить с фактически установленными версиями. Проверка только кнопки «обновить всё» не подходит для производственного окна: она скрывает причинность и усложняет возврат.

Шаг 3. Переведите один Mac Agent

На изолированном Mac установите поддерживаемую Java 21 и укажите её непосредственно в запуске агента. Вариант с переменной окружения:

export JAVA_HOME="/путь/к/java-21"
"$JAVA_HOME/bin/java" -version

В реальной службе путь должен быть задан там, где запускается Agent, а не только в интерактивном профиле пользователя. Если агент стартует через службу, графический сеанс или отдельный скрипт, проверяйте именно этот контекст.

После запуска проверьте:

• появление узла в Jenkins;
• версию JVM в информации узла;
• выполнение простого задания;
• отключение и повторное подключение;
• перезапуск Mac и автоматическое возвращение агента;
• отсутствие изменения меток и переменных окружения.

Подробные варианты подключения и работы агентов описаны в официальной документации Jenkins по Agent. Команду запуска не следует усложнять дополнительными переключателями, пока базовое подключение не подтверждено.

Шаг 4. Запустите настоящую Xcode-сборку

Проверка должна включать не только java -version, но и репрезентативный Pipeline:

1. получение исходного кода;
2. восстановление зависимостей;
3. сборку Xcode;
4. запуск тестов;
5. подготовку или загрузку артефакта.

На пилотном узле лучше использовать непроизводственную задачу и тестовые либо ограниченные учётные данные. Подпись выпуска переводится на этот узел только после подтверждения доступа к Keychain и корректного разделения секретов. Правила создания подписанного кода следует сопоставить с документацией Apple по подписи.

Если старый проект требует отдельный JDK, его нужно выбрать в Pipeline явно. Например, логика может выглядеть так:

withEnv(["JAVA_HOME=${tool 'project-jdk'}"]) {
    sh 'java -version'
    sh './build-script'
}

Название инструмента здесь условное и должно соответствовать конфигурации Jenkins. Смысл проверки — убедиться, что после перехода JVM агента на Java 21 проект действительно запускается на назначенном JDK, а не случайно наследует системное окружение.

Шаг 5. Обновите контроллер и сохраните двойную маршрутизацию

Контроллер обновляется только после успешного пилота. В окне изменений сначала переводится контроллер на поддерживаемую JVM и целевую LTS, затем проверяется загрузка Jenkins, плагины, учётные данные и видимость пилотного узла.

Немигрированные узлы сохраняются под отдельными метками либо временно исключаются из маршрутизации. Это необходимо, потому что контроллер уже может требовать Java 21 или Java 25, тогда как старый Agent JVM ещё не готов к новому условию. Нельзя допускать автоматический выбор узла только потому, что он свободен.

Поэтапный перевод Mac-узлов и откат

После контроллера сначала переводятся задания, которые не создают производственный релиз: тесты, сборка промежуточных артефактов и статический анализ. Затем подключаются архивирование и задачи подписи. Такой порядок снижает риск того, что проблема JVM будет обнаружена одновременно с ошибкой сертификата.

Для каждой очереди назначаются:

• список Mac Agent с одинаковой базовой конфигурацией;
• набор заданий для проверки;
• владелец решения о продолжении;
• время наблюдения после перевода;
• точный способ остановки маршрутизации;
• версия и команда возврата.

Сигналом готовности к следующей очереди является не один успешный запуск, а повторяемая последовательность: обычное задание, переподключение, перезапуск Mac, повторная сборка и проверка журналов. Точные показатели времени восстановления или производительности нельзя объявлять универсальными без измерений конкретной инфраструктуры.

Контроль первой недели после перехода

В течение первой недели после миграции команда отслеживает не только красные сборки, но и причины отключений Mac Agent. Ошибка соединения, неверный JDK, сбой плагина, отсутствие Keychain-доступа и повреждённый рабочий каталог требуют разных исправлений.

В базовый профиль успешно переведённого узла стоит записать:

• версию JVM Agent;
• команду или службу запуска;
• версию macOS и Xcode;
• набор меток;
• разрешённые задания;
• способ выбора JDK проекта;
• правила работы с сертификатами;
• проверенный сценарий перезапуска и отката.

Так формируется не разовая инструкция, а критерий допуска для следующего Mac. Если в текущем парке нет свободного узла для пилота или параллельного маршрута, временный удалённый Mac может быть оправдан как изолированный ресурс для проверки. При выборе такого варианта нужно заранее оценить возможности удалённого Mac для командной работы, способ доступа и процедуру восстановления.

Подробности об окружении и доступных операциях разумно сверить через справочный центр NodeMini, но параметры конкретной аренды не должны подменять технический план миграции. Узел имеет смысл добавлять только тогда, когда он действительно предоставляет отдельный маршрут для пилота, а не создаёт ещё одну общую точку отказа.

Итоговая проверка перед расширением

• [ ] Зафиксированы версии контроллера, плагинов, JVM, Xcode и проектных JDK.
• [ ] Сохранены параметры запуска всех Mac Agent и их метки.
• [ ] Проверена целевая Java по официальной политике Jenkins.
• [ ] Один изолированный Mac зарегистрировался на Java 21.
• [ ] Подтверждены отключение, переподключение и автоматический запуск после перезагрузки.
• [ ] Реальный Pipeline прошёл получение исходников, сборку и тесты Xcode.
• [ ] Подпись проверена отдельно от базового соединения Agent.
• [ ] Старый JDK проекта не зависит от JVM агента.
• [ ] Для каждой очереди определены критерии остановки и возврата.
• [ ] Есть отдельный ресурс или подтверждённая процедура, позволяющая не тестировать на единственном производственном Mac.

Частые вопросы перед миграцией

Нужно ли сначала обновлять Agent перед переходом Jenkins на Java 21?

В корпоративной среде безопаснее сначала выбрать изолированный Mac Agent и перевести его JVM на Java 21. После этого проверяются регистрация, переподключение, перезапуск и реальная Xcode-сборка. Контроллер обновляется только после успешного пилота. Исключение возможно лишь при заранее проверенной совместимой схеме, но рассчитывать на неё без тестового узла рискованно.

Как указать Java 21 для Jenkins Agent на Mac?

Java 21 указывается в контексте запуска самого Agent: через JAVA_HOME или явный путь к исполняемому файлу Java. Настройка интерактивного профиля пользователя не гарантирует изменение службы автозапуска. После перезапуска нужно проверить версию JVM в информации узла Jenkins и сравнить её с результатом java -version из фактического процесса запуска.

Сможет ли Agent на Java 21 собирать старый проект на другой Java?

Сможет, если проектный JDK установлен отдельно и Pipeline выбирает его явно. JVM агента отвечает за работу Agent и соединение с контроллером, а не автоматически за компиляцию приложения. Для старого проекта следует проверить JAVA_HOME, настройку Jenkins Tool и команду сборки в логах. Иначе проект может незаметно использовать системную Java.

Как откатить Mac Agent, если после обновления Jenkins он отключился?

Сначала остановите выдачу новых заданий на узел и определите слой сбоя: контроллер, Agent JVM, параметры запуска, плагин или окружение проекта. Затем верните только подтверждённо неисправный объект, используя сохранённые параметры, метки и резервную копию. Полный одновременный откат контроллера, Java и Pipeline усложняет диагностику и может затронуть уже работающие узлы.

Как перевести несколько Mac Agent на Java 21 без остановки CI/CD?

Сгруппируйте узлы по версиям macOS, Xcode, способу запуска и назначению. Сначала переведите один изолированный узел, затем задания без публикации, после этого — архивирование и подпись. Каждую следующую группу запускайте только после проверки реальной сборки, перезапуска, переподключения и готового возврата. Непроверенные узлы не должны оставаться в общей производственной метке.

Текущая схема с единственным физическим Mac или с ручным подключением узлов часто выглядит дешевле, но у неё есть минимум три слабых места: отсутствует безопасный пилотный контур, перезапуск зависит от доступности конкретной машины, а временное расширение под окно Jenkins требует срочной закупки и последующего обслуживания. Поэтому, если собственный парк не позволяет остановить единственный производственный Mac, аренда удалённого Mac в NodeMini может быть более рациональным способом добавить отдельный узел для Java 21, проверить Xcode Pipeline и сохранить возможность быстрого отката. После успешной миграции такой ресурс можно отключить, оставить как резервный или использовать для следующего этапа расширения; параметры заказа доступны на странице аренды Mac в NodeMini.