Getting Started with Pipeline 学习Pipeline

Overview

Audience and Purpose

This document is intended for novice users of the Jenkins pipeline feature. The document explains what a pipeline is,why that matters,and how to create the different kinds of pipelines.

本文档面向Jenkins管道特性的新手。 该文档解释了什么是管道，为什么重要，以及如何创建不同类型的管道。

Why Pipeline?

While standard Jenkins "freestyle" jobs support simple continuous integration by allowing you to define sequential tasks in an application lifecycle,they do not create a record of execution that persists through any planned or unplanned restarts,enable one script to address all the steps in a complex workflow,or confer the other advantages of pipelines.

虽然标准的Jenkins“自由式”作业通过允许在应用程序生命周期中定义顺序任务来支持简单的持续集成，但它们不会创建通过任何计划或计划外重新启动持续执行的记录，使一个脚本能够处理所有步骤 复杂的工作流程，或赋予管道的其他优点。

In contrast to freestyle jobs,pipelines enable you to define the whole application lifecycle. Pipeline functionality helps Jenkins to support continuous delivery (CD). The Pipeline plugin was built with requirements for a flexible,extensible,and script-based CD workflow capability in mind.

与自由式工作相反，管道使您能够定义整个应用程序生命周期。 管道功能帮助Jenkins支持连续交付（CD）。 Pipeline插件构建时考虑了灵活，可扩展和基于脚本的CD工作流功能的要求。

Accordingly,pipeline functionality is:

• Durable: Pipelines can survive both planned and unplanned restarts of your Jenkins master.

• Pausable: Pipelines can optionally stop and wait for human input or approval before completing the jobs for which they were built.

• Versatile: Pipelines support complex real-world CD requirements,including the ability to fork or join,loop,and work in parallel with each other.

• Extensible: The Pipeline plugin supports custom extensions to its DSL (domain scripting language) and multiple options for integration with other plugins.

The flowchart below is an example of one continuous delivery scenario enabled by the Pipeline plugin:

因此，管线功能是：


耐用：管道可以在计划和计划外重新启动您的Jenkins主人生存。
可停止：管道可以选择停止并等待人工输入或批准，然后再完成其构建的作业。
通用：流水线支持复杂的现实世界CD要求，包括分叉或连接，循环和彼此并行工作的能力。
可扩展：Pipeline插件支持对其DSL（域脚本语言）的自定义扩展和用于与其他插件集成的多个选项。
以下流程图是由管道插件启用的一个连续交付方案的示例：

figure 1. Pipeline Flow

Pipeline Defined

Pipelines are Jenkins jobs enabled by the Pipeline (formerly called "workflow") plugin and built with simple text scripts that use a Pipeline DSL (domain-specific language) based on the Groovy programming language.

Pipelines Leverage the power of multiple steps to execute both simple and complex tasks according to parameters that you establish. Once created,pipelines can build code and orchestrate the work required to drive applications from commit to delivery.

管道是由Pipeline（以前称为“工作流”）插件启用的Jenkins作业，并使用简单的文本脚本构建，使用基于Groovy编程语言的管道DSL（领域专用语言）。


管道利用多个步骤的功能根据您建立的参数执行简单和复杂的任务。 一旦创建，管道可以构建代码并编排从提交到交付的应用所需的工作。

Pipeline Vocabulary

Pipeline terms such as "step," "node," and "stage" are a subset of the vocabulary used for Jenkins in general.

诸如“step”，“node”和“stage”的流水线术语是用于通常的Jenkins的词汇表的子集。

Step

A "step" (often called a "build step") is a single task that is part of sequence. Steps tell Jenkins what to do.

“步骤”（通常称为“构建步骤”）是作为序列的一部分的单个任务。 步骤告诉jenkins做什么。

Node

In pipeline coding contexts,a "node" is a step that does two things,typically by enlisting help from available executors on agents:

• Schedules the steps contained within it to run by adding them to the Jenkins build queue (so that as soon as an executor slot is free on a node,the appropriate steps run).

• Creates a workspace,meaning a file directory specific to a particular job,where resource-intensive processing can occur without negatively impacting your pipeline performance. Workspaces created by node are automatically removed after all the steps contained inside the node declaration finish executing. It is a best practice to do all material work,such as building or running shell scripts,within nodes,because node blocks in a stage tell Jenkins that the steps within them are resource-intensive enough to be scheduled,request help from the agent pool,and lock a workspace only as long as they need it.

In Jenkins generally,"node" also means any computer that is part of your Jenkins installation,whether that computer is used as a master or as an agent.

在管道编码上下文中，“节点”是执行两个操作的步骤，通常通过从代理上的可用执行器获取帮助：
通过将其中包含的步骤添加到Jenkins构建队列（以便一旦执行器插槽在节点上可用，就运行相应的步骤）来运行它包含的步骤。

创建工作空间，意味着特定于特定作业的文件目录，其中可以进行资源密集型处理，而不会对流水线性能产生负面影响。在节点声明中包含的所有 步骤完成执行后，将自动删除由节点创建的工作空间。在节点中执行所有重要工作（例如构建或运行shell脚本）是最佳做法，因为阶段中的节点 块告诉Jenkins其中的步骤是足够资源调度的，请求代理池的帮助，并只锁定工作区，只要它们需要它。
在Jenkins中，“节点”还指任何作为Jenkins安装的一部分的计算机，无论该计算机是作为主机还是作为代理。

Stage

A "stage" is a logically distinct part of the execution of any task,with parameters for locking,ordering,and labeling its part of a process relative to other parts of the same process. Pipeline Syntax is often comprised of stages. Each stage step can have one or more build steps within it. It is a best practice to work within stages because they help with organization by lending logical divisions to a pipelines,and because the Jenkins Pipeline visualization feature displays stages as unique segments of the pipeline.

“阶段”是任何任务的执行的逻辑上不同的部分，具有用于相对于同一进程的其他部分锁定，排序和标记其过程的部分的参数。 流水线语法通常由阶段组成。 每个阶段步骤可以在其内具有一个或多个构建步骤。 这是一个最佳实践，在阶段内工作，因为它们通过将逻辑分区借给管道来帮助组织，并且因为Jenkins管道可视化功能将阶段显示为管道的唯一段。

Familiarity with Jenkins terms such as "master," "agent," and "executor" also helps with understanding how pipelines work. These terms are not specific to pipelines:

熟悉Jenkins术语，如“master”，“agent”和“executor人”也有助于了解管道的工作原理。 这些术语不是特定于管道：

• master - A "master" is the computer where the Jenkins server is installed and running; it handles tasks for your build system. Pipeline scripts are parsed on masters,where Groovy code runs and node blocks allocate executors and workspaces for use by any nested steps (such assh) that might request one or both.

• agent - An "agent" (formerly "slave") is a computer set up to offload available projects from the master. Your configuration determines the number and scope of operations that an agent can perform. Operations are performed by executors.

• executor - An "executor" is a computational resource for running builds or Pipeline steps. It can run on master or agent machines,either by itself or in parallel with other executors.

  
  

  
  
  master - “master”是安装并运行Jenkins服务器的计算机; 它处理您的构建系统的任务。 管道脚本在主器件上解析，Groovy代码在其中运行，节点块分配执行器和工作空间以供可能请求其中一个或两个的任何嵌套步骤（例如sh）使用。
  agent - “agent”（以前称为“slave”）是一台计算机，设置为从主机卸载可用项目。 您的配置确定代理程序可以执行的操作的数量和范围。 操作由执行程序执行。
  xecutor- “executor”是用于运行构建或流水线步骤的计算资源。 它可以在主机或代理机上运行，无论是自身还是与其他执行程序并行运行。
  

  
  
  

Preparing Jenkins to Run Pipelines

To run pipelines,you need to have a Jenkins instance that is set up with the appropriate plugins. This requires:

• Jenkins 1.642.3 or later (Jenkins 2 is recommended)

• The Pipeline plugin

Installing the Pipeline Plugin

The Pipeline plugin is installed in the same way as other Jenkins plugins. Installing the Pipeline plugin also installs the suite of related plugins on which it depends:

1. Open Jenkins in your web browser.

2. On the Manage Jenkins page for your installation,navigate toManage Plugins.

3. FindPipelinefrom among the plugins listed on the Available tab (You can do this by scrolling through the plugin list or by using "Pipeline" as a term to filter results).

4. Select the checkBox for Pipeline plugin.

5. Select eitherInstall without restartorDownload Now and install after restart.

6. Restart Jenkins.

Pipeline Plugin Context

The Pipeline plugin works with a suite of related plugins that enhance the pipeline functionality of your Jenkins setup. The related plugins typically introduce additional pipeline Syntax or visualizations.

For example,the table below,while not comprehensive,describes a few pipeline-related plugins in terms of their importance to pipeline functionality (required,recommended,or optional).

To get the basic pipeline functionality,you only need to install the main Pipeline plugin,but recommended plugins add additional capabilities that you will probably want. For example,it is a best practice to develop pipelines as code by storing aJenkinsfilewith pipeline script in your SCM,so that you can apply the same version control and testing to pipelines as you do to your other software,and that is why the Multibranch Pipeline plugin is recommended.

Pipeline插件与一组相关的插件配合使用，增强Jenkins设置的管道功能。 相关的插件通常引入附加的流水线语法或可视化。


例如，下面的表格并不全面，描述了一些管道相关的插件在管道功能（必需，推荐或可选）方面的重要性。


要获得基本的管道功能，您只需要安装主要的Pipeline插件，但推荐的插件添加您可能需要的附加功能。 例如，最佳实践是通过在您的SCM中存储具有管道脚本的Jenkins文件来开发管道作为代码，以便您可以对管道应用与其他软件相同的版本控制和测试，这就是为什么 建议使用多分支管道插件。

Optional plugins are mainly useful if you are creating pipelines that are related to the technologies that they support.

如果您正在创建与其支持的技术相关的管道，则可选插件对你们是有用的。

Plugin Name	Description	Status
Pipeline (workflow-aggregator)	Installs the core pipeline engine and its dependent plugins: Pipeline: API,Pipeline: Basic Steps,Pipeline: Durable Task Step,Pipeline: Execution Support,Pipeline: Global Shared Library for cps pipeline,Pipeline: Groovy cps Execution,Pipeline: Job,Pipeline: SCM Step,Pipeline: Step API	required
Pipeline: Stage View	Provides a graphical swimlane view of pipeline stage execution,as well as a build history of the stages 提供流水线阶段执行的图形泳道视图，以及阶段的构建历史	recommended
Multibranch Pipeline	Adds "Multibranch Pipeline" item type which enables Jenkins to automatically build branches that contain aJenkinsfile 添加“多分支管道”项目类型，使Jenkins能够自动构建包含Jenkins文件的分支	recommended
GitHub Branch Source	Adds GitHub Organization Folder item type and adds "GitHub" as a branch source on Multibranch pipelines 添加GitHub组织文件夹项目类型，并在多分支管道上添加“GitHub”作为分支源	recommended for teams hosting repositories in GitHub
Bitbucket Branch Source	Adds Bitbucket Team item type and adds "Bitbucket" as a branch source on Multibranch pipelines	recommended for teams hosting repositories in Bitbucket; best with Bitbucket Server 4.0 or later.
Docker Pipeline	Enables pipeline to build and use Docker containers inside pipeline scripts. 使管道能够在管道脚本中构建和使用Docker容器。	optional

More information

As with any Jenkins plugin,you can install the Pipeline plugin using the Plugin Manager in a running Jenkins instance.

To explore Pipeline without installing Jenkins separately or accessing your production system,you can run aDocker demoof Pipeline functionality.

Pipeline-related plugins are regularly "whitelisted" as compatible with or designed for Pipeline usage. For more information,see thePlugin Compatibility With Pipelineweb page.

When you get flows from source control throughJenkinsfileor aPipeline Global Library,you may also have to whitelist method calls in theScript Security Plugin.

与任何Jenkins插件一样，您可以使用插件管理器在运行的Jenkins实例中安装Pipeline插件。


要在不单独安装Jenkins或访问生产系统的情况下探索Pipeline，您可以运行管道功能的Docker演示。


管道相关的插件定期“列入白名单”，与管道使用兼容或设计。 有关详细信息，请参阅Plugin与Pipeline兼容的网页。


当从源控件通过Jenkinsfile或Pipeline全局库获得流时，您可能还必须在Script Security Plugin中将方法调用列入白名单。

Several plugins available in the Jenkins ecosystem but not actually related to the Pipeline feature set described in this guide also use the terms "pipeline," "DSL," and "Job DSL" in their names. For example: Build Pipeline plugin - provides a way to execute Jenkins jobs sequentially Build Flow Plugin - introduces a job type that lets you define an orchestration process as a script. This guide describes thePipeline Pluginthat supports the current Pipeline feature set.

Approaches to Defining Pipeline Script

You can create pipelines in either of the following ways:

• Through script entered in the configuration page of the web interface for your Jenkins instance.

• Through aJenkinsfilethat you create with a text editor and then check into your project’s source control repository,where it can be accessed when you select thePipeline Script from SCMoption while configuring the Pipeline in Jenkins.

  
  

  通过脚本输入您的Jenkins实例的Web界面的配置页。
  通过使用文本编辑器创建的Jenkins文件，然后检查项目的源代码控制存储库，当您在Jenkins中配置流水线时，从SCM选项选择流水线脚本时，可以访问它。
  
  
  

When you use a Jenkinsfile,it is a best practice to put #!groovy at the top of the file so that IDEs and GitHub diffs detect the Groovy language properly. 当您使用Jenkins文件时，最好将＃！groovy放在文件的顶部，以便IDE和GitHub diff可以正确检测Groovy语言。

Creating a Simple Pipeline

Initial pipeline usage typically involves the following tasks:

初始管道使用通常包括以下任务：

1. Downloading and installing the Pipeline plugin (Unless it is already part of your Jenkins installation)

2. Creating a Pipeline of a specific type

3. Configuring your Pipeline

4. Controlling flow (workflow) through your Pipeline

5. Scaling your Pipeline

下载和安装Pipeline插件（除非它已经是Jenkins安装的一部分）
创建特定类型的管道
配置管道
通过您的管道控制流（工作流）
缩放您的管道

To create a simple pipeline from the Jenkins interface,perform the following steps:

1. ClickNew Itemon your Jenkins home page,enter a name for your (pipeline) job,selectPipeline,and clickOK.

2. In the Script text area of the configuration screen,enter your pipeline script. If you are new to pipeline creation,you might want to start by opening Snippet Generator and selecting the "Hello Word" snippet.

3. Check the Use Groovy SandBox option below the Script text area.

4. ClickSave.

5. ClickBuild Nowto create the pipeline.

6. Click ▾ and selectConsole Outputto see the output.

Pipelines are written as Groovy scripts that tell Jenkins what to do when they are run. Relevant bits of Syntax are introduced as needed,so while an understanding of Groovy is helpful,it is not required to use Pipeline.

管道编写为Groovy脚本，告诉Jenkins当它们运行时要做什么。 根据需要引入了相关的语法位，因此理解Groovy是有帮助的，但不需要使用Pipeline。

If you are a Jenkins administrator (in other words,authorized to approve your own scripts),sandBoxing is optional but efficient,because it lets scripts run without approval as long as they limit themselves to operations that Jenkins considers inherently safe.

如果您是Jenkins管理员（换句话说，授权批准您自己的脚本），沙盒是可选的，但有效，因为它允许脚本没有批准，只要他们限制自己的操作，Jenkins认为本质上是安全的。

To use pathnames that include spaces,bracket those pathnames between escaped double quotes using \". The extra quotation marks ensure that any spaces in pathnames are parsed properly. 要使用包含空格的路径名，请使用\“将转义双引号之间的路径名括起来。额外的引号可确保正确解析路径名中的任何空格。

The following example shows a successful build of a pipeline created with a one-line script that uses theechostep to output the phrase,"Hello from Pipeline":

node {
    echo 'Hello from Pipeline'
}

Started by user anonymous
[Pipeline] echo
Hello from Pipeline
[Pipeline] End of Pipeline
Finished: SUCCESS

You can also create complex and multibranch pipelines in the script entry area of the Jenkins configuration page,but because they contain multiple stages and the configuration page UI provides limited scripting space,pipeline creation is more commonly done using an editor of your choice from which scripts can be loaded into Jenkins using thePipeline script from SCMoption. 您还可以在Jenkins配置页面的脚本输入区域中创建复杂和多分支管道，但是因为它们包含多个阶段，并且配置页面UI提供有限的脚本空间，所以使用您选择的编辑器 可以使用SCM选项中的Pipeline脚本加载到Jenkins中。

It is a best practice to use parallel steps whenever you can,as long as you remember not to attempt so much parallel processing that it swamps the number of available executors. For example,you can acquire a node within the parallel branches of your pipeline:

这是一个最佳实践，只要你能够使用并行步骤，只要你记得不要尝试这么多的并行处理，它集满了可用执行器的数量。 例如，您可以获取管道并行分支中的一个节点：

parallel integration-tests':{ node(mvn-3.3'){} },functional-testsselenium'){} }