«1. Обзор

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

В этой статье мы рассмотрим весь процесс создания расширения, которое добавляет статистику в вывод сборки, а именно количество классов и строк кода.

2. Настройка

Первое, что нужно сделать, это настроить проект. К счастью, Jenkins предоставляет для этого удобные архетипы Maven.

Просто запустите следующую команду из оболочки: 

mvn archetype:generate -Dfilter=io.jenkins.archetypes:plugin

Мы получим следующий вывод: 

[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart
  (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: remote -> io.jenkins.archetypes:empty-plugin (Skeleton of
  a Jenkins plugin with a POM and an empty source tree.)
2: remote -> io.jenkins.archetypes:global-configuration-plugin
  (Skeleton of a Jenkins plugin with a POM and an example piece
  of global configuration.)
3: remote -> io.jenkins.archetypes:hello-world-plugin
  (Skeleton of a Jenkins plugin with a POM and an example build step.)

Теперь выберите первый вариант и определите группу/артефакт/пакет в интерактивном режиме. После этого необходимо внести уточнения в файл pom.xml, так как он содержит такие записи, как \u003cname\u003eTODO Plugin\u003c/name\u003e.

3. Дизайн плагина Jenkins

3.1. Точки расширения

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

Например, каждая сборка состоит из нескольких шагов, т.е. «Checkout from VCS», «Compile», «Test», «Assemble» и т. д. Jenkins определяет точку расширения hudson.tasks.BuildStep, поэтому мы можем реализовать ее, чтобы предоставить пользовательский шаг, который можно настроить.

Другой пример — hudson.tasks.BuildWrapper — это позволяет нам определять действия до/после.

У нас также есть неосновной плагин расширения электронной почты, который определяет точку расширения hudson.plugins.emailext.plugins.RecipientProvider, которая позволяет предоставлять получателей электронной почты. Пример реализации доступен здесь: hudson.plugins.emailext.plugins.recipients.UpstreamComitterRecipientProvider.

Примечание: существует устаревший подход, при котором класс плагина должен расширять hudson.Plugin. Однако вместо этого теперь рекомендуется использовать точки расширения.

3.2. Инициализация плагина

Необходимо сообщить Дженкинсу о нашем расширении и о том, как оно должно быть создано.

Во-первых, мы определяем статический внутренний класс в плагине и помечаем его с помощью аннотации hudson.Extension: 

class MyPlugin extends BuildWrapper {
    @Extension
    public static class DescriptorImpl 
      extends BuildWrapperDescriptor {

        @Override
        public boolean isApplicable(AbstractProject<?, ?> item) {
            return true;
        }

        @Override
        public String getDisplayName() {
            return "name to show in UI";
        }
    }
}

Во-вторых, нам нужно определить конструктор, который будет использоваться для создания экземпляра объекта плагина, и пометить его аннотацией Аннотация org.kohsuke.stapler.DataBoundConstructor.

Для этого можно использовать параметры. Они отображаются в пользовательском интерфейсе и автоматически доставляются Jenkins.

Напр. рассмотрим подключаемый модуль Maven: 

@DataBoundConstructor
public Maven(
  String targets,
  String name,
  String pom,
  String properties,
  String jvmOptions,
  boolean usePrivateRepository,
  SettingsProvider settings,
  GlobalSettingsProvider globalSettings,
  boolean injectBuildVariables) { ... }

Он сопоставлен со следующим пользовательским интерфейсом:

Также можно использовать аннотацию org.kohsuke.stapler.DataBoundSetter с сеттерами.

4. Реализация плагина

Мы намерены собирать базовую статистику проекта во время сборки, поэтому hudson.tasks.BuildWrapper — правильный путь.

Давайте реализуем это: 

class ProjectStatsBuildWrapper extends BuildWrapper {

    @DataBoundConstructor
    public ProjectStatsBuildWrapper() {}

    @Override
    public Environment setUp(
      AbstractBuild build,
      Launcher launcher,
      BuildListener listener) {}

    @Extension
    public static class DescriptorImpl extends BuildWrapperDescriptor {

        @Override
        public boolean isApplicable(AbstractProject<?, ?> item) {
            return true;
        }

        @Nonnull
        @Override
        public String getDisplayName() {
            return "Construct project stats during build";
        }

    }
}

Хорошо, теперь нам нужно реализовать настоящую функциональность.

Давайте определим доменный класс для статистики проекта: 

class ProjectStats {

    private int classesNumber;
    private int linesNumber;

    // standard constructors/getters
}

И напишем код, который создает данные: 

private ProjectStats buildStats(FilePath root)
  throws IOException, InterruptedException {
 
    int classesNumber = 0;
    int linesNumber = 0;
    Stack<FilePath> toProcess = new Stack<>();
    toProcess.push(root);
    while (!toProcess.isEmpty()) {
        FilePath path = toProcess.pop();
        if (path.isDirectory()) {
            toProcess.addAll(path.list());
        } else if (path.getName().endsWith(".java")) {
            classesNumber++;
            linesNumber += countLines(path);
        }
    }
    return new ProjectStats(classesNumber, linesNumber);
}

Наконец, нам нужно показать статистику конечным пользователям. Давайте создадим для этого HTML-шаблон: 

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>$PROJECT_NAME$</title>
</head>
<body>
Project $PROJECT_NAME$:
<table border="1">
    <tr>
        <th>Classes number</th>
        <th>Lines number</th>
    </tr>
    <tr>
        <td>$CLASSES_NUMBER$</td>
        <td>$LINES_NUMBER$</td>
    </tr>
</table>
</body>
</html>

И заполним его во время сборки: 

public class ProjectStatsBuildWrapper extends BuildWrapper {
    @Override
    public Environment setUp(
      AbstractBuild build,
      Launcher launcher,
      BuildListener listener) {
        return new Environment() {
 
            @Override
            public boolean tearDown(
              AbstractBuild build, BuildListener listener)
              throws IOException, InterruptedException {
 
                ProjectStats stats = buildStats(build.getWorkspace());
                String report = generateReport(
                  build.getProject().getDisplayName(),
                  stats);
                File artifactsDir = build.getArtifactsDir();
                String path = artifactsDir.getCanonicalPath() + REPORT_TEMPLATE_PATH;
                File reportFile = new File("path");
                // write report's text to the report's file
            }
        };
    }
}

5. Использование

Пришло время объединить все, что мы уже создали, — и посмотреть. в действии.

Предполагается, что Jenkins запущен и работает в локальной среде. В противном случае см. подробности установки.

5.1. Добавьте плагин в Jenkins

Теперь давайте создадим наш плагин: 

mvn install

Это создаст файл *.hpi в целевом каталоге. Нам нужно скопировать его в каталог плагинов Jenkins (~/.jenkins/plugin по умолчанию): 

cp ./target/jenkins-hello-world.hpi ~/.jenkins/plugins/

Наконец, давайте перезапустим сервер и убедимся, что плагин применен:

  1. Open CI dashboard at http://localhost:8080
  2. Navigate to Manage Jenkins | Manage Plugins | Installed
  3. Find our plugin

5.2. Настройка задания Jenkins

Давайте создадим новое задание для проекта Apache commons-lang с открытым исходным кодом и настроим там путь к его репозиторию Git:

Для этого нам также нужно включить наш подключаемый модуль:

5.3. Проверьте результаты

Теперь все готово, давайте проверим, как это работает.

Мы можем построить проект и перейти к результатам. Мы видим, что файл stats.html доступен здесь:

Давайте откроем его:

Это то, что мы ожидали — один класс с тремя строками кода.

6. Заключение

«В этом руководстве мы создали плагин Jenkins с нуля и убедились, что он работает.

Естественно, мы не осветили все аспекты разработки расширений CI, мы лишь предоставили базовый обзор, идеи дизайна и первоначальную настройку.

И, как всегда, исходный код можно найти на GitHub.