Jenkinsfile 是一个文本文件，包含 Jenkins 流水线的定义，并被检入源代码控制仓库。Jenkinsfile 将整个工作流存储为代码，因此它是代码审查和流水线迭代过程的基础。有关更多信息，请参阅 Jenkins 官方文档。

本文档演示如何基于 GitHub 仓库中的 Jenkinsfile 创建流水线。

前提条件

• KubeSphere 企业版平台需要安装并启用 DevOps 扩展组件。

• 已有一个 Docker Hub 账户和一个 GitHub 账户。

• 已创建一个企业空间、一个 DevOps 项目和一个用户 (例如 project-regular)，并已邀请该用户至 DevOps 项目且授予 operator 角色。请参阅角色和成员管理。

• 已设置 CI 专用节点用于运行流水线。请参阅为依赖项缓存设置 CI 节点。

• 已安装和配置 SonarQube（可选）。请参阅将 SonarQube 集成到流水线。如果跳过这一部分，则没有下面的 SonarQube 分析阶段。

流水线概述

本示例流水线包括以下阶段。

步骤 1：创建凭证

1. 以 project-regular 用户登录 KubeSphere 企业版 Web 控制台。

2. 点击企业空间管理并进入您的 DevOps 项目，在 DevOps 项目设置下的凭证页面创建以下凭证。有关如何创建凭证的更多信息，请参阅凭证管理。

   说明
   如果您的账户或密码中包含任何特殊字符，例如 @ 和 $，可能会因为无法识别而在流水线运行时导致错误。在这种情况下，请先在一些第三方网站（例如 urlencoder）上对账户或密码进行编码，然后将输出结果复制粘贴作为您的凭证信息。

   凭证 ID	类型	用途
   dockerhub-id	用户名和密码	Docker Hub
   github-id	用户名和密码	GitHub

3. 再为 SonarQube 创建一个凭证 (sonar-token)，用于上述的阶段 3（代码分析）。凭证类型选择访问令牌，在令牌字段输入 SonarQube 令牌，请参阅为新项目创建 SonarQube 令牌 (Token)。点击确定完成操作。

4. 还需要创建具有如下图所示权限的 GitHub 个人访问令牌 (PAT)，然后在 DevOps 项目中，使用生成的令牌创建用于 GitHub 认证的账户凭证（例如，github-token）。

   

   说明
   如需创建 GitHub 个人访问令牌，请转到您 GitHub 账户的 Settings，点击 Developer settings，选择 Personal access tokens，然后点击 Generate new token。

5. 您将在凭证页面看到已创建的凭证。

步骤 2：在 GitHub 仓库中修改 Jenkinsfile

1. 登录 GitHub 并 Fork GitHub 仓库 devops-maven-sample 的所有分支至您的 GitHub 个人账户。

2. 在您自己的 GitHub 仓库 devops-maven-sample 中，切换到 v4.1.0-sonarqube 分支，点击根目录中的文件 Jenkinsfile-online。

3. 点击右侧的编辑图标，编辑环境变量。

   条目	值	描述信息
   DOCKER_CREDENTIAL_ID	dockerhub-id	您在 KubeSphere 企业版中为 Docker Hub 账户设置的名称。
   GITHUB_CREDENTIAL_ID	github-id	您在 KubeSphere 企业版中为 GitHub 账户设置的名称，用于将标签推送至您的 GitHub 仓库。
   REGISTRY	docker.io	默认为 docker.io，用作推送镜像的地址。
   DOCKERHUB_NAMESPACE	your-dockerhub-id	请替换为您的 Docker Hub 账户名，也可以替换为该账户下的 Organization 名称。
   GITHUB_ACCOUNT	your-github-id	请替换为您的 GitHub 账户名。例如，如果您的 GitHub 地址是 https://github.com/kubesphere/，则您的 GitHub 账户名为 kubesphere，也可以替换为该账户下的 Organization 名称。
   APP_NAME	devops-maven-sample	应用名称。
   SONAR_CREDENTIAL_ID	sonar-token	您在 KubeSphere 企业版中为 SonarQube 令牌设置的名称，用于代码质量检测。

   说明
   Jenkinsfile 中 mvn 命令的参数 -o 表示开启离线模式。本教程中已下载相关依赖项，以节省时间并适应某些环境中的网络干扰。离线模式默认开启。

4. 编辑环境变量后，点击 Commit changes，更新 v4.1.0-sonarqube 分支中的文件。

步骤 3：创建流水线

1. 以 project-regular 用户登录 KubeSphere 企业版 Web 控制台。

2. 点击企业空间管理并进入您的 DevOps 项目，在流水线页面点击创建。

3. 在弹出的对话框中，将其命名为 jenkinsfile-in-scm。

4. 在流水线类别下，选择多分支流水线。

5. 在代码仓库下，选择一个代码仓库，点击下一步继续。

   若没有可用的代码仓库，点击下方的创建代码仓库。有关更多信息，请参阅导入代码仓库。

   1. 在导入代码仓库对话框，输入代码仓库名称（自定义），点击选择代码仓库。

   2. 在 GitHub 页签，从凭证的下拉菜单中选择 github-token，然后点击确定。

   3. 在 GitHub 列表中，选择您的 GitHub 账户，与该令牌相关的所有仓库将在右侧列出。选择 devops-maven-sample 并点击选择。

   4. 点击确定选择您的代码仓库。

6. 在高级设置中，勾选删除旧分支。本教程中，建议分支保留天数（天）和分支最大数量使用默认值。

   删除旧分支意味着您将一并丢弃分支记录。分支记录包括控制台输出、已归档制品以及特定分支相关的其他元数据。更少的分支意味着您可以节省 Jenkins 正在使用的磁盘空间。DevOps 提供两个选项来确定何时丢弃旧分支：

   • 分支保留天数（天）：超过保留期限的分支将被删除。

   • 分支最大数量：分支数量超过最大数量时，删除最旧的分支。

   说明
   分支保留天数（天）和分支最大数量可以同时应用于分支。只要某个分支满足其中一个字段所设置的条件，则会删除该分支。例如，如果您将保留天数和最大分支数分别指定为 2 和 3，待某个分支的保留天数超过 2 或者分支保留数量超过 3，则会删除该分支。DevOps 默认用 7 和 5 预填充这两个字段。

7. 在策略设置中，DevOps 默认提供四种策略。本示例不会使用从 Fork 仓库中发现 PR 这条策略，因此您可以删除该策略。对于其他策略，无需修改设置，直接使用默认值即可。

   Jenkins 流水线运行时，开发者提交的 Pull Request (PR) 也将被视为一个单独的分支。

   发现分支

   • 排除已提交 PR 的分支：不扫描源分支，例如源仓库的 master 分支。需要合并这些分支。

   • 只包括已提交 PR 的分支：仅扫描 PR 分支。

   • 包括所有分支：拉取源仓库中的所有分支。

   从原仓库发现 PR

   • 拉取 PR 合并后的代码：PR 合并到目标分支后，基于源代码创建并运行流水线。

   • 拉取 PR 提交时的代码：根据 PR 本身的源代码创建并运行流水线。

   • 分别创建两个流水线：创建两个流水线，一个流水线使用 PR 与目标分支合并后的源代码版本，另一个使用 PR 本身的源代码版本。

   说明
   选择 GitHub 作为代码仓库，才能启用此处的策略设置设置。

8. 向下滚动到脚本路径，将其更改为 Jenkinsfile-online，这是示例仓库中位于根目录下的 Jenkinsfile 的文件名。该字段指定代码仓库中的 Jenkinsfile 路径。它表示仓库的根目录。如果文件位置变更，则脚本路径也需要更改。

9. 在扫描触发器中，勾选定时扫描并设置时间间隔为 5 分钟。点击创建完成配置。

步骤 4：运行流水线

1. 流水线创建后，会展示在列表中。点击流水线名称查看其详情页。

   说明
   在流水线列表页面，点击该流水线右侧的，选择复制来创建该流水线的副本。 如果要同时运行多个不包含多分支的流水线，在流水线列表页面，全部选中这些流水线，然后点击运行来批量运行它们。 流水线详情页面的同步状态，显示了 KubeSphere 企业版和 Jenkins 之间的同步结果。若同步成功，将显示成功以及绿色的对号图标。

2. 在运行记录页签下，正在扫描多个分支。点击右侧的运行，流水线将根据您设置的行为策略来运行。从下拉列表中选择 v4.1.0-sonarqube 分支，然后添加标签号，例如 v0.0.2。点击确定开始运行。

   说明
   如果您在此页面上未看到任何运行记录，则需要手动刷新浏览器或点击更多操作按钮中的扫描仓库。 标签名称用于在 GitHub 和 Docker Hub 中指代新生成的发布版本和镜像。现有标签名称不能再次用于字段 TAG_NAME。否则，流水线将无法成功运行。

3. 稍等片刻，点击运行记录查看详情。

   说明
   运行失败可能由不同因素所引起。本示例中，在上述步骤中编辑分支的环境变量时，仅更改了 v4.1.0-sonarqube 分支的 Jenkinsfile。而 v4.1.0 分支中的这些变量没有修改（使用了错误的 GitHub 和 Docker Hub 账户），从而导致失败。其他原因如网络问题、Jenkinsfile 中的编码不正确等也可能导致运行失败。 在运行记录详情页的运行日志页签下，查看其日志的详细信息，根据日志排除故障和问题。

4. 流水线如果运行到 Push with Tag 阶段，会在此阶段暂停，需要具有审核权限的用户点击继续。

   在开发或生产环境中，可能需要具有更高权限的人员（例如版本管理员）来审核流水线、镜像以及代码分析结果。他们有权决定流水线是否能进入下一阶段。在 Jenkinsfile 中，支持使用 input 来指定审核流水线的用户。如果想指定一个用户（例如 project-admin）来审核，可以在 Jenkinsfile 中添加一个字段。如果有多个用户，则需要通过逗号进行分隔，如下所示：

   input(id: 'release-image-with-tag', message: 'release image with tag?', submitter: 'project-admin,project-admin1')

5. 以具有流水线审核权限的用户登录 KubeSphere 企业版 Web 控制台，点击企业空间管理并进入您的 DevOps 项目，点击流水线名称进入详情页。在运行记录页签下，点击要审核的记录，点击继续以批准流水线。

步骤 5：检查流水线状态

1. 在运行记录的流水线页签下，查看流水线的运行状态。流水线在刚创建时会初始化几分钟。示例流水线有八个阶段，它们已在 Jenkinsfile-online 中单独定义。

2. 点击运行日志页签查看流水线运行日志。点击每个阶段查看其详细日志。点击查看完整日志，根据日志排除故障和问题，也可以将日志下载到本地进行进一步分析。

步骤 6：验证结果

1. 流水线成功运行后，点击代码检查通过 SonarQube 查看结果。

2. 按照 Jenkinsfile 中的定义，通过流水线构建的 Docker 镜像也已成功推送到 Docker Hub。在 Docker Hub 中，您会看到带有标签 v0.0.2 的镜像，该标签在流水线运行之前已指定。

3. 同时，GitHub 中会生成一个新标签和一个新发布版本。