流水线入门

正如 前文 提到的,Jenkins 流水线是一套插件,它支持实现和集成持续交付流水线到 Jenkins。流水线提供了一组可扩展的工具,用于通过流水线 DSL 将简单到复杂的交付流水线建模为“代码”。 [1]

本节描述了如何在 Jenkins 中开始创建你的流水线并介绍创建和存储 Jenkinsfile 的各种方式。

配置要求

为了使用 Jenkins 流水线,你需要:

  • Jenkins 2.x 或以上版本(旧版本到 1.642.3 可能可以,但不建议)

  • 流水线插件,[2] 作为“建议插件”的一部分安装(在安装 Jenkins 后,运行 Post-installation setup wizard 时指定)。

Managing Plugins 中阅读了解更多与安装和管理插件有关的信息。

定义流水线

声明式和脚本式流水线都是 DSL 语言,[1]用来描述软件交付流水线的一部分。 脚本式流水线是用一种限制形式的 Groovy 语法编写的。

本文档将根据需要介绍 Groovy 语法的相关部分,所以虽然理解 Groovy 对使用流水线有所帮助,但并不是必须的。

流水线可以通过以下任一方式来创建:

  • 通过 Blue Ocean - 在 Blue Ocean 中设置一个流水线项目后,Blue Ocean UI 会帮你编写流水线的 Jenkinsfile 文件并提交到源代码管理系统。

  • 通过经典 UI - 你可以通过经典 UI 在 Jenkins 中直接输入基本的流水线。

  • 在源码管理系统中定义 - 你可以手动编写一个 Jenkinsfile 文件,然后提交到项目的源代码管理仓库中。[3]

使用两种方式定义流水线的语法是相同的。尽管 Jenkins 支持在经典 UI 中直接进入流水线,但通常认为最好的实践是在 Jenkinsfile 文件中定义流水线,Jenkins 之后会直接从源代码管理系统加载。

通过 Blue Ocean

如果你刚接触 Jenkins 流水线,Blue Ocean UI 可以帮助你 设置流水线项目,并通过图形化流水线编辑器为你自动创建和编写流水线(即 Jenkinsfile)。

作为在 Blue Ocean 中设置流水线项目的一部分,Jenkins 给你项目的源代码管理仓库配置了一个安全的、经过身份验证的适当的连接。因此,你通过 Blue Ocean 的流水线编辑器在 Jenkinsfile 中做的任何更改都会自动的保存并提交到源代码管理系统。

了解更多 Blue Ocean 相关信息请前往 Blue Ocean 章节和 Blue Ocean 入门页面。

通过经典 UI

使用经典 UI 创建的 Jenkinsfile 由 Jenkins 自己保存(在 Jenkins 的主目录下)。

想要通过 Jenkins 经典 UI 创建一个基本流水线:

  1. 如果有要求的话,确保你已登录进 Jenkins。

  2. 从Jenkins 主页(即 Jenkins 经典 UI 的工作台),点击左上的 新建任务

    Classic UI left column

  3. 输入一个任务名称字段,填写你新建的流水线项目的名称。
    警告:Jenkins 使用这个项目名称在磁盘上创建目录。建议不要在项目名称中使用空格,因为这样做可能会触发在脚本中不能正确处理目录路径中的空格的bug。

  4. 向下滚动并点击 流水线,然后点击页面底部的 确定 打开流水线配置页(已选中 General 选项)。

    Enter a name, click <strong>Pipeline</strong> and then click <strong>OK</strong>

  5. 点击页面顶部的 流水线 选项卡让页面向下滚动到 流水线 部分。
    注意:如果你在源代码管理系统中定义了 Jenkinsfile, 请按照下面的在源码管理系统中定义的说明。

  6. 流水线 部分, 确保 定义 字段显示 Pipeline script 选项。

  7. 将你的流水线代码输入到 脚本 文本区域。
    例如,复制并粘贴下面的声明式示例流水线代码(在 Jenkinsfile ( …​ ) 标题下)或者它的脚本化的版本到 脚本 文本区域。(下面的声明式示例将在整个过程的其余部分使用。)

    Jenkinsfile (Declarative Pipeline)
    pipeline {
        agent any (1)
        stages {
            stage('Stage 1') {
                steps {
                    echo 'Hello world!' (2)
                }
            }
        }
    }
    1 agent 指示 Jenkins 为整个流水线分配一个执行器(在 Jenkins 环境中的任何可用代理/节点上)和工作区。
    2 echo 写一个简单的字符串到控制台输出。
    3 node 与上面的 agent 做了同样的事情。

    Example Pipeline in the classic UI

    注意:你也可以从 脚本 文本区域右上方的 try sample Pipeline…​ 选项选择脚本式流水线的示例。注意该区域没有可用的声明式流水线示例。

  8. 点击 保存 打开流水线项目视图页面。

  9. 在该页面, 点击左侧的 立即构建 运行流水线。

    Classic UI left column on an item

  10. 在左侧的 Build History 下面,点击 #1 来访问这个特定流水线运行的详细信息。

  11. 点击 Console Output 来查看流水线运行的全部输出。下面的输出显示你的流水线已成功运行。

    <strong>Console Output</strong> for the Pipeline

    注意:

    • 你也可以通过点击构建号左边的彩色地球仪从工作台直接访问控制台输出(例如 #1)。

    • 通过经典的 UI 定义流水线可以很方便的测试流水线代码片段,也可以处理简单的或不需要从源代码仓库中检出/克隆的流水线。正如上面提到的,和通过 Blue Ocean(上面)或在版本管理系统中(下面)定义的 ``Jenkinsfile`` 不同,在流水线项目的 脚本 文本区域输入的 ``Jenkinsfile`` 由 Jenkins 自己存储在 Jenkins 主目录下。因此,为了更好地控制和扩展你的流水线,尤其是源代码管理系统中那些复杂的项目,建议使用 Blue Ocean源码管理系统来定义你的 Jenkinsfile 文件。

在源码管理系统中

复杂的流水线很难在流水线配置页面 经典 UI脚本文本区域进行编写和维护。

为简化操作,流水线的 Jenkinsfile 可以在文本编辑器或集成开发环境(IDE)中进行编写并提交到源码管理系统 [3](可选择性地与需要 Jenkins 构建的应用程序代码放在一起)。然后 Jenkins 从源代码管理系统中检出 Jenkinsfile 文件作为流水线项目构建过程的一部分并接着执行你的流水线。

要使用来自源代码管理系统的 Jenkinsfile 文件配置流水线项目:

  1. 按照 通过经典 UI上面的步骤定义你的流水线直到第5步(在流水线配置页面访问流水线部分)。

  2. 定义 字段选择 Pipeline script from SCM 选项。

  3. SCM 字段,选择包含 Jenkinsfile 文件的仓库的源代码管理系统的类型。

  4. 填充对应仓库的源代码管理系统的字段。
    Tip: 如果你不确定给定字段应填写什么值,点击它右侧的 ? 图标以获取更多信息。

  5. 脚本路径 字段,指定你的 Jenkinsfile 文件的位置(和名称)。这个位置是 Jenkins 检出/克隆包括 Jenkinsfile 文件的仓库的位置,它应该与仓库的文件结构匹配。该字段的默认值采取名称为 "Jenkinsfile" 的 Jenkinsfile 文件并位于仓库的根路径。

当你更新指定的仓库时,只要流水线配置了版本管理系统的轮询触发器,就会触发一个新的构建。

由于流水线代码(特别是脚本式流水线)是使用类似 Groovy 的语法编写的, 如果你的IDE不能正确的使用语法高亮显示你的 Jenkinsfile,可以尝试在 Jenkinsfile 文件的顶部插入行 #!/usr/bin/env groovy 纠正这个问题。 [4] [5]

内置文档

流水线拥有内置文档的特性可以让创建各种复杂的流水线变得更容易。该内置文档基于 Jenkins 实例中安装的插件自动生成和更新。

该内置文档可以在 ``${YOUR_JENKINS_URL}/pipeline-syntax`` 全局地找到。对于任何已配置的流水线项目,这个文档也被链接到侧栏的流水线语法

Classic UI left column on an item

片段生成器

内置的“片段生成器”工具有助于为各个步骤创建代码段,发现插件提供的新步骤,或者为特定的步骤尝试不同的参数。

片段生成器由 Jenkins 实例中可用的步骤动态添加。可用的步骤的数量依赖于安装的插件,这些插件显式地公开了流水线中使用的步骤。

要使用代码生成器生成一个步骤的片段:

  1. 从已配置好的流水线导航到 流水线语法 链接(见上),或访问 ``${YOUR_JENKINS_URL}/pipeline-syntax``。

  2. 示例步骤 下拉菜单中选择需要的步骤。

  3. 使用 示例步骤 下拉菜单的动态填充区来配置已选的步骤。

  4. 点击 生成流水线脚本 生成一个能够被复制并粘贴到流水线中的流水线片段。

Snippet Generator

要访问所选步骤的附加信息和/或文档,请点击帮助图标(上图中的红色箭头所示)。

全局变量参考

对于只展示步骤的片段生成器的补充,流水线还提供了一个内置的“全局变量参考”。和片段生成器一样,它也是由插件动态添加。但和片段生成器不一样的是,全局变量参考只包含由流水线或插件提供的可用于流水线的变量文档。

流水线默认提供的变量是:

env

可以从脚本式流水线中访问的环境变量,例如: env.PATHenv.BUILD_ID。 访问内置的全局变量参考页面 ${YOUR_JENKINS_URL}/pipeline-syntax/globals 以获取完整的,最新的,可用于流水线的环境变量列表。

params

将为流水线定义的所有参数作为 Map,例如:params.MY_PARAM_NAME

currentBuild

可用于发现当前正在执行的流水线的信息, 比如 currentBuild.resultcurrentBuild.displayName 等属性。参考内置的全局变量参考页面 ${YOUR_JENKINS_URL}/pipeline-syntax/globals 以获取完整的,最新的,currentBuild 的属性列表。

声明式指令生成器

片段生成器可以帮助生成脚本式流水线的步骤或者声明式流水线的 stage 中的 steps 代码块,但是其并没有包含用于定义声明式流水线的 section(节段)directive(指令)。声明式指令生成器(Declarative Directive Generator)这个工具可以做到这点。和 片段生成器类似,指令生成器允许你选择声明式的指令,对其以一种方式进行配置,然后生成这个指令的配置,让你将其用于声明式流水线。

要使用声明式指令生成器生成一个声明式的指令:

  1. 从已配置好的流水线导航到 Pipeline Syntax/流水线语法 链接(见上),然后点击侧栏的 Declarative Directive Generator,或直接访问 ``${YOUR_JENKINS_URL}/directive-generator``。

  2. 在下拉菜单中选择需要的指令。

  3. 使用下拉菜单下面动态生成的区域配置已选的指令。

  4. 点击 Generate Declarative Directive 生成一个能够被复制到流水线中的指令配置。

指令生成器可以生成嵌套的指令配置,比如在 when 指令内的条件,但是它不能生成流水线步骤。对于包含步骤的指令内容,比如 stage 内的 stepspost 内的条件如 alwaysfailure,指令生成器添加一个占位符注释。你仍然需要手动添加步骤到流水线中。

Jenkinsfile (Declarative Pipeline)
stage('Stage 1') {
    steps {
        // One or more steps need to be included within the steps block.
    }
}

延伸阅读

本节仅仅介绍了 Jenkins 流水线可以做的事情的皮毛,但是应该为你开始测试 Jenkins 实例提供了足够的基础。

在下一节中,使用 Jenkinsfile,会讨论更多的流水线步骤以及实现成功的,真实世界的 Jenkins 流水线模式。

其它资源



反馈修改意见?

如果对此页的内容有修改意见,请通过下面的快速表格 快速表单反馈.

或者,你不想填表单,只需填写你要反馈的内容

    


看已有的反馈 这里.