Pipelines 作为代码(Pipelines as Code)
配置和使用 Pipelines as Code
摘要
第 1 章 关于 Pipelines as Code 复制链接链接已复制到粘贴板!
使用 Pipelines 作为 Code,具有所需权限的集群管理员和用户可以将管道模板定义为源代码 Git 存储库的一部分。当由源代码推送或配置的 Git 存储库的拉取请求触发时,Pipelines as Code 会运行管道并报告状态。
1.1. 主要特性 复制链接链接已复制到粘贴板!
作为代码的管道支持以下功能:
- 在托管 Git 仓库的平台上拉取请求状态并控制。
- GitHub Checks API 以设置管道运行的状态,包括重新检查。
- GitHub 拉取请求和提交事件。
-
在注释中拉取请求操作,如
/retest。 - Git 事件过滤和每个事件一个单独的管道。
- OpenShift Pipelines 中的自动任务解析,包括本地任务、Tekton Hub 和远程 URL。
- 使用 GitHub blob 和对象 API 检索配置。
-
通过 GitHub 机构或使用 Prow 风格的
OWNERS文件访问控制列表(ACL)。 -
用于管理 bootstrap 和 Pipelines 作为代码软件仓库的
tkn pacCLI 插件。 - 支持 GitHub App、GitHub Webhook、Bitbucket 服务器和 Bitbucket 云。
第 2 章 安装和配置 Pipelines as Code 复制链接链接已复制到粘贴板!
您可以作为 Red Hat OpenShift Pipelines 安装的一部分安装 Pipelines as Code。
2.1. 在 OpenShift Container Platform 上安装 Pipelines 作为代码 复制链接链接已复制到粘贴板!
安装 Red Hat OpenShift Pipelines Operator 时,Pipelines 作为代码安装在 openshift-pipelines 命名空间中。如需了解更多详细信息,请参阅附加资源部分的安装 OpenShift Pipelines。
要使用 Operator 禁用 Pipelines as Code 的默认安装,请在 TektonConfig 自定义资源中将 enable 参数的值设置为 false。
另外,您可以运行以下命令:
oc patch tektonconfig config --type="merge" -p '{"spec": {"platforms": {"openshift":{"pipelinesAsCode": {"enable": false}}}}}'
$ oc patch tektonconfig config --type="merge" -p '{"spec": {"platforms": {"openshift":{"pipelinesAsCode": {"enable": false}}}}}'
要使用 Red Hat OpenShift Pipelines Operator 启用 Pipelines 的默认安装,在 TektonConfig 自定义资源中将 enable 参数的值设置为 true :
另外,您可以运行以下命令:
oc patch tektonconfig config --type="merge" -p '{"spec": {"platforms": {"openshift":{"pipelinesAsCode": {"enable": true}}}}}'
$ oc patch tektonconfig config --type="merge" -p '{"spec": {"platforms": {"openshift":{"pipelinesAsCode": {"enable": true}}}}}'
2.2. 将管道安装为代码 CLI 复制链接链接已复制到粘贴板!
集群管理员可以在本地机器中使用 tkn pac 和 opc CLI 工具,或作为容器进行测试。当您为 Red Hat OpenShift Pipelines 安装 tkn CLI 时,tkn pac 和 opc CLI 工具会自动安装。
您可以为支持的平台安装 tkn pac 和 opc 版本 1.17.0 二进制文件:
2.3. 自定义 Pipelines as Code 配置 复制链接链接已复制到粘贴板!
要自定义 Pipelines as Code,集群管理员可在 TektonConfig 自定义资源中配置以下参数,在 platform. openshift.pipelinesAsCode.settings spec 中配置以下参数:
| 参数 | 描述 | default |
|---|---|---|
|
| 应用程序的名称。例如,GitHub Checks 标签中显示的名称。 |
|
|
| 指明是否应使用 GitHub 应用中生成的令牌自动创建 secret。然后可将这个 secret 用于私有仓库。 |
|
|
| 启用后,允许来自管道运行注解的远程任务。 |
|
|
| Tekton Hub API 的基本 URL。 | |
|
| Tekton Hub 目录名称。 |
|
|
|
Tekton Hub 仪表板的 URL。Pipelines as Code 使用这个 URL 在 Tekton Hub 仪表板中生成一个 | 不适用 |
|
| 通过查询公共 Bitbucket 的 IP 范围来指示是否保护服务请求。更改参数的默认值可能会导致安全问题。 |
|
|
| 指明是否提供一组额外的 IP 范围或网络,它们用逗号分开。 | 不适用 |
|
|
管道运行的 | 不适用 |
|
|
管道运行的 | 不适用 |
|
| 自动配置新的 GitHub 存储库。Pipelines as Code 设置命名空间,并为存储库创建一个自定义资源。这个参数只支持 GitHub 应用程序。 |
|
|
|
如果启用了 |
|
|
| 启用或禁用失败任务的日志片断视图,管道中有一个错误。当管道的数据泄漏时,您可以禁用此参数。 |
|
|
| 启用或禁用容器日志检查来检测错误消息,并将它们作为拉取请求上的注解公开。只有在使用 GitHub 应用程序时,才会应用此设置。 |
|
|
|
容器日志中检查的行的最大数量,以搜索错误消息。设置为 | 50 |
|
|
如果设置为 |
|
|
| 其他存储库用于限制生成的 GitHub 访问令牌。 |
2.4. 配置额外的 Pipelines as Code 控制器来支持额外的 GitHub 应用程序 复制链接链接已复制到粘贴板!
默认情况下,您可以将 Pipelines 配置为代码,以便与一个 GitHub 应用程序交互。在某些情况下,您可能需要使用多个 GitHub 应用程序,例如,如果您需要使用不同的 GitHub 帐户或不同的 GitHub 实例,如 GitHub Enterprise 或 GitHub SaaS。如果要使用多个 GitHub 应用程序,您必须为每个额外 GitHub 应用程序配置额外的 Pipelines 作为代码控制器。
流程
在
TektonConfig自定义资源中,将额外的PACController部分添加到 platform.openshift.pipelinesAsCodespec 中,如下例所示:其他PACController部分示例Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
可选: 如果要使用多个 GitHub 应用程序,请在
pipelinesAsCode.additionalPACControllersspec 下创建额外的部分,为每个 GitHub 实例配置 Pipelines 作为代码控制器。为每个控制器使用唯一名称。
第 3 章 使用带有 Git 存储库托管服务提供商的 Pipelines as Code。 复制链接链接已复制到粘贴板!
安装 Pipelines 作为代码后,集群管理员可以配置 Git 存储库托管服务提供商。目前,支持以下服务:
- GitHub 应用程序
- GitHub Webhook
- GitLab
- Bitbucket 服务器
- Bitbucket 云
GitHub App 是与 Pipelines as Code 搭配使用的建议服务。
3.1. 使用带有 GitHub 应用程序的 Pipelines as Code 复制链接链接已复制到粘贴板!
GitHub Apps 充当 Red Hat OpenShift Pipelines 的集点,并为 OpenShift Pipelines 提供了基于 Git 的工作流的优势。集群管理员可以为所有集群用户配置单个 GitHub 应用程序。对于 GitHub Apps 使用 Pipelines 作为代码,请确保 GitHub App 的 Webhook 指向 Pipelines as Code controller route (或入口端点),用于侦听 GitHub 事件。
有三种方法为 Pipelines 设置 GitHub 应用程序作为代码:
-
使用
tkn命令行工具。 - 使用 Web 控制台的 Administrator 视角。
- 在 GitHub 中手动设置应用程序,然后为 Pipelines 作为代码创建一个 secret。
默认情况下,Pipelines as Code 可以和一个 GitHub 应用程序通信。如果您将额外的 Pipelines 配置为与额外的 GitHub 应用程序通信,请单独配置每个 GitHub 应用程序。您必须为任何其他控制器手动设置 GitHub 应用程序。
3.1.1. 使用命令行界面配置 GitHub 应用程序 复制链接链接已复制到粘贴板!
您可以使用 tkn 命令行工具创建 GitHub 应用程序,并为 GitHub 应用程序配置 Pipelines 作为代码控制器。
如果您创建了额外的 Pipelines as Code 控制器来支持额外的 GitHub 应用程序,则只能对主控制器使用此流程。要为其他控制器创建 GitHub 应用程序,请使用手动过程。
先决条件
- 以集群管理员身份登录到 OpenShift Container Platform 集群。
-
已使用
插件安装了 tkn 命令行工具。tknpac
流程
输入以下命令:
tkn pac bootstrap github-app
$ tkn pac bootstrap github-appCopy to Clipboard Copied! Toggle word wrap Toggle overflow 此命令假设您的帐户使用标准 github.com API 端点。如果您使用不同的 GitHub API 端点,例如,如果使用 GitHub Enterprise,请使用
--github-api-url选项指定端点,如下例所示:示例命令
tkn pac bootstrap github-app --github-api-url https://github.com/enterprises/example-enterprise
$ tkn pac bootstrap github-app --github-api-url https://github.com/enterprises/example-enterpriseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
3.1.2. 在管理员视角中创建 GitHub 应用程序 复制链接链接已复制到粘贴板!
作为集群管理员,您可以使用 OpenShift Container Platform 集群配置 GitHub 应用程序,以使用 Pipelines as Code。此配置允许您执行构建部署所需的一组任务。
如果您创建了额外的 Pipelines as Code 控制器来支持额外的 GitHub 应用程序,则只能对主控制器使用此流程。要为其他控制器创建 GitHub 应用程序,请使用手动过程。
先决条件
您已从 Operator Hub 安装了 Red Hat OpenShift Pipelines pipelines-1.17 operator。
流程
- 在 Administrator 视角中,使用导航窗格进入到 Pipelines。
- 在 Pipelines 页面中点 Setup GitHub App。
-
输入您的 GitHub 应用程序名称。例如,
pipelines-ci-clustername-testui。 - 点 Setup。
- 在浏览器中提示时输入您的 Git 密码。
-
点 Create GitHub App for <username>,其中
<username>是您的 GitHub 的用户名。
验证
成功创建 GitHub 应用程序后,OpenShift Container Platform Web 控制台会打开并显示应用程序的详情。
GitHub App 的详细信息保存为 openShift-pipelines 命名空间中的 secret。
要查看与 GitHub 应用程序关联的名称、链接和 secret 等详情,请进入到 Pipelines 并点 View GitHub App。
3.1.3. 手动配置 GitHub 应用程序并为 Pipelines 作为代码创建 secret 复制链接链接已复制到粘贴板!
您可以使用 GitHub 用户界面创建 GitHub 应用程序。然后,您必须创建一个 secret 将 Pipelines as Code 配置为连接到 GitHub 应用程序。
如果您创建了额外的 Pipelines as Code 控制器来支持额外的 GitHub 应用程序,则必须对其他控制器使用此流程。
流程
- 登录您的 GitHub 帐户。
- 在 GitHub 菜单中,选择 Settings → Developer settings → GitHub Apps,然后点 New GitHub App。
在 GitHub App 表单中提供以下信息:
-
GitHub 应用程序名称:
OpenShift Pipelines - 主页 URL :OpenShift 控制台 URL
Webhook URL :作为代码路由或入口 URL 的 Pipelines。您可以运行以下命令来找到它:
echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')Copy to Clipboard Copied! Toggle word wrap Toggle overflow 另外,要为额外的 Pipelines 作为代码控制器配置 GitHub 应用程序,请将
pipelines-as-code-controller替换为您配置的控制器的名称,如下例所示:示例命令
echo https://$(oc get route -n openshift-pipelines pac_controller_2 -o jsonpath='{.spec.host}')$ echo https://$(oc get route -n openshift-pipelines pac_controller_2 -o jsonpath='{.spec.host}')Copy to Clipboard Copied! Toggle word wrap Toggle overflow Webhook secret :一个任意的机密。您可以运行以下命令来生成 secret:
openssl rand -hex 20
$ openssl rand -hex 20Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
GitHub 应用程序名称:
在 Repository permissions 部分中选择以下项目:
-
Checks:
Read & Write -
Contents:
Read & Write -
Issues:
Read & Write -
Metadata:
Read-only -
Pull request:
Read & Write
-
Checks:
在 Organization permissions 部分中选择以下项目:
-
Members:
Read-only -
计划
: 只读
-
Members:
订阅以下事件:
- Check run
- 检查套件
- Commit comment
- Issue comment
- Pull request
- push
- 点 Create GitHub App。
- 在新创建的 GitHub App 的 Details 页面中,记录顶部显示的 App ID。
- 在 Private key 部分,点 Generate Private key 自动生成并下载 GitHub 应用的私钥。安全地存储私钥,以备将来参考和使用。
- 在您要与 Pipelines as Code 一起使用的软件仓库上安装创建的应用程序。
输入以下命令将 Pipelines as Code 配置为访问新创建的 GitHub 应用程序:
oc -n openshift-pipelines create secret generic pipelines-as-code-secret \ --from-literal github-private-key="$(cat <PATH_PRIVATE_KEY>)" \ --from-literal github-application-id="<APP_ID>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"$ oc -n openshift-pipelines create secret generic pipelines-as-code-secret \1 --from-literal github-private-key="$(cat <PATH_PRIVATE_KEY>)" \2 --from-literal github-application-id="<APP_ID>" \3 --from-literal webhook.secret="<WEBHOOK_SECRET>"4 Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Pipelines as Code 通过检测从 GitHub Enterprise 集的标头集并将其用于 GitHub Enterprise API 授权 URL 来自动工作。
3.1.4. 将 GitHub 令牌限定到额外的存储库 复制链接链接已复制到粘贴板!
Pipelines as Code 使用 GitHub 应用程序来生成 GitHub 访问令牌。Pipelines as Code 使用这个令牌从存储库检索管道有效负载,并启用 CI/CD 进程与 GitHub 存储库交互。
默认情况下,访问令牌仅限于 Pipelines as Code 检索管道定义的存储库。在某些情况下,您可能希望令牌有权访问其他存储库。例如,可能会出现 CI 存储库,其中 .tekton/pr.yaml 文件和源有效负载位于,但 pr.yaml 中定义的构建过程从单独的私有 CD 存储库获取任务。
您可以通过两种方式扩展 GitHub 令牌的范围:
- 全局配置 :您可以将 GitHub 令牌扩展到不同命名空间中的存储库列表。您必须具有管理权限来设置此配置。
- 仓库级别配置:您可以将 GitHub 令牌扩展到与原始存储库相同的命名空间中的存储库列表。您不需要管理权限来设置此配置。
流程
-
在
TektonConfig自定义资源 (CR) 中,在pipelinesAsCode.settingsspec 中,将secret-github-app-token-scoped参数设置为false。此设置允许将 GitHub 令牌范围到全局和存储库级别配置中列出的私有和公共存储库。 要在
TektonConfigCR 中为 scoping GitHub 令牌设置全局配置,在pipelinesAsCode.settingsspec 中指定secret-github-app-scope-extra-repos参数中的额外软件仓库,如下例所示:Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要为 GitHub 令牌设置存储库级别配置,请在
RepositoryCR 的github_app_token_scope_repos参数中指定附加存储库,如下例所示:Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在本例中,
Repository自定义资源与test-repo命名空间中的linda/project存储库关联。生成的 GitHub 令牌的范围已扩展到owner/project和owner1/project1存储库,以及linda/project存储库。这些存储库必须存在于test-repo命名空间下。注意其他存储库可以是公共或私有存储库,但必须位于与
Repository资源关联的存储库相同的命名空间中。如果命名空间中不存在任何存储库,则 GitHub 令牌的范围会失败,并显示出错信息:
failed to scope GitHub token as repo owner1/project1 does not exist in namespace test-repo
failed to scope GitHub token as repo owner1/project1 does not exist in namespace test-repoCopy to Clipboard Copied! Toggle word wrap Toggle overflow
结果
生成的 GitHub 令牌可让您访问您在全局和存储库级别配置的额外软件仓库,以及 Pipelines as Code 有效负载文件所在的原始存储库。
如果您同时提供全局配置和存储库级别配置,则令牌将限定为来自这两个配置的所有存储库,如下例所示。
TektonConfig 自定义资源
Repository 自定义资源
GitHub 令牌的范围仅限于 owner/project, owner1/project1, owner2/project2, owner3/project3, 和 linda/project 仓库。
3.2. 使用带有 GitHub Webhook 的 Pipelines as Code 复制链接链接已复制到粘贴板!
如果无法创建 GitHub 应用程序,在您的仓库中使用带有 GitHub Webhook 的 Pipelines as Code。但是,使用带有 GitHub Webhook 的 Pipelines as Code 并不代表您可以访问 GitHub Check Runs API。任务的状态在拉取请求中作为注释添加,它在 Checks 选项卡中没有提供。
带有 GitHub Webhook 的 Pipelines as Code 不支持 /retest 和 /ok-to-test 等 GitOps 注释。要重启持续集成 (CI),请创建一个到存储库的新提交。例如,要在不进行任何更改的情况下创建新提交,您可以使用以下命令:
git --amend -a --no-edit && git push --force-with-lease <origin> <branchname>
$ git --amend -a --no-edit && git push --force-with-lease <origin> <branchname>
先决条件
- 确保在集群中安装了 Pipelines as Code。
为了授权,请在 GitHub 上创建一个个人访问令牌。
要生成一个安全的、细颗粒的令牌,将其范围限制为一个特定的存储库,并授予以下权限:
Expand 表 3.1. 细粒度令牌的权限 Name 权限 管理
只读
元数据
只读
内容
只读
提交状态
读和写
Pull request
读和写
Webhook
读和写
要使用经典令牌,将范围设置为
public_repo(公共存储库)和repo(私有存储库)。另外,提供一个短的令牌过期周期,并在其他位置记录下令牌。注意如果要使用
tkn pacCLI 配置 webhook,请添加admin:repo_hook范围。
流程
配置 Webhook 并创建一个
Repository自定义资源 (CR)。要配置 webhook 并使用
tkn pacCLI 工具自动创建一个RepositoryCR,请使用以下命令:tkn pac create repo
$ tkn pac create repoCopy to Clipboard Copied! Toggle word wrap Toggle overflow 互动输出示例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要配置 webhook 并 手动创建
RepositoryCR,请执行以下步骤:在 OpenShift 集群中,提取 Pipelines as Code 控制器的公共 URL。
echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在 GitHub 存储库或机构中执行以下步骤:
- 进入 Settings -> Webhooks 并点 Add webhook。
- 将 Payload URL 设置为 Pipelines as Code 的公共 URL。
- 将内容类型选为 application/json。
添加 webhook secret 并在另一个位置记录它。在本地机器上安装
openssl后,生成一个随机 secret。openssl rand -hex 20
$ openssl rand -hex 20Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 点 Let me select individual events 并选择这些事件:Commit comments, Issue comments, Pull request, 和 Pushes.
- 点击 Add webhook。
在 OpenShift 集群中,使用个人访问令牌和 webhook secret 创建一个
Secret对象。oc -n target-namespace create secret generic github-webhook-config \ --from-literal provider.token="<GITHUB_PERSONAL_ACCESS_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"
$ oc -n target-namespace create secret generic github-webhook-config \ --from-literal provider.token="<GITHUB_PERSONAL_ACCESS_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 创建
RepositoryCR。示例:
RepositoryCRCopy to Clipboard Copied! Toggle word wrap Toggle overflow 注意Pipelines as Code 假设 OpenShift
Secret对象和RepositoryCR 位于同一命名空间中。
可选: 对于现有的
RepositoryCR,请添加多个 GitHub Webhook secret 或为已删除的 secret 提供替换。使用
tkn pacCLI 工具添加 webhook。示例:使用
tkn pacCLI 的额外 Webhooktkn pac webhook add -n repo-pipelines
$ tkn pac webhook add -n repo-pipelinesCopy to Clipboard Copied! Toggle word wrap Toggle overflow 互动输出示例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
更新现有 OpenShift
Secret对象中的webhook.secret密钥。
可选: 对于现有的
RepositoryCR,更新个人访问令牌。使用
tkn pacCLI 工具更新个人访问令牌。示例:使用
tkn pacCLI 更新个人访问令牌tkn pac webhook update-token -n repo-pipelines
$ tkn pac webhook update-token -n repo-pipelinesCopy to Clipboard Copied! Toggle word wrap Toggle overflow 互动输出示例
? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace.
? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace.Copy to Clipboard Copied! Toggle word wrap Toggle overflow 或者,通过修改
RepositoryCR 来更新个人访问令牌。在
RepositoryCR 中查找 secret 的名称。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 使用
oc patch命令更新$target_namespace命名空间中的$NEW_TOKEN的值。oc -n $target_namespace patch secret github-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"$ oc -n $target_namespace patch secret github-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
3.3. 在 GitLab 中使用 Pipelines as Code 复制链接链接已复制到粘贴板!
如果您的机构或项目使用 GitLab 作为首选平台,您可以在 GitLab 上使用带有 webhook 的仓库的 Pipelines as Code。
先决条件
- 确保在集群中安装了 Pipelines as Code。
为授权,请生成个人访问令牌作为 GitLab 上项目或机构的管理器。
注意-
如果要使用
tkn pacCLI 配置 webhook,请将admin:repo_hook范围添加到令牌中。 - 使用范围被设置为针对特定项目的令牌无法提供对从已分叉存储库发送的合并请求 (MR) 的 API 访问。在这种情况下,Pipelines as Code 会以一条 MR 评论的方式显示结果。
-
如果要使用
流程
配置 Webhook 并创建一个
Repository自定义资源 (CR)。要配置 webhook 并使用
tkn pacCLI 工具自动创建一个RepositoryCR,请使用以下命令:tkn pac create repo
$ tkn pac create repoCopy to Clipboard Copied! Toggle word wrap Toggle overflow 互动输出示例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要配置 webhook 并 手动创建
RepositoryCR,请执行以下步骤:在 OpenShift 集群中,提取 Pipelines as Code 控制器的公共 URL。
echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在 GitLab 项目中,执行以下步骤:
- 使用左侧边栏进入 Settings -> Webhooks。
- 将 URL 设置为 Pipelines as Code 控制器公共 URL。
添加 webhook secret 并在另一个位置记录它。在本地机器上安装
openssl后,生成一个随机 secret。openssl rand -hex 20
$ openssl rand -hex 20Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 点 Let me select individual events 并选择这些事件:Commit comments, Issue comments, Pull request, 和 Pushes.
- 点 Save Changes。
在 OpenShift 集群中,使用个人访问令牌和 webhook secret 创建一个
Secret对象。oc -n target-namespace create secret generic gitlab-webhook-config \ --from-literal provider.token="<GITLAB_PERSONAL_ACCESS_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"
$ oc -n target-namespace create secret generic gitlab-webhook-config \ --from-literal provider.token="<GITLAB_PERSONAL_ACCESS_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 创建
RepositoryCR。示例:
RepositoryCRCopy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- 如果您使用 GitLab 的私有实例而不是 GitLab.com,请取消注释此字段并将其设置为 GitLab API 的 URL。GitLab API 与存储库相同。例如,如果仓库是
https://gitlab.example.com/owner/repo,API URL 为https://gitlab.example.com/。
注意-
Pipelines as Code 假设 OpenShift
Secret对象和RepositoryCR 位于同一命名空间中。
可选: 对于现有的
RepositoryCR,请添加多个 GitLab Webhook secret 或为已删除的 secret 提供替换。使用
tkn pacCLI 工具添加 webhook。示例:使用
tkn pacCLI 添加额外的 Webhooktkn pac webhook add -n repo-pipelines
$ tkn pac webhook add -n repo-pipelinesCopy to Clipboard Copied! Toggle word wrap Toggle overflow 互动输出示例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
更新现有 OpenShift
Secret对象中的webhook.secret密钥。
可选: 对于现有的
RepositoryCR,更新个人访问令牌。使用
tkn pacCLI 工具更新个人访问令牌。示例:使用
tkn pacCLI 更新个人访问令牌tkn pac webhook update-token -n repo-pipelines
$ tkn pac webhook update-token -n repo-pipelinesCopy to Clipboard Copied! Toggle word wrap Toggle overflow 互动输出示例
? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace.
? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace.Copy to Clipboard Copied! Toggle word wrap Toggle overflow 或者,通过修改
RepositoryCR 来更新个人访问令牌。在
RepositoryCR 中查找 secret 的名称。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 使用
oc patch命令更新$target_namespace命名空间中的$NEW_TOKEN的值。oc -n $target_namespace patch secret gitlab-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"$ oc -n $target_namespace patch secret gitlab-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
3.4. 在 Bitbucket Cloud 中使用 Pipelines as Code 复制链接链接已复制到粘贴板!
如果您的机构或项目使用 Bitbucket Cloud 作为首选平台,您可以在 Bitbucket Cloudb 上使用带有 webhook 的仓库的 Pipelines as Code。
先决条件
- 确保在集群中安装了 Pipelines as Code。
在 Bitbucket Cloud 上创建一个应用程序密码。
选中以下框,为令牌添加适当的权限:
-
账户:
Email,Read -
工作区成员资格:
Read、Write -
项目:
Read,Write -
Issues:
Read,Write Pull requests:
Read,Write注意-
如果要使用
tkn pacCLI 配置 webhook,请在令牌中添加Webhooks:Read和Write权限。 - 生成后,在另外一个位置保持密码或令牌的副本。
-
如果要使用
-
账户:
流程
配置 Webhook 并创建一个
RepositoryCR。要配置 webhook 并使用
tkn pacCLI 工具自动创建一个RepositoryCR,请使用以下命令:tkn pac create repo
$ tkn pac create repoCopy to Clipboard Copied! Toggle word wrap Toggle overflow 互动输出示例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要配置 webhook 并 手动创建
RepositoryCR,请执行以下步骤:在 OpenShift 集群中,提取 Pipelines as Code 控制器的公共 URL。
echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Bitbucket Cloud 上,执行以下步骤:
- 使用 Bitbucket Cloud 存储库的左侧导航窗格,进入 Repository settings -> Webhooks,然后点 Add webhook。
- 设置 Title。例如,"Pipelines as Code"。
- 将 URL 设置为 Pipelines as Code 控制器公共 URL。
- 选择这些事件: Repository: Push,Pull Request: Created,Pull Request: Updated, 和 Pull Request: Comment created.
- 点击 Save。
在 OpenShift 集群中,使用目标命名空间中的 app 密码创建一个
Secret对象。oc -n target-namespace create secret generic bitbucket-cloud-token \ --from-literal provider.token="<BITBUCKET_APP_PASSWORD>"
$ oc -n target-namespace create secret generic bitbucket-cloud-token \ --from-literal provider.token="<BITBUCKET_APP_PASSWORD>"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 创建
RepositoryCR。示例:
RepositoryCRCopy to Clipboard Copied! Toggle word wrap Toggle overflow
注意-
Bitbucket 云不支持
tkn pac create和tkn pac bootstrap命令。 Bitbucket 云不支持 Webhook secret。为了保护有效负载并防止 CI 被劫持,Pipelines as Code 会获取 Bitbucket 云 IP 地址列表,并确保 Webhook 接收仅来自这些 IP 地址。
-
要禁用默认行为,在
TektonConfig自定义资源中将bitbucket-cloud-check-source-ip参数设置为false,在pipelinesAsCode.settingsspec 中。 -
要允许额外的安全 IP 地址或网络,请将它们作为逗号分隔的值添加到
TektonConfig自定义资源中的bitbucket-cloud-additional-source-ip参数中,在pipelinesAsCode.settingsspec 中。
-
要禁用默认行为,在
可选: 对于现有的
RepositoryCR,请添加多个 Bitbucket Cloud Webhook secret 或为已删除的 secret 提供替换。使用
tkn pacCLI 工具添加 webhook。示例:使用
tkn pacCLI 添加额外的 Webhooktkn pac webhook add -n repo-pipelines
$ tkn pac webhook add -n repo-pipelinesCopy to Clipboard Copied! Toggle word wrap Toggle overflow 互动输出示例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意只有在
RepositoryCR 在 default 命名空间以外的命名空间中存在时,才在运行tkn pac webhook add命令时使用[-n <namespace>]选项。-
更新现有 OpenShift
Secret对象中的webhook.secret密钥。
可选: 对于现有的
RepositoryCR,更新个人访问令牌。使用
tkn pacCLI 工具更新个人访问令牌。示例:使用
tkn pacCLI 更新个人访问令牌tkn pac webhook update-token -n repo-pipelines
$ tkn pac webhook update-token -n repo-pipelinesCopy to Clipboard Copied! Toggle word wrap Toggle overflow 互动输出示例
? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace.
? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace.Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意只有在
RepositoryCR 在 default 命名空间以外的命名空间中存在时,才在tkn pac webhook update-token命令中使用[-n <namespace>]选项。或者,通过修改
RepositoryCR 来更新个人访问令牌。在
RepositoryCR 中查找 secret 的名称。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 使用
oc patch命令更新$target_namespace命名空间中的$password的值。oc -n $target_namespace patch secret bitbucket-cloud-token -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"$ oc -n $target_namespace patch secret bitbucket-cloud-token -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
3.5. 在 Bitbucket Server 中使用 Pipelines as Code 复制链接链接已复制到粘贴板!
如果您的机构或项目使用 Bitbucket Cloud 作为首选平台,您可以在 Bitbucket Server 上使用带有 webhook 的仓库的 Pipelines as Code。
先决条件
- 确保在集群中安装了 Pipelines as Code。
在 Bitbucket 服务器上,生成个人访问令牌作为项目管理器,并将它保存到一个其他位置中。
注意-
令牌必须具有
PROJECT_ADMIN和REPOSITORY_ADMIN权限。 - 令牌必须有权访问拉取请求中分叉的存储库。
-
令牌必须具有
流程
在 OpenShift 集群中,提取 Pipelines as Code 控制器的公共 URL。
echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Bitbucket 服务器上,执行以下步骤:
- 使用 Bitbucket Data Center 存储库的左侧导航窗格,进入 Repository settings -> Webhooks 并点 Add webhook。
- 设置 Title。例如,"Pipelines as Code"。
- 将 URL 设置为 Pipelines as Code 控制器公共 URL。
添加 webhook secret,并将它的副本保存到备用位置。如果您在本地机器上安装了
openssl,使用以下命令生成随机 secret:openssl rand -hex 20
$ openssl rand -hex 20Copy to Clipboard Copied! Toggle word wrap Toggle overflow 选择以下事件:
- Repository: Push
- Repository: Modified
- Pull Request: Opened
- Pull Request: Source branch updated
- Pull Request: Comment added
- 点击 Save。
在 OpenShift 集群中,使用目标命名空间中的 app 密码创建一个
Secret对象。oc -n target-namespace create secret generic bitbucket-server-webhook-config \ --from-literal provider.token="<PERSONAL_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"
$ oc -n target-namespace create secret generic bitbucket-server-webhook-config \ --from-literal provider.token="<PERSONAL_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 创建
RepositoryCR。示例:
RepositoryCRCopy to Clipboard Copied! Toggle word wrap Toggle overflow 注意Bitbucket 服务器不支持
tkn pac create和tkn pac bootstrap命令。
3.6. 使用自定义证书与 Pipelines as Code 进行交互 复制链接链接已复制到粘贴板!
要将 Pipelines as Code 配置为使用通过私有签名或自定义证书进行访问的 Git 存储库,您可以将证书公开给 Pipelines as Code。
流程
-
如果您使用 Red Hat OpenShift Pipelines Operator 安装了 Pipelines as Code,则可以使用
Proxy对象将自定义证书添加到集群中。Operator 在所有 Red Hat OpenShift Pipelines 组件和工作负载中公开证书,包括 Pipelines as Code。
其他资源
3.7. 在 Pipelines as Code 中使用私有存储库 复制链接链接已复制到粘贴板!
Pipelines as Code 通过使用用户令牌在目标命名空间中创建或更新 secret 来支持私有存储库。Tekton Hub 中的 git-clone 任务使用用户令牌来克隆私有存储库。
每当作为代码在目标命名空间中运行时,它会使用 pac-gitauth-<REPOSITORY_OWNER>-<REPOSITORY_NAME>-<RANDOM_STRING> 格式创建或更新 secret。
您必须使用管道运行和管道定义中的 basic-auth 工作区来引用 secret,然后传递给 git-clone 任务。
在管道中,您可以引用 git-clone 任务的 basic-auth 工作区来重复使用:
- 1
git-clone任务获取basic-auth工作区,并使用它来克隆私有存储库。
您可以通过在 pipelinesAsCode.settings spec 中将 TektonConfig 自定义资源的 secret-auto-create 参数设置为 false 或 true 来修改此配置。
第 4 章 使用 Repository 自定义资源 复制链接链接已复制到粘贴板!
Repository 自定义资源 (CR) 有以下主要功能:
- 告知 Pipelines as Code 关于处理来自一个 URL 事件的信息。
- 告知 Pipelines as Code 关于管道运行的命名空间信息。
- 使用 webhook 方法时,对于 Git 供应商平台需要需要引用 API secret、用户名或 API URL。
- 为存储库提供最后的管道运行状态。
4.1. 创建 Repository 自定义资源 复制链接链接已复制到粘贴板!
您可以使用 tkn pac CLI 或其他替代方法在目标命名空间中创建 Repository 自定义资源 (CR)。例如:
- 1
my-pipeline-ci是目标命名空间。
每当存在来自 URL (如 https://github.com/<repository>/<project> )的事件时,Pipelines as Code 会匹配它,然后开始签出 管道运行的 <repository>/<project > 存储库的内容以匹配 .tekton/ 目录中的内容。
-
您必须在与要执行的源代码存储库关联的管道所在的同一命名空间中创建
RepositoryCR,它不能针对不同的命名空间。 -
如果多个
RepositoryCR 与同一事件匹配,Pipelines as Code 只处理最旧的事件。如果您需要与特定命名空间匹配,请添加pipelinesascode.tekton.dev/target-namespace: "<mynamespace>"注解。通过这种显式目标,可防止恶意攻击者在其无法访问的命名空间中执行一个管道运行。
4.2. 创建全局存储库自定义资源 复制链接链接已复制到粘贴板!
另外,您可以在安装 OpenShift Pipelines 的命名空间中创建全局 Repository 自定义资源(CR),通常是 openshift-pipelines。如果创建此 CR,则您在其中指定的设置将默认应用于您创建的所有 Repository CR。
全局 Repository CR 只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议(SLA)支持,且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。
有关红帽技术预览功能支持范围的更多信息,请参阅技术预览功能支持范围。
先决条件
-
有对
openshift-pipelines命名空间的管理员访问权限。 -
使用
oc命令行工具登录到 OpenShift 集群。
流程
在
openshift-pipelines命名空间中创建一个名为pipeline-as-code的RepositoryCR。指定此 CR 中所有所需的默认设置。创建 CR 的命令示例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在本例中,您创建的所有
RepositoryCR 都包含用于访问 GitLab 存储库的通用 secret。您可以在 CR 中设置不同的存储库 URL 和其他设置。
4.3. 设置并发限制 复制链接链接已复制到粘贴板!
您可以使用 Repository 自定义资源定义 (CRD) 中的 concurrency_limit spec 来定义为存储库同时运行的最大管道运行数量。
如果有多个管道与事件匹配,管道会按照字母顺序与事件启动匹配。
例如,如果您在 .tekton 目录中有三个管道运行,并在存储库配置中创建了一个 concurrency_limit 为 1 的拉取请求,则所有管道运行都会按字母顺序执行。在任意给定时间点,只有一个管道运行处于 running 状态,而其余会处于排队状态。
4.4. 更改管道定义的源分支 复制链接链接已复制到粘贴板!
默认情况下,当处理推送事件或拉取请求事件时,Pipelines as Code 从触发事件的分支获取管道定义。您可以使用 Repository 自定义资源定义(CRD) 中的 pipelinerun_provenance 设置从 Git 存储库供应商上配置的默认分支获取定义,如 main, master, 或 trunk。
您可以使用此设置作为安全预防。在默认的行为中,Pipelines as Code 使用提交拉取请求中的管道定义。使用 default-branch 设置时,管道定义必须在运行前合并到默认分支中。此要求可确保在合并审查过程中对任何更改进行最大可能验证。
4.5. 自定义参数扩展 复制链接链接已复制到粘贴板!
您可以使用 params 字段使用 Pipelines as Code 在 PipelineRun 资源中扩展自定义参数。您可以为 Repository 自定义资源 (CR) 模板中的 custom 参数指定一个值。指定的值替换管道运行中的 custom 参数。
在以下情况下可以使用自定义参数:
- 定义 URL 参数,如因推送或拉取请求而异的 registry URL。
-
要定义一个参数,如管理员可在不需要 Git 仓库中执行
PipelineRun的更改的情况下管理的帐户 UUID。
只有在无法使用 Tekton PipelineRun 参数时,才使用自定义参数扩展功能,因为 Tekton 参数在 Pipeline 资源中定义,并在 Git 仓库内自定义它。但是,自定义参数会被定义和自定义 Repository CR 所在的位置。因此,您无法从单一点管理 CI/CD 管道。
以下示例显示了 Repository CR 中名为 company 的自定义参数:
ABC Company 取代了您的管道运行和远程获取任务中的参数名称 company。
您还可以从 Kubernetes secret 检索自定义参数的值,如下例所示:
Pipelines as Code 解析并使用以下自定义参数:
-
如果您定义了
值和一个secret_ref,Pipelines as Code 将使用值。 -
如果您在
params部分中没有name,Pipelines as Code 不会解析参数。 -
如果您有多个带有相同
名称的参数,Pipelines as Code 将使用最后一个参数。
您还可以定义自定义参数,仅在指定条件与 CEL 过滤器匹配时才使用其扩展。以下示例显示了当触发拉取请求事件时,适用于名为 company 的自定义参数的 CEL 过滤器:
当您有多个具有相同名称和不同过滤器的参数时,Pipelines as Code 会使用与过滤器匹配的第一个参数。因此,Pipelines as Code 允许您根据不同的事件类型扩展参数。例如,您可以组合一个推送和拉取请求事件。
第 5 章 使用 Pipelines as Code 解析器 复制链接链接已复制到粘贴板!
Pipelines as Code 解析器可确保运行的管道运行不会与其他其它运行冲突。
5.1. 关于 Pipelines as Code 解析器 复制链接链接已复制到粘贴板!
要分割您的管道和管道运行,请将文件存储在 .tekton/ 目录或其子目录中。
如果 Pipelines as Code 在 .tekton/ 目录中的任何 YAML 文件中发现一个带有对任务或管道的引用的管道运行,Pipelines as Code 会自动解析引用的任务,以使用 PipelineRun 对象中嵌入的 spec 提供单个管道运行。
如果 Pipelines as Code 无法解析 Pipeline 或 PipelineSpec 定义中引用的任务,则运行会在对集群应用更改前失败。您可以在 Git 供应商平台上查看问题,在 Repository CR 所在的目标命名空间的事件内。
当解析器观察到以下类型的任务时会跳过解析过程:
- 任务或管道捆绑包。
-
具有没有
tekton.dev/前缀的 API 版本的自定义任务。
解析器以字面形式使用此类任务,不进行任何转换。
如果要在拉取请求中发送它之前在本地对管道运行进行测试,请使用 tkn pac resolve 命令。
您还可以引用远程管道和任务。
5.2. 在 with Pipelines as Code 中使用远程任务注解 复制链接链接已复制到粘贴板!
Pipelines as Code 支持在一个管道运行中使用注解来获取远程任务或管道。如果您在管道运行或 PipelineRun 或 PipelineSpec 对象中引用远程任务,Pipelines as Code 码解析器会自动包含它。如果在获取远程任务或解析它们时出现错误,Pipelines as Code 将停止处理任务。
要包含远程任务,请参阅以下注解示例:
引用 Tekton Hub 中的远程任务
在 Tekton Hub 中引用单个远程任务。
... pipelinesascode.tekton.dev/task: "git-clone" ...
... pipelinesascode.tekton.dev/task: "git-clone"1 ...Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- Pipelines as Code 包括来自 Tekton Hub 的任务的最新版本。
引用 Tekton Hub 中的多个远程任务
... pipelinesascode.tekton.dev/task: "[git-clone, golang-test, tkn]" ...
... pipelinesascode.tekton.dev/task: "[git-clone, golang-test, tkn]" ...Copy to Clipboard Copied! Toggle word wrap Toggle overflow 使用
-<NUMBER>后缀引用 Tekton Hub 中的多个远程任务。... pipelinesascode.tekton.dev/task: "git-clone" pipelinesascode.tekton.dev/task-1: "golang-test" pipelinesascode.tekton.dev/task-2: "tkn" ...
... pipelinesascode.tekton.dev/task: "git-clone" pipelinesascode.tekton.dev/task-1: "golang-test" pipelinesascode.tekton.dev/task-2: "tkn"1 ...Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- 默认情况下,Pipelines as Code 会将字符串解析为从 Tekton Hub 获取最新的任务。
引用 Tekton Hub 中的远程任务的特定版本。
... pipelinesascode.tekton.dev/task: "[git-clone:0.1]" ...
... pipelinesascode.tekton.dev/task: "[git-clone:0.1]"1 ...Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- 引用 Tekton Hub 中的
git-clone远程任务的0.1版本。
使用 URL 的远程任务
... pipelinesascode.tekton.dev/task: "<https://remote.url/task.yaml>" ...
...
pipelinesascode.tekton.dev/task: "<https://remote.url/task.yaml>"
...
- 1
- 远程任务的公共 URL。注意
如果使用 GitHub,远程任务 URL 使用与
Repository自定义资源定义 (CRD) 相同的主机,Pipelines as Code 会使用 GitHub 令牌并使用 GitHub API 获取 URL。例如,如果您有一个类似于
https://github.com/<organization>/<repository>的存储库 URL,远程 HTTP URL 引用类似于https://github.com/<organization>/<repository>/blob/<mainbranch>/<path>/<file> 的 GitHub blob,Pipelines as Code 会使用 GitHub App 令牌从该私有存储库中获取任务定义文件。当您使用公共 GitHub 存储库时,Pipelines as Code 的行为与 GitHub 原始 URL 类似,如
https://raw.githubusercontent.com/<organization>/<repository>/<mainbranch>/<path>/<file>。- GitHub App 令牌的范围为所有者或存储库所在的机构。使用 GitHub Webhook 方法时,您可以在允许个人令牌的任何机构中获取任何私有或公共存储库。
从存储库内的 YAML 文件中引用任务
... pipelinesascode.tekton.dev/task: "<share/tasks/git-clone.yaml>" ...
...
pipelinesascode.tekton.dev/task: "<share/tasks/git-clone.yaml>"
...
- 1
- 到包含任务定义的本地文件的相对路径。
5.3. 在 Pipelines as Code 中使用远程管道注解 复制链接链接已复制到粘贴板!
您可以使用远程管道注解在多个存储库间共享管道定义。
...
pipelinesascode.tekton.dev/pipeline: "<https://git.provider/raw/pipeline.yaml>"
...
...
pipelinesascode.tekton.dev/pipeline: "<https://git.provider/raw/pipeline.yaml>"
...
- 1
- 远程管道定义的 URL。您还可以为同一存储库中的文件提供位置。
您只能使用注解引用一个管道定义。
5.3.1. 覆盖远程管道中的任务 复制链接链接已复制到粘贴板!
默认情况下,如果您在管道运行中使用远程管道注解,Pipelines as Code 会使用作为远程管道一部分的所有任务。
您可以通过在管道运行中添加任务注解来覆盖远程管道中的任务。添加的任务必须与远程管道中的任务的名称相同。
例如,您可以使用以下管道运行定义:
引用远程管道和覆盖任务的管道运行定义示例
在本例中,假设位于 https://git.provider/raw/pipeline.yaml 的远程任务包括一个名为 git-clone 的任务,并且 my-git-clone-task.yaml 文件定义的任务也命名为 git-clone。
在这种情况下,管道运行执行远程管道,但将管道中名为 git-clone 的任务替换为您定义的任务。
第 6 章 管理管道运行 复制链接链接已复制到粘贴板!
使用 Pipelines as Code,您可以在代码存储库中创建管道并运行这些管道。
6.1. 使用 Pipelines as Code 创建管道运行 复制链接链接已复制到粘贴板!
要使用 Pipelines as Code 运行管道,您可以在存储库的 .tekton/ 目录中创建管道运行定义或模板作为 YAML 文件。您可以使用远程 URL 在其他存储库中引用 YAML 文件,但管道运行仅由包含 .tekton/ 目录中的事件触发。
Pipelines as Code 解析器会将所有任务与管道运行绑定,作为一个单独的管道运行,而无需外部依赖项。
-
对于管道,使用最少一个带有 spec 的管道,或一个独立的
Pipeline对象。 - 对于任务,在管道中嵌入任务 spec,或者将其单独定义为一个 Task 对象。
参数化提交和 URL
您可以使用 {{<var>}} 的格式来使用动态的、可扩展的参数,在您的提交中指定参数。目前,您可以使用以下变量:
-
{{repo_owner}}: 存储库所有者。 -
{{repo_name}}: 存储库名称。 -
{{repo_url}}:存储库完整 URL。 -
{{revision}}:提交的完全 SHA 修订。 -
{{sender}}:提交发送者的用户名或帐户 ID。 -
{{source_branch}}:事件源自的分支名称。 -
{{target_branch}}:事件目标的分支名称。对于推送事件,它与source_branch相同。 -
{{pull_request_number}}:拉取或合并请求号,仅对pull_request事件类型定义。 -
{{git_auth_secret}}:使用 Git 提供程序的令牌自动生成的 secret 名称,用于签出私有存储库。
将事件与管道运行匹配
您可以通过在管道运行中使用特殊注解,将不同的 Git 供应商事件与每个管道运行匹配。如果有多个管道与事件匹配,Pipelines as Code 会并行运行它们,并在管道运行完成后将结果发送到 Git 供应商。
将 pull 事件与管道运行匹配
您可以使用以下示例将 pipeline-pr-main 管道运行与以 main 分支为目标的 pull_request 事件匹配:
- 1
- 您可以通过添加以逗号分隔的条目来指定多个分支。例如:
"[main, release-nightly]"。另外,您可以指定以下内容:-
对分支的完整引用,如
"refs/heads/main" -
带有模式匹配的 globs,如
"refs/heads/\ the" -
标签,如
"refs/tags/1.\*"
-
对分支的完整引用,如
将推送事件与管道运行匹配
您可以使用以下示例将 pipeline-push-on-main 管道运行与以 refs/heads/main 分支为目标的 push 事件匹配:
- 1
- 您可以通过添加以逗号分隔的条目来指定多个分支。例如:
"[main, release-nightly]"。另外,您可以指定以下内容:-
对分支的完整引用,如
"refs/heads/main" -
带有模式匹配的 globs,如
"refs/heads/\ the" -
标签,如
"refs/tags/1.\*"
-
对分支的完整引用,如
将注释事件与管道运行匹配
当注释的文本与 ^/merge-pr 正则表达式匹配时,您可以使用以下示例匹配管道运行的 pipeline-comment 管道:
只有在注释作者满足以下要求之一时才启动管道运行:
- 作者是存储库的所有者。
- 作者是存储库的合作者。
- 作者是存储库机构中的公共成员。
-
注释作者在存储库根目录的
OWNERS文件的approvers或reviewers部分中列出,如 Kubernetes 文档所述。Pipelines as Code 支持OWNERS和OWNERS_ALIASES文件的规格。如果OWNERS文件包含一个 filters 部分,Pipelines as Code 会匹配 approvers,并使用 reviewers 仅针对198.51.100.0/24过滤器。
将注释事件与管道运行匹配只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议(SLA)支持,且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。
有关红帽技术预览功能支持范围的更多信息,请参阅技术预览功能支持范围。
高级事件匹配
Pipelines as Code 支持在高级事件匹配中使用基于通用表达式语言 (CEL) 的过滤。如果您在管道运行中有 pipelinesascode.tekton.dev/on-cel-expression 注解,PPipelines as Code 使用 CEL 表达式并跳过 on-target-branch 注解。与简单的 on-target-branch 注解匹配相比,CEL 表达式允许复杂的过滤和负效果。
要将基于 CEL 的过滤作为代码使用,请考虑以下注解示例:
匹配以
main分支为目标并来自wip分支的pull_request事件:Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要仅在路径更改时运行管道,您可以使用带有 glob 模式的
.pathChanged后缀功能:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- 匹配
docs目录中的所有 markdown 文件。
匹配以标题
[DOWNSTREAM]开头的所有拉取请求:Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要在
pull_request事件上运行管道,但跳过experimental分支:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
对于使用 Pipelines as Code 时进行基于 CEL 的高级过滤,您可以使用以下字段和后缀功能:
-
event: 一个push或pull_request事件。 -
target_branch:目标分支。 -
source_branch: 一个pull_request事件的源分支。对于push事件,它与target_branch相同。 -
event_title:匹配事件的标题,如一个push事件的提交标题,以及pull_request事件的 pull 或 merge 请求的标题。目前,只有 GitHub、Gitlab 和 Bitbucket 云是受支持的提供程序。 -
.pathChanged:字符串的后缀函数。如果路径已改变,字符串可以是一个路径的 glob。目前,只支持 GitHub 和 Gitlab。
另外,您还可以访问 Git 存储库供应商传递的完整有效负载。使用 headers 字段访问有效负载的标头,如 headers['x-github-event']。使用 body 字段访问有效负载的正文,如 body.pull_request.state。
使用带有 Pipelines as Code 的基于 CEL 的过滤的有效负载的标头和正文只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议(SLA)支持,且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。
有关红帽技术预览功能支持范围的更多信息,请参阅技术预览功能支持范围。
在以下示例中,只有在以下条件都为 true 时,管道运行才会启动:
-
拉取请求以
main分支为目标。 -
拉取请求的作者是
超级用户。 -
操作是
synchronize;此操作会在拉取请求上执行更新时触发。
如果您使用 标头 或 正文 字段进行事件匹配,您可能无法使用 Git 命令(如 retest )触发管道运行。如果使用 Git 命令,则有效负载正文是包含此命令而非原始有效负载的注释。
如果要在使用 body 字段进行事件匹配时再次运行管道,您可以关闭并重新打开拉取请求或合并请求,或者添加新的 SHA 提交,例如使用以下命令:
git commit --amend --no-edit && git push --force-with-lease
git commit --amend --no-edit && git push --force-with-lease
使用临时 GitHub App 令牌用于 Github API 操作
您可以使用来自 GitHub App 的 Pipelines as Code 生成的临时安装令牌来访问 GitHub API。令牌值存储在为私有存储库生成的临时 {{git_auth_secret}} 动态变量的 git-provider-token 键中。
例如,要在拉取请求中添加注释,您可以使用 Tekton Hub 中的 github-add-comment 任务使用 Pipelines as Code 注解:
... pipelinesascode.tekton.dev/task: "github-add-comment" ...
...
pipelinesascode.tekton.dev/task: "github-add-comment"
...
然后,您可以在 tasks 部分添加任务,或管道运行定义中的 finally 任务:
- 1
- 通过使用动态变量,您可以为来自任何存储库的任何拉取请求重复使用此片断模板。
在 GitHub 应用程序中,生成的安装令牌的有效期为 8 小时,其范围限制于事件源自于集群中配置的存储库。
其他资源
6.2. 使用 Pipelines as Code 运行管道运行 复制链接链接已复制到粘贴板!
使用默认配置,当指定事件(如拉取请求或推送在仓库上发生)时,Pipelines as Code 会在默认分支的 .tekton/ 目录中运行任何管道运行。例如,如果在默认分支上运行的管道具有注解 pipelinesascode.tekton.dev/on-event: "[pull_request]",它将在每次发生拉取请求事件时运行。
如果是拉取请求或合并请求,Pipelines as Code 也会从默认分支以外的分支运行管道,如果拉取请求作者满足以下条件:
- 作者是存储库的所有者。
- 作者是存储库的合作者。
- 作者是存储库机构中的公共成员。
-
拉取请求作者在存储库根目录的
OWNERS文件的approvers或reviewers部分中列出,如 Kubernetes 文档中所述。Pipelines as Code 支持OWNERS和OWNERS_ALIASES文件的规格。如果OWNERS文件包含一个 filters 部分,Pipelines as Code 会匹配 approvers,并使用 reviewers 仅针对198.51.100.0/24过滤器。
如果拉取请求作者没有满足要求,则满足要求的其他用户可以在拉取请求中注释掉 /ok-to-test,并启动管道运行。
Pipeline 运行执行
管道运行始终在与生成事件的存储库关联的 Repository 自定义资源定义 (CRD) 的命名空间中运行。
您可以使用 tkn pac CLI 工具观察管道运行的执行。
要遵循最后一次管道运行的执行,请使用以下示例:
tkn pac logs -n <my-pipeline-ci> -L
$ tkn pac logs -n <my-pipeline-ci> -L1 Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
my-pipeline-ci是RepositoryCRD 的命名空间。
要以交互方式执行任何管道运行,请使用以下示例:
tkn pac logs -n <my-pipeline-ci>
$ tkn pac logs -n <my-pipeline-ci>1 Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
my-pipeline-ci是RepositoryCRD 的命名空间。如果需要查看除最后一个管道运行以外的管道运行,您可以使用tkn pac logs命令选择附加到仓库的PipelineRun:
如果您配置使用 GitHub App 的 Pipelines as Code,Pipelines as Code 会在 GitHub App 的 Checks 选项卡中发布了一个 URL。您可以点 URL 并按照管道执行进行操作。
6.3. 使用 Pipelines as Code 重启或取消管道运行 复制链接链接已复制到粘贴板!
您可以重启或取消没有事件的管道运行,如向分支发送新提交或提升拉取请求。要重启所有管道运行,请使用 GitHub App 中的所有检查 功能。
要重启所有或特定的管道运行,请使用以下评论:
-
/test和/retest注释会重启所有管道运行。 -
/test <pipeline_run_name> 和 /retest <pipeline_run_name> 注释启动或重启特定的管道运行。您可以使用此命令在存储库上启动任何 Pipelines as Code 管道,无论它是由此管道运行的事件触发。
要取消所有或特定的管道运行,请使用以下评论:
-
/cancel注释取消所有管道运行。 -
/cancel <pipeline_run_name> 注释会取消特定的管道运行。
注释的结果在 GitHub App 的 Checks 选项卡中看到。
只有在注释作者满足以下要求之一时,注释才会启动、重启或取消任何管道运行:
- 作者是存储库的所有者。
- 作者是存储库的合作者。
- 作者是存储库机构中的公共成员。
-
注释作者在存储库根目录的
OWNERS文件的approvers或reviewers部分中列出,如 Kubernetes 文档所述。Pipelines as Code 支持OWNERS和OWNERS_ALIASES文件的规格。如果OWNERS文件包含一个 filters 部分,Pipelines as Code 会匹配 approvers,并使用 reviewers 仅针对198.51.100.0/24过滤器。
使用注释启动与事件不匹配的管道运行只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议(SLA)支持,且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。
有关红帽技术预览功能支持范围的更多信息,请参阅技术预览功能支持范围。
流程
- 如果您以拉取请求为目标,并使用 GitHub App,进入 Checks 选项卡,然后点 Re-run all checks。
如果您以 pull 或 merge 请求为目标,请使用拉取请求中的注释:
取消所有管道运行的注释示例
This is a comment inside a pull request. /cancel
This is a comment inside a pull request. /cancelCopy to Clipboard Copied! Toggle word wrap Toggle overflow 如果您以推送请求为目标,请在提交消息中包含注释。
注意此功能仅支持 GitHub 供应商。
- 进入您的 GitHub 存储库。
- 单击 Commits 部分。
- 点击要重启管道运行的提交。
点击您要添加注释的行号。
启动或重启特定管道运行的注释示例
This is a comment inside a commit. /retest example_pipeline_run
This is a comment inside a commit. /retest example_pipeline_runCopy to Clipboard Copied! Toggle word wrap Toggle overflow 注意如果您在推送请求中的多个分支中运行命令,则会使用带有最新提交的分支。
这会产生两个情况:
-
如果您在没有任何参数的提交上运行命令,如
/test,则会自动对main分支执行测试。 -
如果您包含分支规格,如
/test branch:user-branch,则测试将在带有user-branch分支的上下文的提交上执行。
-
如果您在没有任何参数的提交上运行命令,如
6.4. 使用 Pipelines as Code 监控管道运行状态 复制链接链接已复制到粘贴板!
根据上下文和支持的工具,您可以以不同的方式监控管道运行的状态。
GitHub 应用程序的状态
当管道运行完成后,在 Check 选项卡中添加状态,其中包含管道的每个任务以及 tkn pipelinerun describe 命令的输出的有限信息。
日志错误片断
当 Pipelines as Code 检测到管道其中一个任务中的错误时,会显示一段信息,它包括第一个失败的任务的任务详情中的最后 3 行信息。
Pipelines as Code 通过查看管道运行并使用隐藏字符替换 secret 值来避免泄漏 secret。但是,Pipelines as Code 无法隐藏来自工作区和 envFrom 源的 secret。
日志错误片断的注解
在 TektonConfig 自定义资源中,在 pipelinesAsCode.settings spec 中,您可以将 error-detection-from-container-logs 参数设置为 true。在这种情况下,Pipelines as Code 会检测容器日志中的错误,并在发生错误的拉取请求中添加它们作为注解。
为日志错误片断添加注解只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议(SLA)支持,且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。
有关红帽技术预览功能支持范围的更多信息,请参阅技术预览功能支持范围。
目前,Pipelines as Code 只支持使用以下格式的 makefile 或 grep 输出的简单情况:
<filename>:<line>:<column>: <error message>
<filename>:<line>:<column>: <error message>
您可以使用 error-detection-simple-regexp 参数自定义用于检测错误的正则表达式。正则表达式使用命名组来授予如何指定匹配的灵活性。需要匹配的组是 filename, line, 和 error。您可以查看 Pipelines as Code 配置映射用于默认正则表达式。
默认情况下,Pipelines as Code 只扫描容器日志的最后 50 行。您可以在 error-detection-max-number-of-lines 字段中增加这个值,或为无限数量的行设置 -1。但是,此类配置可能会增加监视器的内存用量。
Webhook 的状态
对于 Webhook,当事件是拉取请求时,状态将添加为拉取请求或合并请求的注释。
失败
如果命名空间与 Repository 自定义资源定义 (CRD) 匹配,Pipelines as Code 会在命名空间中的 Kubernetes 事件中发出其故障日志消息。
与 Repository CRD 关联的状态
管道运行的最后 5 个状态消息存储在 Repository 自定义资源中。
oc get repo -n <pipelines-as-code-ci>
$ oc get repo -n <pipelines-as-code-ci>
NAME URL NAMESPACE SUCCEEDED REASON STARTTIME COMPLETIONTIME pipelines-as-code-ci https://github.com/openshift-pipelines/pipelines-as-code pipelines-as-code-ci True Succeeded 59m 56m
NAME URL NAMESPACE SUCCEEDED REASON STARTTIME COMPLETIONTIME
pipelines-as-code-ci https://github.com/openshift-pipelines/pipelines-as-code pipelines-as-code-ci True Succeeded 59m 56m
使用 tkn pac describe 命令,您可以提取与存储库及其元数据关联的运行状态。
通知
Pipelines as Code 不管理通知。如果您需要通知,请使用管道的 finally 功能。
6.5. 使用 Pipelines as Code 清理管道运行 复制链接链接已复制到粘贴板!
在一个用户命名空间中可以运行多个管道。通过设置 max-keep-runs 注解,您可以将 Pipelines as Code 配置为保留与事件匹配的有限数量的管道运行。例如:
... pipelinesascode.tekton.dev/max-keep-runs: "<max_number>" ...
...
pipelinesascode.tekton.dev/max-keep-runs: "<max_number>"
...
- 1
- Pipelines as Code 在成功完成执行后启动清理,只保留使用注解配置的最大管道运行数量。注意
- Pipelines as Code 会跳过清理运行的管道,但会清理带有未知状态的管道运行。
- Pipelines as Code 会跳过清理失败的拉取请求。
6.6. 在 Pipelines as Code 中使用传人(incoming)webhook 复制链接链接已复制到粘贴板!
使用传入的 webhook URL 和共享 secret,您可以在存储库中启动管道运行。
要使用传入的 Webhook,在 Repository 自定义资源定义 (CRD) 的 spec 部分中指定以下内容:
- Pipelines as Code 匹配的传入 Webhook URL。
Git 提供程序和用户令牌。目前,Pipelines as Code 支持
github、gitlab和bitbucket-cloud。注意在 GitHub 应用程序上下文中使用传入的 Webhook URL 时,您必须指定令牌。
- 目标分支和传入 Webhook URL 的 secret。
示例: 带有传入 Webhook 的 Repository CRD
示例:传入 webhook 的 repo-incoming-secret secret
要触发位于 Git 存储库的 .tekton 目录中的管道运行,请使用以下命令:
curl -X POST 'https://control.pac.url/incoming?secret=very-secure-shared-secret&repository=repo&branch=main&pipelinerun=target_pipelinerun'
$ curl -X POST 'https://control.pac.url/incoming?secret=very-secure-shared-secret&repository=repo&branch=main&pipelinerun=target_pipelinerun'
Pipelines as Code 与传入的 URL 匹配,并将其视为 push 事件。但是,Pipelines as Code 不会报告这个命令触发的管道运行的状态。
要获取报告或通知,请将 finally 任务直接添加到您的管道中。另外,您可以使用 tkn pac CLI 工具检查 Repository CRD。
第 7 章 Pipelines as Code 命令参考 复制链接链接已复制到粘贴板!
您可以使用 tkn pac CLI 工具控制 Pipelines as Code。您还可以使用 TektonConfig 自定义资源将 Pipelines 配置为代码日志,并使用 oc 命令查看 Pipelines as Code 日志。
7.1. Pipelines as Code 命令参考 复制链接链接已复制到粘贴板!
tkn pac CLI 工具提供以下功能:
- Bootstrap Pipelines as Code 安装和配置。figuration.
- 创建一个新的 Pipelines as Code 仓库。
- 列出所有 Pipelines as Code 仓库。
- 描述一个 Pipelines as Code 仓库和相关联的运行。
- 生成简单的管道运行以开始。
- 如由 Pipelines as Code 执行来解析一个管道运行。
您可以使用与功能对应的命令进行测试和试验,因此您不必对包含应用源代码的 Git 仓库进行更改。
7.1.1. 基本语法 复制链接链接已复制到粘贴板!
tkn pac [command or options] [arguments]
$ tkn pac [command or options] [arguments]
7.1.2. 全局选项 复制链接链接已复制到粘贴板!
tkn pac --help
$ tkn pac --help
7.1.3. 工具命令 复制链接链接已复制到粘贴板!
7.1.3.1. bootstrap 复制链接链接已复制到粘贴板!
| 命令 | 描述 |
|---|---|
|
| 安装并配置 Pipelines 作为 Git 仓库托管服务提供商的 Code,如 GitHub 和 GitHub Enterprise。 |
|
| 安装每天(nightly)构建的 Pipelines as Code。 |
|
| 覆盖 OpenShift 路由 URL。
默认情况下, 如果您没有 OpenShift Container Platform 集群,它会要求您输入指向入口端点的公共 URL。 |
|
|
在 |
7.1.3.2. 软件仓库 复制链接链接已复制到粘贴板!
| 命令 | 描述 |
|---|---|
|
| 根据管道运行模板创建一个新的 Pipelines as Code 仓库以及一个命名空间。 |
|
| 列出所有 Pipelines as Code 软件仓库,并显示关联运行的最后一个状态。 |
|
| 描述一个 Pipelines as Code 仓库和相关联的运行。 |
7.1.3.3. generate 复制链接链接已复制到粘贴板!
| 命令 | 描述 |
|---|---|
|
| 生成简单的管道运行。 从包含源代码的目录执行时,它会自动检测当前的 Git 信息。 另外,它使用基本的语言检测功能,并根据语言添加额外的任务。
例如,如果它在仓库的 root 中检测到一个 |
7.1.3.4. 解析 复制链接链接已复制到粘贴板!
| 命令 | 描述 |
|---|---|
|
| 执行管道运行,就像由 Pipelines as Code 服务中所有的一样。 |
|
|
显示在 结合在本地机器上运行的 Kubernetes 安装,您可以在不生成新提交的情况下观察管道运行。 如果从源代码存储库运行命令,它会尝试检测当前的 Git 信息并自动解析当前修订或分支等参数。 |
|
| 通过覆盖从 Git 存储库派生的默认参数值来执行管道运行。
您可以使用 |
7.2. 将 Pipelines 配置为代码日志记录 复制链接链接已复制到粘贴板!
您可以通过编辑 TektonConfig 自定义资源(CR)中的 pac-config-logging 配置映射将 Pipelines 配置为代码日志。
先决条件
- 在集群中安装了 Pipelines as Code。
流程
- 在 Web 控制台的 Administrator 视角中,进入 Administration → CustomResourceDefinitions。
-
使用 Search by name 字段搜索
tektonconfigs.operator.tekton.dev自定义资源定义(CRD),然后点 TektonConfig 查看 CRD Details 页面。 - 点 实例 选项卡。
-
点 config 实例查看
TektonConfigCR 详情。 - 点 YAML 标签。
根据您的要求,编辑
.options.configMaps.pac-config-logging.data参数下的loglevel.字段。将 Pipelines as Code 日志级别字段设置为
warn的TektonConfigCR 示例Copy to Clipboard Copied! Toggle word wrap Toggle overflow 可选:通过更改
.options.deployments字段中每个组件的.env.value,为 Pipelines 作为代码组件创建一个自定义日志配置映射。以下示例显示了带有名为custom-pac-config-logging的自定义配置映射的配置。带有 Pipelines as Code 自定义日志配置映射的
TektonConfigCR 示例Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.3. 按命名空间分割 Pipelines as Code 日志 复制链接链接已复制到粘贴板!
Pipelines as Code 日志包含命名空间信息,以便可以根据特定命名空间过滤日志或分割日志。例如,要查看与 mynamespace 命名空间相关的 Pipelines as Code 日志,请输入以下命令:
oc logs pipelines-as-code-controller-<unique-id> -n openshift-pipelines | grep mynamespace
$ oc logs pipelines-as-code-controller-<unique-id> -n openshift-pipelines | grep mynamespace
- 1
- 将
pipelines-as-code-controller-<unique-id>替换为 Pipelines as Code 控制器名称。