Jenkins Job Buidler

目录

Job Definitions

Job

参数

Job Template

Template变量的默认值

Project

Views

View Template

Macro

Folders

Item ID’s

Raw config

Defaults

Variable References

Variable Inheritance

Yaml Anchors & Aliases

Custom Yaml Tags

Action Tags

Inclusion Tags

---

Jenkins Job Builder（以下简称“JJB”）就是用来创建Jenkins任务的工具。为了简化配置大量Jenkins任务的工作量，采用更容易阅读的基于yaml或json格式的文件来编辑任务，然后使用JJB将yaml或json格式的配置转化为可以被Jenkins理解的XML格式的任务配置文件，并更新到Jenkins中。

工作原理很简单，Jenkins创建的任务实际是以XML文件的格式保存在$JENKINS_HOME/jobs/[job-name]/config.xml的，JJB能够将YAML转化为XML文件（借助Jenkins提供的命令接口），并更新到Jenkins中。

使用JJB的优点也是显而易见的：

• 无需通过前台页面来进行任务创建，方便puppet、docker等进行服务器配置管理或容器的构建；
• YAML文件作为配置可以通过版本管理工具管理起来；
• 可以通过定义job-template或参数，简化任务配置，有效减少工作量。

Job Definitions

Job

Job定义一个任务，

- job:
    name: job-name
    project-type: freestyle
    defaults: global
    description: 'Do not edit this job through the web!'
    disabled: false
    display-name: 'Fancy job name'
    concurrent: true
    workspace: /srv/build-area/job-name
    quiet-period: 5
    block-downstream: false
    block-upstream: false
    retry-count: 3
    node: NodeLabel1 || NodeLabel2
    logrotate:
      daysToKeep: 3
      numToKeep: 20
      artifactDaysToKeep: -1
      artifactNumToKeep: -1

参数

参数	意义
project-type	项目类型，默认为freestyle，具体见 modules
defaults	指定一些列公用默认值。如果Defaults的名字是“global”，那么将默认被所有的任务和任务模板使用。
description	描述
disabled	默认false
display-name	显示名称
concurrent	job是否并发执行，默认false
workspace	自定义workspace路径
folder
child-workspace	子workspace
quiet-period	一个连续2次执行之间的间隔时间（秒），默认0
block-downstream	下游任务在执行，是否阻塞。默认false
block-upstream	上游任务在执行，是否阻塞。默认false
auth-token
retry-count	checkout 重试次数
node	job可运行的节点，通过label指定。
logrotate
jdk
raw	自定义xml内容，可插入job定义中

Job Template

如果多个任务都是类似的配置，那么可以使用任务模板来定义，然后在“project”中将模板任务实现。

任务模板的语法及参数与任务定义相同，并且可以在任意地方根据需要增加变量。变量通过两个大括号定义，如{name}（在字符串中，变量最好用引号包起来；如果确实需要表示“{”和“}”字符，用“{{”和“}}”表示）。任何没有在project中定义的变量，将从Defaults中继承。

任务模板定义部分以“- job-template:”标识，通常必须包含一个{name}变量，否则所有的任务实例都采用同样的名字。任务模板不会创建任何任务。

Template变量的默认值

为了模板的重复利用，有时不需要值，这就需要为模板指定默认值。

JJB有2种方法为模板指定默认值。

1、在Job-Template中

- job-template:
    name: '{project-name}-verify'

    #####################
    # Variable Defaults #
    #####################

    branch: master

    #####################
    # Job Configuration #
    #####################

    parameters:
      - string:
          name: BRANCH
          default: '{branch}'

    scm:
      - git:
          refspec: 'refs/heads/{branch}'

上述定义了BRANCH变量的默认值为{branch},branch也是个变量，定义在job-template下。

2、使用{var|default}

- job-template:
    name: '{project-name}-verify'
    parameters:
      - string:
          name: BRANCH
          default: '{branch|master}'

    scm:
      - git:
          refspec: 'refs/heads/{branch|master}'

Project

项目用于将所有相关的任务归类（在实际使用时可以按照开发的project来分），以及给任务模板提供变量值，所以project的属性并无限制，可以定义任何模板中需要的属性。

- project:
    name: project-name         #变量定义
    jobs:
      - '{name}-unit-tests':
          mail-to: [email protected]
      - '{name}-perf-tests':
          mail-to: [email protected]

project下增加的任何属性，都定义为一个变量，都为了job Template提供变量。jobs下列举的Job Template都会应用到上面定义的变量。

如果变量的值是一个list，那么会基于list的每个元素进行实现。多个list会导致出现“笛卡尔积”个具体实现

- job-template:
    name: '{name}-{branch}'
    builders:
      - shell: 'git checkout {branch_name}'
  
- project:
    name: project-name
    branch:
     - a:
        branch_name: feature-a
     - b:
        branch_name: feature-b
    jobs:
     - '{name}-{branch}'

这样会生成“project-name-a”和“project-name-b”两个具体任务，它们在构建时分别会调用“git checkout feature-a”和“git checkout feature-b”命令。

Views

一个job集合的显示方式。

View Template

Macro

Job定义的操作，例如builders，publishers，可以定义为一个宏。

# The 'add' macro takes a 'number' parameter and will creates a
# job which prints 'Adding ' followed by the 'number' parameter:
- builder:
    name: add
    builders:
     - shell: "echo Adding {number}"

# A specialized macro 'addtwo' reusing the 'add' macro but with
# a 'number' parameter hardcoded to 'two':
- builder:
    name: addtwo
    builders:
     - add:
        number: "two"

# Glue to have Jenkins Job Builder to expand this YAML example:
- job:
    name: "testingjob"
    builders:
     # The specialized macro:
     - addtwo
     # Generic macro call with a parameter
     - add:
        number: "ZERO"
     # Generic macro called without a parameter. Never do this!
     # See below for the resulting wrong output :(
     - add

Folders

Folder层次用于jobs，views，slaves组织。

JJB支持2种上传job到某个目录的方式：

• name中指定，<folder>/my-job-name

- job:
    name: python-jobs/tox-py27
    builders:
      - shell: |
          tox -e py27

• 使用folder属性

- defaults:
    name: team1
    folder: team1-jobs

- job:
    name: ruby-jobs/rspec
    defaults: team1    # defaults参数
    builders:
      - shell: |
          rvm use --create ruby-2.3.0@rspec
          bundle install
          bundle exec rspec

Item ID’s

可以给一个代码块赋值一个id，在其他地方可以引用。

- project:
    name: test_template_id
    jobs:
        - 'simple-template':    #通过id引用
            test_var: Hello World
            type: periodic
            num: 1
        - 'not-as-simple-template':  #通过id引用 
            test_var: Goodbye World
            type: canary
            num: 2

- job-template:
    name: 'template-test-ids-{num}-{type}'
    id: simple-template
    builders:
      - shell: |
         echo "Template name: {template-name}"
         echo "Job name: template-test-ids-{num}-{type}"
         echo "{test_var}"

- job-template:
    name: 'template-test-ids-{num}-{type}'
    id: not-as-simple-template
    builders:
      - shell: |
         echo "Template name: {template-name}"
         echo "Job name: template-test-ids-{num}-{type}"
      - shell: |
         echo "{test_var}"

Raw config

wrappers:
  - raw:
      xml: |
        <hudson.plugins.xvnc.Xvnc>
          <takeScreenshot>true</takeScreenshot>
          <useXauthority>false</useXauthority>
        </hudson.plugins.xvnc.Xvnc>

Defaults

许多共性的属性或动作可以提取出来放到一个默认集合中，供其他的任务使用。

如果Defaults的名字是“global”，那么将默认被所有的任务和任务模板使用。当然在任务中也可以显式定义属性值来覆盖全局默认的属性值。

- defaults:
    name: global
    arch: 'i386'

- project:
    name: project-name
    jobs:
        - 'build-{arch}'    #使用默认属性
        - 'build-{arch}':
            arch: 'amd64'    #覆盖默认属性。

- job-template:
    name: 'build-{arch}'
    builders:
        - shell: "echo Build arch {arch}."

Variable References

可用通过{obj:key}变量把一个对象传入到模板中。

- project:
    name: test_custom_distri
    disabled: true            #定义变量
    distributions: !!python/tuple [precise, jessie]
    architectures: !!python/tuple &architectures
      - amd64
      - i386
    axis_a:
        type: user-defined
        name: architectures
        values: *architectures
    jobs:
      - '{name}-source'

- job-template:
      name: '{name}-source'
      project-type: matrix
      disabled: '{obj:disabled}'    #引用变量
      axes:
        - axis:
            type: user-defined
            name: distribution
            values: '{obj:distributions}'
        - axis: '{obj:axis_a}'

Variable Inheritance

JJB允许在不同级别为变量定义默认值。优先级如下：

1. job-group
2. project
3. job-template
4. defaults

- project:
    name: foo
    jobs:
      - '{project-name}-merge':
          branch: production   #覆盖project中变量值
      - '{project-name}-verify'

    branch: master

Yaml Anchors & Aliases

参考：https://blog.csdn.net/demon7552003/article/details/99693818

Custom Yaml Tags

Action Tags

!join:

第一个list元组作为分隔符。

- string-with-comma: !join:
    - ','
    -
        - item1
        - item2
        - item3

- string-with-space: !join:
    - ' '
    -
        - item1
        - item2
        - item3

Inclusion Tags

!include

后跟的字符串作为一个yaml文件对待。

- job:
    name: test-job-1
    builders:
      !include: include001.yaml.inc



#include001.yaml.inc 文件
- timeout-wrapper
- pre-scm-shell-ant
- copy-files

!include-raw:

对待给定的字符串或者字符串列表作为文件名称，文件内容不做任何转换（字节流）读取。

- job:
    name: test-job-include-raw-1
    builders:
      - shell:
          !include-raw: include-raw001-hello-world.sh
      - shell:
          !include-raw: include-raw001-vars.sh




#include-raw001-vars.sh  


#!/bin/bash
#
# Sample script showing how the yaml include-raw tag can be used
# to inline scripts that are maintained outside of the jenkins
# job yaml configuration.

echo "hello world"

exit 0

!include-raw-escape:

读取内容需要转义

JJB使用

配置信息

默认路径：/etc/jenkins_jobs/jenkins_jobs.ini，定义要连接的jenkins服务器

[jenkins]
user=jenkins
password=password
url=http://localhost:8081/jenkins

任务操作

测试配置

jenkins-jobs test path/to/myjob.yaml

若测试通过，将输出XML格式的任务配置，如果想将测试的XML格式的任务配置输出到文件，可以添加“-o”参数：

更新任务

jenkins-jobs [--conf jenkins_jobs.ini] update path/to/job1.yaml

删除任务

jenkins-jobs [--conf jenkins_jobs.ini] delete job1