Сразу о версиях, чтобы не строить на песке. На середину 2026 актуальная ветка - Jenkins LTS 2.555.1, которая требует уже Java 21 или Java 25 (поддержка Java 17 в этой линейке закончилась). Если у тебя более старый контроллер - команды ниже всё равно работают, API стабилен годами, но держи в голове, что Jenkins живёт по плану "2+2+2" и старую Java рано или поздно выкинут.
Три способа управлять Jenkins программно
Разложим по полочкам, чтобы не путаться, какой инструмент когда брать.
- Jenkins CLI - утилита командной строки. Удобна для скриптов на сервере и разовых административных команд: запустить джобу, перезагрузить конфиг, поставить контроллер в режим обслуживания. Работает поверх HTTP или SSH.
- REST API - HTTP-интерфейс. Это основной мост для интеграций: получить статус сборки в JSON, триггернуть пайплайн из внешней системы, выгрузить список джоб. Любой язык, у которого есть HTTP-клиент, умеет говорить с Jenkins.
- Script Console - выполнение Groovy прямо на контроллере. Самый мощный и самый опасный инструмент: ты получаешь полный доступ к внутренностям Jenkins. Для админки и точечных операций, которые больше никак не сделать.
Jenkins CLI: запуск джоб и управление
Исторически jenkins-cli.jar работал через так называемый remoting-режим. Забудь про него: из-за дыр в безопасности remoting-транспорт выпилили ещё в Jenkins 2.165. Сегодня клиент использует HTTP (по умолчанию), SSH или WebSocket. Это важная актуализация по сравнению со старыми книгами и статьями, где remoting ещё фигурирует.
Сначала качаем клиент прямо с твоего контроллера и смотрим список доступных команд:
Код: Выделить всё
# скачиваем клиент с самого Jenkins
curl -sO http://jenkins.example.com:8080/jnlpJars/jenkins-cli.jar
# список всех команд (через HTTP-транспорт, он по умолчанию)
java -jar jenkins-cli.jar -s http://jenkins.example.com:8080/ \
-auth admin:11aabbccddeeff00112233445566778899 help
Код: Выделить всё
# запустить джобу, дождаться окончания, прокинуть параметры
java -jar jenkins-cli.jar -s http://jenkins.example.com:8080/ \
-auth admin:11aabbccddeeff00112233445566778899 \
build my-deploy-job -f -v \
-p ENV=staging -p VERSION=1.4.2
Код: Выделить всё
# перечитать конфигурацию с диска (после ручной правки XML)
java -jar jenkins-cli.jar -s http://jenkins.example.com:8080/ \
-auth admin:TOKEN reload-configuration
# мягко перезапустить - дождётся завершения текущих сборок
java -jar jenkins-cli.jar -s http://jenkins.example.com:8080/ \
-auth admin:TOKEN safe-restart
Вот где живёт вся интеграция. Главная фишка Jenkins REST API в том, что почти к любому URL веб-интерфейса можно добавить суффикс и получить машиночитаемый ответ: /api/json, /api/xml или /api/python. Хочешь статус последней сборки джобы - вот он:
Код: Выделить всё
# статус последней сборки в JSON, ?pretty для читаемости
curl -s -u admin:TOKEN \
"http://jenkins.example.com:8080/job/my-deploy-job/lastBuild/api/json?pretty=true"
Код: Выделить всё
# только нужные поля - быстрее и легче
curl -s -u admin:TOKEN \
"http://jenkins.example.com:8080/job/my-deploy-job/lastBuild/api/json?tree=number,result,building"
Код: Выделить всё
JENKINS=http://jenkins.example.com:8080
CRED="admin:11aabbccddeeff00112233445566778899"
# 1. достаём crumb и имя его заголовка одним запросом
CRUMB=$(curl -s -u "$CRED" \
"$JENKINS/crumbIssuer/api/json" | \
python3 -c 'import sys,json; d=json.load(sys.stdin); print(d["crumbRequestField"]+":"+d["crumb"])')
# 2. триггерим параметризованную джобу, передав crumb заголовком
curl -s -X POST -u "$CRED" -H "$CRUMB" \
"$JENKINS/job/my-deploy-job/buildWithParameters?ENV=prod&VERSION=1.4.2"
Script Console: Groovy на контроллере - мощно и опасно
Script console (Manage Jenkins -> Script Console, либо POST на /scriptText) выполняет Groovy-код в JVM самого контроллера, с полными правами. Это администраторский скальпель: им делают то, чего нет ни в UI, ни в CLI. Массово перебрать джобы, починить зависшие сборки, выгрузить отчёт по плагинам. Простой пример - найти все джобы, у которых последняя сборка упала:
Код: Выделить всё
// перебрать все джобы и вывести упавшие
Jenkins.instance.getAllItems(hudson.model.Job).each { job ->
def b = job.getLastBuild()
if (b && b.getResult()?.toString() == 'FAILURE') {
println "FAILED: ${job.fullName} -> ${b.number}"
}
}
Код: Выделить всё
curl -s -X POST -u admin:TOKEN -H "$CRUMB" \
--data-urlencode "script=println Jenkins.instance.getVersion()" \
http://jenkins.example.com:8080/scriptText
Безопасность доступа к API: чек-лист
Программный доступ - это всегда расширение поверхности атаки. Минимум, который надо закрыть:
- Только API-токены, никаких паролей в скриптах и переменных окружения CI. Токен легко отозвать, не меняя пароль.
- Не выключай CSRF-защиту "чтобы заработало". Это совет из старых форумов 2018 года, сегодня он вредный - научись доставать crumb или ходи по токену.
- Раздавай права по матрице (Matrix Authorization): сервисному пользователю для триггера джобы хватит Job/Build и Job/Read, а не админских прав.
- Только HTTPS. Токен в URL или заголовке по голому HTTP - это утечка, ждущая своего часа.
- Доступ к script console - отдельная привилегия Overall/RunScripts, выдавай поштучно.
Стоит честно сказать, на фоне чего ты это изучаешь. У GitLab CI и GitHub Actions модель управления pipeline другая: конфиг лежит в репозитории как YAML, а API и так первоклассны и заложены в продукт изначально. У Jenkins исторически наоборот - сначала UI и плагины, API наслаивался сверху, отсюда и зоопарк из трёх способов. Зато этот зоопарк даёт гибкость, которой у конкурентов нет: script console позволяет влезть в живой контроллер так глубоко, как ни одна managed-платформа не разрешит. А связка JCasC (Configuration as Code) плюс эфемерные агенты в Kubernetes плюс REST API превращает старичка Jenkins во вполне современный, полностью описанный кодом сервер. Blue Ocean при этом считай наследием - проект давно заброшен, строить на нём автоматизацию не нужно.
Мини-лаба
Подними локальный Jenkins (хоть в Docker), создай тестовую параметризованную джобу с параметрами ENV и VERSION и прогони руками всю цепочку:
- Скачай jenkins-cli.jar с /jnlpJars/ и запусти джобу командой build с -f и -p.
- Выпусти себе API-токен в профиле и забери статус lastBuild через REST API с ?tree=number,result.
- Достань crumb из /crumbIssuer/api/json и триггерни джобу через POST на /buildWithParameters.
- Повтори триггер, но по API-токену и БЕЗ crumb - убедись, что Jenkins пропускает запрос.
- В script console напиши Groovy, который выведет версию Jenkins и список упавших джоб.
- Какой транспорт CLI убрали из Jenkins по соображениям безопасности и какие остались?
- Зачем нужен crumb при триггере джобы и в каком случае его можно не запрашивать?
- Чем script console принципиально опаснее REST API и кому давать к ней доступ?
- Какой параметр REST API позволяет вытащить из JSON только нужные поля и не качать лишнее?
Три инструмента - три задачи. CLI - для скриптов и админских команд на хосте, REST API - для интеграций и триггеров снаружи (помни про crumb или ходи по токену), script console - для редкой глубокой хирургии под строгим контролем доступа. Освой их, и ручной клик по UI останется в прошлом, а Jenkins CI впишется в любую автоматизацию, какую ты придумаешь.
