The Jenkinsfile

The Jenkinsfile

Audience and Purpose

This document is intended for Jenkins users who want to leverage the power of pipeline functionality. Extending the reach of what was learned from a "Hello World" example in Getting Started with Pipeline, this document explains how to use a Jenkinsfile to perform a simple checkout and build for the contents of a repository.

本文档面向希望利用管道功能的Jenkins用户。 本文档介绍了如何使用Jenkinsfile对存储库的内容执行简单的检出和构建，从而扩展了从“Hello World”示例中学到的内容的范围。

Creating a Jenkinsfile

A Jenkinsfile is a Container for your pipeline (or other) script, which details what specific steps are needed to perform a job for which you want to use Jenkins. You create a Jenkinsfile with your preferred Groovy editor, or through the configuration page on the web interface of your Jenkins instance.

Jenkinsfile是您的管道（或其他）脚本的容器，其中详细说明了执行您要使用Jenkins的作业所需的特定步骤。 您可以使用首选的Groovy编辑器创建Jenkins文件，或者通过Jenkins实例的Web界面上的配置页面创建Jenkins文件。

Using a Groovy editor to code a Jenkinsfile gives you more flexibility for building complex single or multibranch pipelines, but whether you use an editor or the Jenkins interface does not matter if what you want to do is get familiar with basic Jenkinsfile content.

使用Groovy编辑器对Jenkins文件进行编码，可以更灵活地构建复杂的单行或多行分支管道，但是无论使用编辑器还是Jenkins接口，都不需要了解Jenkins文件的基本内容。

1. Open your Jenkins instance or Groovy editor.

2. Navigate to the directory you want (it should be the root directory for your project).

3. Use standard Jenkins syntax.

4. Save your file.

The following example shows a basic Jenkinsfile made to build and test code for a Maven project. node is the step that schedules tasks in the following block to run on the machine (usually an agent) that matches the label specified in the step argument (in this case, a node called "Linux"). Code between the braces ( { and } ) is the body of the nodestep. The checkout scm command indicates that this Jenkinsfile was created with an eye toward multibranch support:

以下示例显示了用于构建和测试Maven项目代码的基本Jenkins文件。 节点 是调度以下块中的任务以在与步骤参数中指定的标签匹配的机器（通常是代理）上运行的步骤（在这种情况下，称为“linux”节点）。 大括号（{和}）之间的代码是节点的主体。 checkout scm命令指示此Jenkins文件是以对多分支支持的眼光创建的：

 node ('linux'){
  stage 'Build and Test'
  env.PATH = "${tool 'Maven 3'}/bin:${env.PATH}"
  checkout scm
  sh 'mvn clean package'
 }

In single-branch contexts, you could replace .checkout scm. with a source code checkout step that calls a particular repository, such as:

在单分支上下文中，您可以替换.checkout scm。 具有调用特定存储库的源代码检出步骤，例如：

git url: "https://github.com/my-organization/simple-maven-project-with-tests.git"

Making Pull Requests

A pull request notifies the person responsible for maintaining a Jenkins repository that you have a change or change set that you want to see merged into the main branch associated with that repository. Each individual change is called a "commit."

拉取请求通知负责维护Jenkins存储库的人员，您具有希望合并到与该存储库关联的主分支的更改或更改集。 每个单独的更改称为“提交”。

You make pull requests from a command line, or by selecting the appropriately labeled button (typically "Pull" or "Create Pull Request") in the interface for your source code management system.

您可以从命令行或通过在源代码管理系统的界面中选择适当标记的按钮（通常为“Pull”或“Create Pull Request”）来执行pull请求。

A pull request to a repository included in or monitored by an Organization Folder can be used to automatically execute a multibranch pipeline build.

对包含在组织文件夹中或由组织文件夹监视的存储库的拉取请求可以用于自动执行多分支管道构建。

Using Organization Folders

Organization folders enable Jenkins to automatically detect and include any new repositories within them as resources.

组织文件夹使Jenkins能够自动检测并包含其中的任何新存储库作为资源。

When you create a new repository (as might be the case for a new project), that repository has a Jenkinsfile. If you also configure one or more organization folders, Jenkins automatically detects any repository in an organization folder, scans the contents of that repository at either default or configurable intervals, and creates a Multibranch Pipeline project for what it finds in the scan. An organization folder functions as a "parent," and any item within it is treated as a "child" of that parent.

当您创建一个新的存储库（对于一个新的项目的情况），该存储库有一个Jenkinsfile。 如果您还配置一个或多个组织文件夹，Jenkins会自动检测组织文件夹中的任何存储库，以默认或可配置的时间间隔扫描该存储库的内容，并为扫描中找到的内容创建多分支管道项目。 组织文件夹用作“父级”，并且其中的任何项目被视为该父级的“子级”。

Organization folders alleviate the need to manually create projects for new repositories. When you use organization folders, Jenkins views your repositories as a hierarchy, and each repository (organization folder) may optionally have child elements such as branches or pull requests.

组织文件夹减轻了为新存储库手动创建项目的需要。 当您使用组织文件夹时，Jenkins将您的存储库视为层次结构，每个存储库（组织文件夹）可以选择性地包含子元素，例如分支或拉取请求。

To create Organization folders:

1. Open Jenkins in your web browser.

2. Go to: New Item → GitHub Organization or New Item → Bitbucket Team.

3. Follow the configuration steps, making sure to specify appropriate scan credentials and a specific owner for the GitHub Organization or Bitbucket Team name.

4. Set build triggers by selecting the checkbox associated with the trigger type you want. Folder scans and the pipeline builds associated with those scans can be initiated by command scripts or performed at defined intervals. They can also triggered by project promotion or changes to the images in a monitored Docker hub.

5. Decide whether to automatically remove or retain unused items. "Orphaned Item Strategy" fields in the configuration interface let you specify how many days to keep old items, and how many old items to keep. If you enter no values in these fields, unused items are removed by default.

   
   

   4.通过选择与所需触发类型相关联的复选框来设置构建触发器。 文件夹扫描和与那些扫描相关联的流水线构建可以由命令脚本启动或以定义的间隔执行。 它们还可以通过项目推广或对受监控的Docker集线器中的映像的更改来触发。

   
   

   5.决定是否自动删除或保留未使用的项目。 配置界面中的“孤立项策略”字段允许您指定保留旧项目的天数以及要保留的旧项目数。 如果在这些字段中未输入任何值，则默认情况下将删除未使用的项目。

While configuring organization folders, you can set the following options:

• Repository name pattern - a regular expression to specify which repositories are included in scans

• API endpoint - an alternate API endpoint to use a self-hosted GitHub Enterprise

• Checkout credentials - alternate credentials to use when checking out (cloning) code

Multibranch Pipeline projects and Organization Folders are examples of "computed folder" functionality. In Multibranch Pipeline projects, computation creates child items for eligible branches. In Organization folders, computation populates child items as individual Multibranch Pipelines for scanned repositories.

多分支管道项目和组织文件夹是“计算文件夹”功能的示例。 在多分支管道项目中，计算为合格分支创建子项目。 在组织文件夹中，计算将子项目填充为扫描存储库的单个多分支管道。

Select the "Folder Computation" section of your Jenkins interface to see the duration (in seconds) and result (success or failure) of computation operations, or to access a Folder Computation Log that provides more detail about this activity.

选择Jenkins界面的“文件夹计算”部分，以查看计算操作的持续时间（以秒为单位）和结果（成功或失败），或访问提供有关此活动的更多详细信息的文件夹计算日志。

Basic Checkout and Build

Checkout and build command examples are shown in the code example used by the introduction above. Examples shown assume that Jenkins is running on Linux or another Unix-like operating system.

结束和构建命令示例在上面介绍的代码示例中显示。 显示的示例假设Jenkins正在Linux或另一个类Unix操作系统上运行。

If your Jenkins server or agent is running on Windows, you are less likely to be using the Bourne shell (sh) or Bourne-Again shell (bash) as a command language interpreter for starting software builds. In Windows environments, use bat in place of sh, and backslashes (\) rather than slashes as file separators in pathnames.

如果你的Jenkins服务器或代理在Windows上运行，你不太可能使用Bourne shell（sh）或Bourne-Again shell（bash）作为启动软件构建的命令语言解释器。 在Windows环境中，在路径名中使用bat代替sh，反斜杠（\）而不是斜杠作为文件分隔符。