Основные команды Jenkins CLI для управления задачами

Jenkins CLI помогает управлять задачами, когда веб-интерфейс слишком медленный для повторяющейся работы. Если вам нужно создавать задачи из шаблонов, запускать сборки или обновлять XML-конфигурацию в скриптах, CLI предоставляет прямой путь.

Это руководство сосредоточено на командах управления задачами: list-jobs, get-job, create-job, copy-job, update-job, delete-job и build.

Настройка Jenkins CLI

Перед выполнением любых команд необходимо установить безопасное соединение с вашим мастером Jenkins. Это включает загрузку клиента CLI и обеспечение правильной аутентификации.

1. Загрузка jenkins-cli.jar

Клиент CLI обычно находится непосредственно на вашем сервере Jenkins по определенному адресу. Вы можете загрузить его с помощью wget или curl:

wget http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar
# ИЛИ с помощью curl
curl -O http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar

2. Методы аутентификации

Подключения Jenkins CLI требуют аутентификации. Наиболее безопасный и рекомендуемый метод — использование API-токена вместо обычного пароля пользователя.

Чтобы сгенерировать API-токен, перейдите в Настройки пользователя > Настройки > API-токен в веб-интерфейсе Jenkins.

Все последующие команды будут требовать флаги аутентификации, обычно с использованием флагов -s (URL сервера) и -auth (учетные данные аутентификации):

java -jar jenkins-cli.jar -s http://your-jenkins-url:8080 -auth USERNAME:API_TOKEN <команда>

Совет: Для безопасности храните ваш API-токен в защищенной переменной окружения или используйте метод аутентификации с SSH-ключом, если он настроен, вместо того чтобы вводить его напрямую в скрипты.

Основные команды для поиска задач

Перед изменением задач часто необходимо перечислить существующие задачи и получить их конфигурации.

Перечисление всех задач: list-jobs

Эта команда отображает имена всех задач, настроенных на мастере Jenkins.

java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH list-jobs

Получение конфигурации задачи: get-job

Задачи Jenkins определяются XML-файлами конфигурации. Команда get-job позволяет получить это XML-определение, что необходимо для создания новых задач на основе шаблонов.

# Получить конфигурацию для 'my-template-job' и сохранить в файл
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH get-job my-template-job > template-config.xml

Основные команды управления задачами

Эти команды обрабатывают основные операции жизненного цикла задач Jenkins.

1. Создание новой задачи: create-job

Команда create-job требует имя новой задачи и XML-файл конфигурации, определяющий ее параметры, шаги сборки и триггеры.

Предварительные требования: Сначала у вас должен быть действительный XML-файл конфигурации (например, new-config.xml), обычно полученный путем изменения шаблона, извлеченного с помощью get-job.

# Пример: Создать новую задачу с именем 'project-feature-branch' с использованием локального XML-файла
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH create-job project-feature-branch < new-config.xml

2. Копирование существующей задачи: copy-job

Это часто самый быстрый способ создать новую задачу, используя существующую задачу в качестве шаблона и применяя новое имя. Эта команда эффективно дублирует конфигурацию исходной задачи.

# Синтаксис: copy-job SOURCE_JOB_NAME DESTINATION_JOB_NAME
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH copy-job original-pipeline new-dev-pipeline

3. Включение и отключение задач: enable-job и disable-job

Эти команды важны для обслуживания, временных остановок или административного контроля, предотвращая или разрешая запуск сборок.

# Команда для остановки дальнейших запланированных или запущенных сборок для обслуживания
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH disable-job legacy-project-build

# Команда для повторной активации задачи
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH enable-job legacy-project-build

4. Удаление задачи: delete-job

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

# Окончательное удаление задачи
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH delete-job obsolete-test-job

Предупреждение: Команда delete-job выполняется немедленно без дополнительного подтверждения в среде CLI. Убедитесь, что ваши скрипты включают правильные шаги проверки перед выполнением этой команды.

Запуск и мониторинг сборок

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

Запуск сборки: build

Команда build запускает новую сборку для указанной задачи. Если задача параметризована, вы можете передать аргументы напрямую с помощью флага -p.

# Запустить простую, непараметризованную сборку
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build nightly-deploy

# Запустить параметризованную задачу, передавая параметры
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build integration-test -p TARGET_ENV=staging -p BRANCH_NAME=hotfix-123

Примечание: Если вы используете флаг -s с build, CLI будет ждать завершения сборки и сообщит код выхода. В противном случае команда возвращается сразу после постановки сборки в очередь.

Просмотр статуса сборки: get-job и console

Хотя CLI не предлагает потоковую передачу в реальном времени, сравнимую с веб-интерфейсом, вы можете проверить статус задачи и получить вывод консоли.

Чтобы просмотреть вывод консоли для определенного номера сборки:

# Получить вывод консоли для сборки #55 задачи 'my-job'
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH console my-job 55

Лучшие практики для написания скриптов CLI

Эффективное использование Jenkins CLI требует принятия определенных лучших практик для стабильности и безопасности:

1. Скриптинг и автоматизация

CLI наиболее полезен в shell-скриптах. Используйте get-job, тщательно изменяйте полученный XML, а затем передавайте измененную конфигурацию обратно с помощью create-job или update-job.

Пример рабочего процесса (Копирование, изменение и создание):

1. Получить шаблон: get-job template-job > tmp.xml
2. Используйте sed для замены заполнителей (например, имя проекта, URL репозитория) в tmp.xml.
3. Создать новую задачу: create-job new-job < tmp.xml

2. Обработка обновлений конфигурации

Чтобы обновить конфигурацию существующей задачи с помощью XML из стандартного ввода, используйте update-job. Это безопаснее, чем удаление и повторное создание задачи, так как сохраняет историю сборок.

# Обновить 'project-a' с использованием локально измененного файла конфигурации
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH update-job project-a < updated-config.xml

3. Обработка ошибок

Всегда проверяйте код выхода ($?) после выполнения команды CLI в ваших скриптах. Код возврата 0 указывает на успех; любой ненулевой код сигнализирует об ошибке. Это важно для надежной автоматизации и отладки.

Ключевой вывод

Jenkins CLI — это практичный инструмент для повторяющегося администрирования задач. Начните с экспорта XML задачи с помощью get-job, вносите контролируемые изменения, обновляйте задачи с помощью update-job и запускайте сборки с помощью build. Храните API-токены вне скриптов и проверяйте разрушительные команды, такие как delete-job, перед их выполнением.