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