跳至主要內容

jenkins使用手册

ZJX2022年12月2日大约 10 分钟

简介

Jenkins 是一款使用 Java 语言开发的开源的自动化平台。我们通过界面或 Jenkinsfile 告诉它执行什么任务，何时执行。一个团队引入了 Jenkins 就像原来手工作坊式的工厂引入了生产流水线。

docker 安装 Jenkins 参考地址

安装 JDK 和 Maven

提示

因为有 docker 数据卷，将 JDK 和 Maven 安装包上传至服务器解压即可。

在 系统管理 -> 全局工具配置 中，可以指定 JDK 和 Maven 目录，为后面的构建 Java 应用程序做准备。

  • Java

    jenkins-指定jdk目录
    jenkins-指定jdk目录

  • Maven

    jenkins-指定maven目录
    jenkins-指定maven目录

配置 Git 私钥

  • 添加公钥到 Git

    提示

    注意，SSH 密钥配置完成，第一次使用时，应该手动尝试一次免密操作，原因是 SSH 有个确认连接的步骤，需要手动确认后才会成功。

    docker exec -it container_jenkins_id bash
ssh-keygen -t rsa -C "986379932@qq.com"
cat /var/jenkins_home/.ssh/id_rsa.pub
# 将公钥复制到git代码托管平台，并手动尝试免密获取代码分支信息（此操作不会下载任何代码）
git ls-remote --symref -- ssh://git@192.168.2.103:2222/root/test-jenkins.git

  • 添加私钥到 Jenkins

    在 Dashboard->系统管理->凭据->系统->全局凭据 (unrestricted)->添加凭据中输入如下内容：

    Jenkins-设置私钥
    Jenkins-设置私钥

pipeline

部署流水线（Deployment pipeline）是指从软件版本控制库到用户手中这一过程的自动化表现形式。

基本结构

一个简单的流水线基本结构，其中 agent 用于指定流水线的执行位置，流水线中的每个阶段都必须在某个地方（物理机、虚拟机或 Docker 容器）执行；

pipeline {
    agent any

    stages {
        stage('test') {
            steps {
                echo 'Testing...'
            }
        }

        stage('deploy') {
            steps {
                echo 'deploying...'
            }
        }
    }

    post {
      changed {
        echo "changed..."
      }
      always {
        echo "always..."
      }
    }
}

post 部分为附加步骤，不影响整个 pipeline 的执行

post 条件描述
always不论当前完成状态是什么，都执行
changed只要当前完成状态与上一次完成状态不同就执行
fixed上一次完成状态为失败或不稳定（unstable），当前完成状态为成功时执行。
regression上一次完成状态为成功，当前完成状态为失败、不稳定或中止（aborted）时执行。
aborted当前执行结果是中止状态时（一般为人为中止）执行
failure当前完成状态为失败时执行
success当前完成状态为成功时执行
unstable当前完成状态为不稳定时执行
cleanup在其他所有条件块执行完成后都执行

支持的指令

显然基本结构满足不了现实多变的需求，Jenkins pipeline 通过各种指令（directive）来丰富自己，Jenkins pipeline 支持的指令有：

指令描述
environment设置环境变量，可定义在 stage 或 pipeline 部分
tools可定义在 pipeline 或 stage 部分。自动下载并安装指定的工具，并将其加入 PATH 变量中。
input定义在 stage 部分，会暂停 pipeline，提示你输入内容
options用于配置 Jenkins pipeline 本身的选项，如 options {retry(3)} 指当 pipeline 失败时再重试 2 次；可定义在 stage 或 pipeline 部分
parallel并行执行多个 step；(pipeline 1.2+)
parameters执行 pipeline 前传入的一些参数
triggers用于定义执行 pipeline 的触发器(使用 cron 表达式触发)
when当满足 when 定义的条件时，阶段才执行

环境变量

内置变量

  • 示例

    pipeline {
    agent any
    stages {
        stage('test') {
            steps {
                echo '${env.BUILD_NUMBER}'
            }
        }
    }
}

  • 常用内置变量

    变量名描述
    BUILD_NUMBER构建号，累加的数字。在打包时，它可作为制品名称的一部分，比如 server-2.jar
    BRANCH_NAME分支名
    BUILD_URL当前构建的页面 URL。如果构建失败，则需要将失败的构建链接放在邮件通知中，这个链接就可以是 BUILD_URL
    GIT_BRANCH通过 git 拉取的源码构建的项目才会有此变量

自定义变量

  • 示例

    pipeline {
    agent any
    environment {
      firstName = 'Zhang'
    }
    stages {
        stage('test') {
            environment {
              lastName = 'Jx'
            }
            steps {
                echo '${firstName} - ${lastName}'
            }
        }
    }
}

触发 pipeline 执行

cron 触发

pipeline {
    agent any
    triggers {
      cron('0 0/1 * * * ')
    }
    stages {
        stage('test') {
            steps {
                echo '每分钟执行一次...'
            }
        }
    }
}
  • * * * * * 每分钟执行一次
  • */5 * * * * 每 5 分钟执行一次
  • 0 2 * * * 每天的 02:00 执行一次
  • * 2 * * * 每天 02:00 后，每分钟执行一次
  • 5 4 * * sun 每周天的 04:05 执行一次

在线 Cron 表达式生成器

upstream - 上游触发

pipeline {
    agent any
    triggers {
      upstream(upstreamProject: 'job1,job2', threshold: hudson.model.Result.SUCCESS)
    }
    stages {
        stage('test') {
            steps {
                echo 'job1和job2如果都执行成功，我就被执行...'
            }
        }
    }
}

提示

hudson.model.Result 是一个枚举，包括以下值：

枚举值说明
ABORTED任务被手动中止
FAILURE构建失败
SUCCESS构建成功
UNSTABLE存在一些错误，但不至于构建失败
NOT_BUILT在多阶段构建时，前面阶段的问题导致后面阶段无法执行

gitlab 事件触发 - 手动配置

  • 设置流水线

    为 Jenkins 下载 GitLab 插件（此插件可提供 webhook）；重启 Jenkins，新建一个名为 test-git-event 的流水线任务，在流水线配置中找到构建触发器（Build Trigger）选项，勾选如下选择框，可以看到 jenkins 会暴露一个 webhook url：

    jenkins-git提交代码触发事件
    jenkins-git提交代码触发事件

    提示

    注意，未安装 GitLab 插件将不会有此选项！

  • 保护 webhook

    为该 pipeline 生成一个 Secret token，只有带上 Secret token 的请求才会被处理方法如下：

    jenkins-保护webhook-gitlab
    jenkins-保护webhook-gitlab

  • gitlab 通知 Jenkins

    将上面得到的 webhook url 和 Secret token 复制到 gitlab 中，如图：

    提示

    gitlab 默认不允许向本地网络(192.168.xx.xx)发出请求，若 Jenkins 在本地部署，需要在 gitlab 中开启外发请求，如下：

    jenkins-gitlab-允许内网访问
    jenkins-gitlab-允许内网访问
    jenkins-为项目绑定钩子
    jenkins-为项目绑定钩子

gitlab 事件触发 - 代码配置

上面的步骤首先需要在 Jenkins 界面上手动勾选Build when a change..复选框，还需要手动单击Generate按钮生成 Secret token，这些操作也可以用代码配置：

pipeline {
    agent any
    triggers {
      gitlab(
        triggerOnPush: true,
        triggerOnMergeRequest: true,
        branchFilterType: 'All',
        secretToken: "3cd8ccdc7f9a30aead293b60e4094665"
      )
    }
    stages {
        stage('test') {
            steps {
                echo 'gitlab 触发器...'
            }
        }
    }
}
参数描述
triggerOnPush当 GitLab 触发 push 事件时，是否执行构建
triggerOnMergeRequest当 GitLab 触发 mergeRequest 事件时，是否执行构建
branchFilterType只有符合条件的分支才会被触发。必选，否则无法实现触发；可选项：NameBasedFilter（按分支名，多个用逗号隔开），RegexBasedFilter（使用正则过滤分支），All（所有分支）
secretTokenwebhook 加密 token

更多参数及用法

将构建状态信息推送到 GitLab

当 Jenkins 执行完构建后，可以将构建结果推送到 GitLab 的相应 commit 记录上，并在 gitLab 上展示构建结果，如图，构建成功会有一个绿色的勾；此操作通过访问 gitLab api 实现；

jenkins-构建信息
jenkins-构建信息

配置 gitlab 插件

在 Dashboard->系统管理->系统配置中找到 gitlab 配置项，新建一个 gitlab connection，输入 Connection Name 和 host URL；并添加 GitLab API Token 的凭证，如图：

jenkins-gitlab-插件-添加gitlab-api-token
jenkins-gitlab-插件-添加gitlab-api-token

提示

如何获取 gitlab api token？api token 用于第三方调用 api 接口，获取方式如下：

gitlab-api-token
gitlab-api-token

配置 pipeline

在 post 部分，将构建结果更新到 GitLab 的相应 commit 记录上。

注意 options 中的gitlab-local-vm参数，为上节配置 gitlab 插件中设置的 Connection Name。

pipeline {
    agent any
    triggers {
      gitlab(
        triggerOnPush: true,
        triggerOnMergeRequest: true,
        branchFilterType: 'All',
        secretToken: "3cd8ccdc7f9a30aead293b60e4094665"
      )
    }
    stages {
        stage('test') {
            steps {
                echo 'gitlab 触发器...'
            }
        }
    }
    post {
      failure {
        updateGitlabCommitStatus name: 'test', state: 'failed'
      }
      success {
        updateGitlabCommitStatus name: 'test', state: 'success'
      }
    }
    options {
      gitLabConnection('gitlab-local-vm')
    }
}

多分支 pipeline

配置

  • 设置代码仓库

    jenkins-multibranch-设置分支源
    jenkins-multibranch-设置分支源

  • 设置分支扫描触发策略

    Jenkins 根据一定的策略去扫描分支，如果有新分支就创建一个以分支名命名的任务，如果发现有分支被删除了，就删除相应的 Jenkins 任务。

    jenkins-multibranch-定时扫描分支
    jenkins-multibranch-定时扫描分支

    提示

    注意，第一次使用 SSH 免密操作扫描分支可能会失败，提示无权操作（status code 128），原因是第一次使用有个手动确认的过程； 可进入容器尝试手动获取一次分支信息，之后就不会报错了。

    # 获取分支信息（此操作不会下载任何代码）
git ls-remote --symref -- ssh://git@192.168.2.103:2222/root/test-jenkins.git

  • 孤儿任务处理策略

    在代码仓库删除分支，该分支在 Jenkins 上的任务也应该被删除；然而 Jenkins 的分支扫描不是实时的，代码仓库的分支被删除，而 jenkins 相应的任务没被删除，这个任务被称为孤儿任务；可以设置孤儿任务的历史记录保存时间：

    jenkins-multibranch-孤儿策略
    jenkins-multibranch-孤儿策略

构建配置

  • 创建 Jenkinsfile

    在项目根目录中，每个分支可创建一个 Jenkinsfile 文件，用于配置构建流水线，如下是一个简单的示例：

    when
    pipeline {
  agent any
  stages {
    stage('deploy of dev') {
      when {
        branch 'dev'
      }
      steps {
        echo "dev start..."
      }
    }
    stage('deploy of master') {
      when {
        branch 'master'
      }
      steps {
        echo "master start..."
      }
    }
  }
}

  • 识别流水线

    提交新建的 Jenkinsfile，手动触发分支扫描，在 Jenkins 上面可看到相关的流水线被自动识别：

    Jenkins-定义多分支流水线
    Jenkins-定义多分支流水线

触发多分支流水线

  • 默认

    对于多分支 pipeline，Jenkins GitLab 插件只监听 push 事件（貌似不是实时的，通过分支扫描发现有新提交才会触发），不监听 merge request 事件，可在 triggers 指令中加入 gitlab 配置： gitlab trigger 参数说明

    triggers {
  gitlab(
    triggerOnPush: true,
    triggerOnMergeRequest: true,
    branchFilterType: 'All',
    secretToken: "3cd8ccdc7f9a30aead293b60e4094665"
  )
}

  • 使用插件

    Generic Webhook Trigger 插件 能帮助我们触发某个分支的构建执行，其配置如下：

    具体整么个流程暂时还没搞明白。。。

    pipeline {
  agent any
  triggers {
    GenericTrigger(
    genericVariables: [
      [key: 'ref', value: '$.ref']
    ],
    causeString: 'Triggered on $ref',
    token: 'abc123',
    tokenCredentialId: '',
    printContributedVariables: true,
    printPostContent: true,
    silentResponse: false,
    shouldNotFlatten: false,
    regexpFilterText: '$ref',
    regexpFilterExpression: 'refs/heads/' + BRANCH_NAME
    )
  }
  stages {
    stage('Some step') {
      steps {
        sh "echo $ref"
      }
    }
  }
}

参数化 pipeline

参数化 pipeline 是指可以通过传参来决定 pipeline 的行为。

parameters 指令

  • 配置

    新增参数后至少要手动执行一次，它才会被 Jenkins 加载生效。以 pipleline-hello-word 流水线项目为例：

    pipeline {
    agent any
    parameters {
        string(defaultValue: '我是字符', description: '', name: '字符示例')
        text(defaultValue: '我可以换行\nOne\nTwo', description: '', name: '文本示例')
        choice(choices: 'dev\ntest\nprod', description: '请选择部署环境', name: '选择框')
        booleanParam(defaultValue: true, description: '', name: '布尔示例')
        password(defaultValue: '12345', description: '密码', name: '密码示例')
    }

    stages {
        stage('test') {
            steps {
                echo "Testing...: ${params.字符示例}--${params.文本示例}--${选择框}--${布尔示例}--${密码示例}"
            }
        }
    }
}

  • 构建

    手动修改传递的参数，点击如下 Bulid 按钮手动构建，可查看输出结果

    jenkins-参数化
    jenkins-参数化

另一个 pipeline 传参

对于上节的 pipleline-hello-word 流水线，我们通过手动设置参数值实现了传参的效果，也可以在其他 pipeline 中可以使用 build 步骤传参构建，如下：

pipeline {
    agent any
    stages {
        stage('test') {
            steps {
                build(
                  job: "pipleline-hello-word",
                  parameters: [
                    string(value: '我是字符', name: '字符示例')
                    text(value: '我可以换行\nOne\nTwo',  name: '文本示例')
                    string(value: 'dev', name: '选择框')
                    booleanParam(value: true,  name: '布尔示例')
                    password(value: '12345',name: '密码示例')
                  ]
                )
            }
        }
    }
}

提示

注意到 choice 类型的参数是使用 string 传参方法代替的。

最近更新：