使用 Jenkinsfile 创建流水线

更新时间：2024-05-30 01:59:10

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

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

说明
DevOps 支持创建两种类型的流水线：一种是本文档中介绍的基于 SCM 中 Jenkinsfile 创建的流水线，另一种是通过图形编辑面板创建的流水线。 Jenkinsfile in SCM 需要源代码管理 (SCM) 中有内置 Jenkinsfile，换句话说，Jenkinsfile 必须是 SCM 的一部分。DevOps 系统会根据代码仓库的现有 Jenkinsfile 自动构建 CI/CD 流水线。通过定义工作流，例如 stage 和 step 可以满足特定的构建、测试和部署要求。

说明

DevOps 支持创建两种类型的流水线：一种是本文档中介绍的基于 SCM 中 Jenkinsfile 创建的流水线，另一种是通过图形编辑面板创建的流水线。

Jenkinsfile in SCM 需要源代码管理 (SCM) 中有内置 Jenkinsfile，换句话说，Jenkinsfile 必须是 SCM 的一部分。DevOps 系统会根据代码仓库的现有 Jenkinsfile 自动构建 CI/CD 流水线。通过定义工作流，例如 stage 和 step 可以满足特定的构建、测试和部署要求。

前提条件

KubeSphere 企业版平台需要安装并启用 DevOps 扩展组件。
已有一个 Docker Hub 账户和一个 GitHub 账户。
已创建一个企业空间、一个 DevOps 项目和一个用户 (例如 project-regular)，并已邀请该用户至 DevOps 项目且授予 operator 角色。请参阅角色和成员管理。
已设置 CI 专用节点用于运行流水线。请参阅为依赖项缓存设置 CI 节点。
已安装和配置 SonarQube（可选）。请参阅将 SonarQube 集成到流水线。如果跳过这一部分，则没有下面的 SonarQube 分析阶段。

流水线概述

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

说明
阶段 1：Checkout SCM：从 GitHub 仓库检出源代码。阶段 2：单元测试：待该测试通过后才会进行下一阶段。阶段 3：SonarQube 分析：SonarQube 代码质量分析。阶段 4：构建并推送快照镜像：根据策略设置中选定的分支来构建镜像，并将 SNAPSHOT-$BRANCH_NAME-$BUILD_NUMBER 标签推送至 Docker Hub，其中 $BUILD_NUMBER 是流水线运行记录列表中的记录的运行 ID。阶段 5：推送最新镜像：将 v4.1.0-sonarqube 分支标记为 latest，并推送至 Docker Hub。阶段 6：带标签推送：生成标签并发布到 GitHub，该标签会推送到 Docker Hub。

说明

阶段 1：Checkout SCM：从 GitHub 仓库检出源代码。
阶段 2：单元测试：待该测试通过后才会进行下一阶段。
阶段 3：SonarQube 分析：SonarQube 代码质量分析。
阶段 4：构建并推送快照镜像：根据策略设置中选定的分支来构建镜像，并将 SNAPSHOT-$BRANCH_NAME-$BUILD_NUMBER 标签推送至 Docker Hub，其中 $BUILD_NUMBER 是流水线运行记录列表中的记录的运行 ID。
阶段 5：推送最新镜像：将 v4.1.0-sonarqube 分支标记为 latest，并推送至 Docker Hub。
阶段 6：带标签推送：生成标签并发布到 GitHub，该标签会推送到 Docker Hub。

步骤 1：创建凭证

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

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

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

说明

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

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

凭证 ID

类型

用途

dockerhub-id

用户名和密码

Docker Hub

github-id

用户名和密码

GitHub

再为 SonarQube 创建一个凭证 (sonar-token)，用于上述的阶段 3（代码分析）。凭证类型选择访问令牌，在令牌字段输入 SonarQube 令牌，请参阅为新项目创建 SonarQube 令牌 (Token)。点击确定完成操作。
还需要创建具有如下图所示权限的 GitHub 个人访问令牌 (PAT)，然后在 DevOps 项目中，使用生成的令牌创建用于 GitHub 认证的账户凭证（例如，github-token）。

说明

如需创建 GitHub 个人访问令牌，请转到您 GitHub 账户的 Settings，点击 Developer settings，选择 Personal access tokens，然后点击 Generate new token。
您将在凭证页面看到已创建的凭证。

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

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

登录 GitHub 并 Fork GitHub 仓库 devops-maven-sample 的所有分支至您的 GitHub 个人账户。
在您自己的 GitHub 仓库 devops-maven-sample 中，切换到 v4.1.0-sonarqube 分支，点击根目录中的文件 Jenkinsfile-online。

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

条目	值	描述信息
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 令牌设置的名称，用于代码质量检测。

条目

值

描述信息

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 表示开启离线模式。本教程中已下载相关依赖项，以节省时间并适应某些环境中的网络干扰。离线模式默认开启。

说明

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

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

步骤 3：创建流水线

以 project-regular 用户登录 KubeSphere 企业版 Web 控制台。
点击企业空间管理并进入您的 DevOps 项目，在流水线页面点击创建。
在弹出的对话框中，将其命名为 jenkinsfile-in-scm。
在流水线类别下，选择多分支流水线。
在代码仓库下，选择一个代码仓库，点击下一步继续。

若没有可用的代码仓库，点击下方的创建代码仓库。有关更多信息，请参阅导入代码仓库。
1. 在导入代码仓库对话框，输入代码仓库名称（自定义），点击选择代码仓库。
2. 在 GitHub 页签，从凭证的下拉菜单中选择 github-token，然后点击确定。
3. 在 GitHub 列表中，选择您的 GitHub 账户，与该令牌相关的所有仓库将在右侧列出。选择 devops-maven-sample 并点击选择。
4. 点击确定选择您的代码仓库。

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

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

分支保留天数（天）：超过保留期限的分支将被删除。
分支最大数量：分支数量超过最大数量时，删除最旧的分支。

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

说明

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

在策略设置中，DevOps 默认提供四种策略。本示例不会使用从 Fork 仓库中发现 PR 这条策略，因此您可以删除该策略。对于其他策略，无需修改设置，直接使用默认值即可。
Jenkins 流水线运行时，开发者提交的 Pull Request (PR) 也将被视为一个单独的分支。

发现分支
- 排除已提交 PR 的分支：不扫描源分支，例如源仓库的 master 分支。需要合并这些分支。
- 只包括已提交 PR 的分支：仅扫描 PR 分支。
- 包括所有分支：拉取源仓库中的所有分支。
从原仓库发现 PR
- 拉取 PR 合并后的代码：PR 合并到目标分支后，基于源代码创建并运行流水线。
- 拉取 PR 提交时的代码：根据 PR 本身的源代码创建并运行流水线。
- 分别创建两个流水线：创建两个流水线，一个流水线使用 PR 与目标分支合并后的源代码版本，另一个使用 PR 本身的源代码版本。
说明

选择 GitHub 作为代码仓库，才能启用此处的策略设置设置。
向下滚动到脚本路径，将其更改为 Jenkinsfile-online，这是示例仓库中位于根目录下的 Jenkinsfile 的文件名。该字段指定代码仓库中的 Jenkinsfile 路径。它表示仓库的根目录。如果文件位置变更，则脚本路径也需要更改。
在扫描触发器中，勾选定时扫描并设置时间间隔为 5 分钟。点击创建完成配置。

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

说明
设置特定的时间间隔让流水线扫描远程仓库，以便根据您在策略设置中设置的策略来检测代码更新或新的 PR。

说明

设置特定的时间间隔让流水线扫描远程仓库，以便根据您在策略设置中设置的策略来检测代码更新或新的 PR。

步骤 4：运行流水线

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

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

说明

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

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

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

说明

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

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

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

说明

运行失败可能由不同因素所引起。本示例中，在上述步骤中编辑分支的环境变量时，仅更改了 v4.1.0-sonarqube 分支的 Jenkinsfile。而 v4.1.0 分支中的这些变量没有修改（使用了错误的 GitHub 和 Docker Hub 账户），从而导致失败。其他原因如网络问题、Jenkinsfile 中的编码不正确等也可能导致运行失败。

在运行记录详情页的运行日志页签下，查看其日志的详细信息，根据日志排除故障和问题。

流水线如果运行到 Push with Tag 阶段，会在此阶段暂停，需要具有审核权限的用户点击继续。
在开发或生产环境中，可能需要具有更高权限的人员（例如版本管理员）来审核流水线、镜像以及代码分析结果。他们有权决定流水线是否能进入下一阶段。在 Jenkinsfile 中，支持使用 input 来指定审核流水线的用户。如果想指定一个用户（例如 project-admin）来审核，可以在 Jenkinsfile 中添加一个字段。如果有多个用户，则需要通过逗号进行分隔，如下所示：
input(id: 'release-image-with-tag', message: 'release image with tag?', submitter: 'project-admin,project-admin1')
以具有流水线审核权限的用户登录 KubeSphere 企业版 Web 控制台，点击企业空间管理并进入您的 DevOps 项目，点击流水线名称进入详情页。在运行记录页签下，点击要审核的记录，点击继续以批准流水线。

说明
在 KubeSphere 企业版中，如果不指定审核员，那么能够运行流水线的账户也能够继续或终止该流水线。此外，流水线创建者、拥有该项目管理员角色的用户或者您指定的账户也有权限继续或终止流水线。

说明

在 KubeSphere 企业版中，如果不指定审核员，那么能够运行流水线的账户也能够继续或终止该流水线。此外，流水线创建者、拥有该项目管理员角色的用户或者您指定的账户也有权限继续或终止流水线。

步骤 5：检查流水线状态

在运行记录的流水线页签下，查看流水线的运行状态。流水线在刚创建时会初始化几分钟。示例流水线有八个阶段，它们已在 Jenkinsfile-online 中单独定义。
点击运行日志页签查看流水线运行日志。点击每个阶段查看其详细日志。点击查看完整日志，根据日志排除故障和问题，也可以将日志下载到本地进行进一步分析。

步骤 6：验证结果

流水线成功运行后，点击代码检查通过 SonarQube 查看结果。
按照 Jenkinsfile 中的定义，通过流水线构建的 Docker 镜像也已成功推送到 Docker Hub。在 Docker Hub 中，您会看到带有标签 v0.0.2 的镜像，该标签在流水线运行之前已指定。
同时，GitHub 中会生成一个新标签和一个新发布版本。