流水线开发工具

Pipeline Development Tools

Jenkins 的流水线包含了 内置文档 和 代码片段生成器，他们是开发时的关键资源。他们提供了根据当前安装的 Jenkins 与相关插件的版本进行定制的详细帮助和信息。在本节中，我们将讨论可能有助于开发 Jenkins 流水线的其他工具和资源。

命令行的流水线静态分析程序

Command-line Pipeline Linter

Jenkins 可以在实际运行某个声明式流水线之前从命令行中验证，或者说 “静态分析，lint”。这可以通过使用 Jenkins CLI 命令或带适当参数的 HTTP POST 请求来完成。我们建议使用 SSH 接口 来运行静态分析程序。关于如何正确配置 Jenkins 以实现安全命令行访问的细节，请参见 Jenkins CLI 文档。

# 通过 SSH 下的 CLI 进行静态检查
# ssh (Jenkins CLI)
# JENKINS_PORT=[sshd port on controller]
# JENKINS_HOST=[Jenkins controller hostname]
ssh -p $JENKINS_PORT $JENKINS_HOST declarative-linter < Jenkinsfile

在执行了 alias jenkins-cli='ssh -l ci_cd_scm -p 32222 ci.senscomm.com' 时，执行如下命令：

jenkins-cli declarative-linter < Jenkinsfile

# 使用 `curl` 通过 HTTP POST 进行静态检查
# curl (REST API)
# Assuming "anonymous read access" has been enabled on your Jenkins instance.
# JENKINS_URL=[root URL of Jenkins controller]
# JENKINS_CRUMB is needed if your Jenkins controller has CRSF protection enabled as it should
JENKINS_CRUMB=`curl "$JENKINS_URL/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,\":\",//crumb)"`
curl -X POST -H $JENKINS_CRUMB -F "jenkinsfile=<Jenkinsfile" $JENKINS_URL/pipeline-model-converter/validate

示例

下面是流水线静态检查器的两个实际例子。第一个示例显示了当传递一个无效的 Jenkinsfile 给静态检查器时的输出，这个文件缺少 agent 声明的部分。

// Jenkinsfile
pipeline {
  agent
  stages {
    stage ('Initialize') {
      steps {
        echo 'Placeholder.'
      }
    }
  }
}

# 无效 Jenkinsfile 的静态检查器输出
# 传递一个未包含 `agent` 小节的 Jenkinsfile

$ jenkins-cli declarative-linter < ./Jenkinsfile
Errors encountered validating Jenkinsfile:
WorkflowScript: 4: Not a valid section definition: "agent". Some extra configuration is required. @ line 4, column 5.
       agent
       ^

WorkflowScript: 3: Missing required section "agent" @ line 3, column 1.
   pipeline {
   ^

在第二个示例中，这个 Jenkinsfile 已经被更新，以包括缺少的在 agent 上的 any。现在静态检查器就会报告说这个流水线脚本是有效的。

// Jenkinsfile
pipeline {
  agent any
  stages {
    stage ('Initialize') {
      steps {
        echo 'Placeholder.'
      }
    }
  }
}

# 有效 Jenkinsfile 的静态检查器输出

$ jenkins-cli declarative-linter < ./Jenkinsfile
Jenkinsfile successfully validated.

Blue Ocean 编辑器

Blue Ocean 的流水线编辑器 提供了一种 WYSIWYG 方式来创建声明式流水线。该编辑器提供了某个流水线中所有阶段、平行分支及步骤的结构化视图。该编辑器在进行流水线修改时进行验证，在提交之前就消除了许多错误。而在幕后，其仍会生成声明式流水线代码。

Blue Ocean 的现状

Blue Ocean 将不再接收更多的功能更新。Blue Ocean 将继续提供易于使用的管道可视化，但他不会得到进一步增强。他只会在重大安全问题或功能缺陷方面得到选择性的更新。

Pipeline 语法片段生成器 会在用户以参数定义 Pipeline 步骤时为他们提供帮助。他是创建 Jenkins 管道的首选工具，因为他为咱们 Jenkins 控制器中的流水线步骤提供在线帮助。他会使用安装在咱们 Jenkins 控制器上的插件来生成 Pipeline 语法。关于所有可用的 Pipeline 步骤的信息，请参考 Pipeline 步骤参考页。

附带修改的 “回放” 流水线运行

"Replay" Pipeline Runs with Modifications

通常情况下，流水线将在经典的 Jenkins Web UI 中定义，或者通过提交到源码控制系统中的 Jenkinsfile 定义。不幸的是，这两种方法对于流水线的快速迭代或原型设计都不理想。“回放，Replay” 特性允许快速修改和执行现有的流水线，而无需改变流水线的配置或创建新的提交，commit。

用法

要使用 “回放” 特性：

1. 在构建历史中选择一个以前完成的运行；

2. 点击左侧菜单中的 “回放”；

3. 进行修改并点击 "运行"；

4. 检查修改后的结果。

一旦咱们对修改感到满意，就可以使用回放来再次查看他们，将他们复制到咱们的 Pipeline 作业或 Jenkinsfile 中，然后使用咱们常规的工程流程提交这些修改。

特点

Features

• 可在同一运行中多次调用 -- 可以方便地对不同修改进行平行测试；

• 也可以对仍在进行中的流水线运行进行调用 -- 只要流水线包含语法正确的 Groovy 代码并且能够启动，就可以被回放；

• 引用的共享库代码也可以修改 -- 如果流水线运行引用了 共享库，那么共享库的代码也会作为 Replay 页面的一部分显示并可以修改；

• 通过专门的 "运行/回放" 权限进行访问控制 -- 这一点由 “作业/配置” 所暗示。如果流水线是不可配置的（如多分支的分支流水线）或 “作业/配置” 未被授权，用户仍然可以通过回放试验流水线的定义;

• 可用于重新运行，Re-run -- 缺乏 “运行/回放” 权限但被授予了 “作业/构建” 的用户仍然可以使用回放来以同一流水线定义重新运行构建。

局限性

Limitations

• 有语法错误的流水线运行不能被重放 -- 这意味着他们的代码无法被查看，在其中所做的任何修改也不能被检索到。当使用回放进行一些较为重要的修改时，请在运行之前将咱们的修改保存到 Jenkins 之外的文件或编辑器中。参见 JENKINS-37589；

• 所回放的流水线行为可能与通过其他方法启动的运行有区别 - 对于不属于多分支流水线一部分的流水线，原始运行和回放运行的代码提交信息可能不同。参见 JENKINS-36453**

IDE 集成

IDE Integrations

Eclipse 的 Jenkins 编辑器

Eclipse 的 Jenkins Editor 插件可以在 Eclipse Marketplace 上找到。这个特别的文本编辑器提供了一些用于定义流水线的功能，例如：

• 通过 Jenkins 的静态检查器检查 而验证流水线脚本。检查失败会显示为 eclipse 标记；

• 带有专用图标的大纲（用于声明式 Jenkins 流水线）；

• 语法/关键词高亮显示；

• Groovy 语法检查。

这个 Jenkins 编辑器插件是个第三方工具，不受 Jenkins 项目方所支持。

VisualStudio Code 的 Jenkins 流水线静态检查器连接器

VisualStudio Code Jenkins Pipeline Linter Connector

VisualStudio Code 的 Jenkins Pipeline Linter Connector 扩展会将咱们当前打开的文件，推送到咱们的 Jenkins 服务器，并在 VS Code 中显示验证结果。

你可以在 VS Code 的扩展浏览器中找到这个扩展，也可以在以下网址找到：

marketplace.visualstudio.com/items?itemName=janjoerke.jenkins-pipeline-linter-connector

该扩展会在 VS Code 中增加了四个设置项，选择咱们打算用来验证的 Jenkins 服务器。

• jenkins.pipeline.linter.connector.url 是 Jenkins 服务器所期望的包含咱们打算验证 Jenkinsfile 的 POST 请求端点，the endpoint。通常，这会指向 <your_jenkins_server:port>/pipeline-model-converter/validate；

• jenkins.pipeline.linter.connector.user 允许咱们指定咱们的 Jenkins 用户名；

• jenkins.pipeline.linter.connector.pass 允许咱们指定咱们的 Jenkins 密码；

• 如果咱们的 Jenkins 服务器启用了 CRSF 保护，那么就必须指定 jenkins.pipeline.linter.connector.crumbUrl。通常这会指向 <your_jenkins_server:port>/crumbIssuer/api/xml?xpath=concat（//crumbRequestField,%22:%22,//crumb）。

Neovim 的 nvim-jenkinsfile-linter 插件

这个 nvim-jenkinsfile-linter Neovim 插件允许咱们通过使用 Jenkins 实例的流水线静态检查器 API 来验证 Jenkinsfile，并在编辑器中报告任何既有的诊断信息。

Atom 的 linter-jenkins 包

这个 linter-jenkins Atom 软件包允许咱们通过使用运行中的 Jenkins 的流水线静态检查器 API 来验证某个 Jenkinsfile。咱们可以直接从 Atom 包管理器中安装他。他还需要安装 Atom 中的 Jenkinsfile 语言支持。

Sublime Text 的 Jenkinsfile 包

这个 Jenkinsfile Sublim Text 包允许咱们通过安全通道（SSH）使用运行中的 Jenkins 实例的流水线静态检查器 API 来验证某个 Jenkinsfile。咱们可以直接从 Sublime Text 包管理器中安装他。

咱们可以在 Sublime Text 界面中的 Package Control 包，在 GitHub 上， 或在 packagecontrol.io 找到该包：

• https://github.com/june07/sublime-Jenkinsfile

• https://packagecontrol.io/packages/Jenkinsfile

流水线的单元测试框架

Pipeline Unit Testing Framework

流水线的单元测试框架 允许咱们在完全运行流水线和 共享库 之前对其进行 单元测试。他提供了一个模拟执行环境，其中真实的流水线步骤会被模拟对象取代，咱们可以用他来检查预期行为。这个框架有着新的和略微粗糙的边缘，但很有希望，new and rough around the edges, but promising。这个项目的 README 包含了一些示例及使用说明。