pipelines-as-code.png

📜 目录

• 😮 Pipelines as Code 是什么？
• 🏗️ 准备环境
• 🚀 快速安装
• ⚡ 能力体验
• 🤔 一些疑问
• 🥰 参考

😮 Pipelines as Code 是什么？

是一套基于 OpenShift Pipeline/Tekton 自用的 CI 工具，可以帮助你快速构建部署你的代码

它使用位于源代码控制管理 (SCM) 系统（例如 GitHub ）的文件中的 Tekton PipelineRuns 和任务来定义 CI/CD，通过将 Pipeline 定义存储在代码仓库中，可以更轻松地通过代码更改对管道更改进行版本控制、审查和协作

它不是一个构建引擎，本身不负责构建工作，只是负责构建的定义和一些资源状态的同步，他会将构建工作全部委托给 Tekton 来做，自己做了一些外围的工作，比如定义了代码仓库地址，在什么条件下可以触发构建，谁会有权限来触发这些构建等等

🏗️ 准备环境

Getting started with Pipelines-as-Code 中详细的描述另外如何安装 Pipelines as Code，这里描述下我的安装过程，给大家一个大致的地图

正如前面提到，Pipelines as Code 会将构建工作交给 Tekton 来做，所以需要安装 Tekton Pipeline 保证构建引擎可用

另外安装 Pipelines as Code 相关的组件，安装可以通过直接 apply yaml 文件到集群，也可以通过一个命令行工具来完成，这个工具可以帮你完成 Pipelines as Code 的安装和一些使用的初始化工作，我使用的就是命令行工具

当然这一切都需要先有一个 k8s 集群

k8s 集群

我使用的是 macOs，k8s 我使用的工具是 OrbStack，他可以提供 Docker 和 k8s 环境，整体使用感觉好，能耗和启动速度方面都很好，推荐大家使用

orbStask.png

Tekton Pipeline

我本地有 tektoncd/pipeline 源码用于开发，可以通过源码直接进行构建部署，通过 ko apply --local -R -f config/ 就可以将 Tekton Pipeline 所需的组件部署起来（简便的部署方式，对吸引社区贡献者作用很大）

如果没有相关开发环境，也可以通过在集群 apply pipeline-release.yaml 进行安装，这会将相关的 Namespace Deployment 等资源安装好

命令行工具

Pipelines as Code 提供了一个命令行工具，这个工具是作为 tkn 的一个插件存在的，tkn 是 Tekton 提供的一个命令行工具，通过如下命令安装这两个命令行工具

brew install tektoncd-cli

brew install openshift-pipelines/pipelines-as-code/tektoncd-pac

执行完成后，执行如下命令行，能显示版本号说明安装正常

{21:44}/ ➭ tkn pac version
0.27.1

🚀 快速开始

在这里，我们会安装 Pipelines as Code 组件，配置 gosmee 以便本地接收 Github 的 webhook 事件信息，创建 Github Application 来同步流水线执行状态和结果到 Github，并且创建一个 Github 代码仓库来检验我们 CI 流水线能否生效

上面步骤中安装的 tkn pac 提供了很多功能，可以让我们的操作简便快捷，基于这一个命令行工具，我们就可以完成安装工作，提供的参数大致如下

{21:44}/ ➭ tkn pac
tkn plugin to use Pipelines as Code as a CLI

Usage:
  tkn-pac [command]

Available Commands:
  bootstrap   Bootstrap Pipelines as Code.
  completion  Prints shell completion scripts
  create      Create Pipelines as Code resources
  delete      Delete Pipelines as Code resources
  describe    Describe a repository
  generate    Generate PipelineRun
  help        Help about any command
  info        Show installation information
  list        List Pipelines as Code Repository
  logs        Display the PipelineRun logs from a Repository
  resolve     Resolve PipelineRun the same way its run on CI
  version     Print tkn pac version
  webhook     Update webhook secret

Flags:
  -h, --help                help for tkn-pac
  -k, --kubeconfig string   Path to the kubeconfig file to use for CLI requests (default: /Users/sda/.kube/config) (default "/Users/sda/.kube/config")
  -n, --namespace string    If present, the namespace scope for this CLI request

Use "tkn-pac [command] --help" for more information about a command.

tkn pac bootstrap 可以帮助我们快速安装 Pipelines as Code 以及设置 Github Application

安装 Pipelines as Code 组件

执行 tkn pac bootstrap 安装 Pipelines as Code，此时会先检查是否已经安装了该工具，如果没有安装，则会询问是否安装，我们在这里选择安装

{21:49}/ ➭ tkn pac bootstrap
=> Checking if Pipelines-as-Code is installed.
🕵️ Pipelines-as-Code doesn't seem to be installed in the pipelines-as-code namespace.
? Do you want me to install Pipelines-as-Code v0.19.2? (Y/n)

安装 gosmee

继续安装时，会询问你是否要安装 gosmee，这是一个 webhook 转发器，可以实现将 Github 上的 webhook 事件信息转发到我们的本地环境，这很重要，我们需要选择安装

gosmee.png

需要注意的是，这里会生成一个 gosmee forward URL，我们需要保留一下，后续设置 Github Application 的时候会到，比如这里生成的 https://hook.pipelinesascode.com/zZVuUUOkCzPD，官方文档没有提到这一步，导致我在这里就踩了坑，导致排查了很久 😭

Pipelines-as-Code does not install an Ingress object to allow the controller to be accessed from the internet.
We can install a webhook forwarder called gosmee (https://github.com/chmouel/gosmee) using a https://hook.pipelinesascode.com URL.
This will let your git platform provider (e.g., GitHub) reach the controller without requiring public access.
? Do you want me to install the gosmee forwarder? (Y/n)
💡 Your gosmee forward URL has been generated: https://hook.pipelinesascode.com/zZVuUUOkCzPD

指定 Tekton Dashboard

前面提到过，Pipelines as Code 主要是将工作委托给了 Tekton 来完成，Tekton 有自己的 UI 界面的组件 Tekton Dashboard，他会在界面上展示 PipelineRun TaskRun 的执行状态及相关的日志

这里指定 Tekton Dashboard 地址的步骤，就是为了支持在查看某个构建状态和详细日志的场景下，跳转到相关界面查看相关信息

因为我没有安装，因此跳过了这个步骤，这里是官方文档提供的 demo，它会先自动检测是否存在对应的地址，如果存在直接使用，用户也可以自行指定地址

👀 We have detected a tekton dashboard install on http://dashboard.paac-127-0-0-1.nip.io
? Do you want me to use it? Yes

创建 Github Application

随后会让你创建一个 Github Applicaiton，这里我们需要为它指定一个名称，名称没有什么要求，只要不与已经存在的 Application 冲突即可

? Enter the name of your GitHub application: My PAAC Application

你会被导向一个链接，通过链接可以创建 Github Application

github-application.png

🔑 Secret pipelines-as-code-secret has been created in the pipelines-as-code namespace
🚀 You can now add your newly created application to your repository by going to this URL:

https://github.com/apps/my-paac-application

💡 Don't forget to run "tkn pac create repository" to create a new Repository CR on your cluster.

此时安装过程就结束了，但是还是需要对刚才创建的 Github Application 做一些改动，保证后续工作顺利

我们需要修改下 Application 的 Webhook URL 保证仓库事件信息可以发送到 gosmee 地址中，访问 https://github.com/settings/apps/my-paac-application 找到设置，将 Webhook URL 修改成上面提到的需要保留的地址

application-webhook.png

⚡ 能力体验

这一步骤中，我们会创建一个 Github 仓库用于体验 Pipelines as Code 提供的强大能力

点击 https://github.com/openshift-pipelines/pac-demo/generate 跳转到 Github 创建一个 demo 仓库，这是一个 Golang 的代码仓库，里面有一些用于演示的简单的代码

访问 Github Application https://github.com/apps/my-paac-application 并安装到刚才创建的 demo 仓库

install-application.png

clone 刚才创建的 demo 仓库到本地，并且进入到相关目录

git clone https://github.com/$yourusername/pac-demo
cd pac-demo

执行如下命令为代码仓库创建 CI 配置

tkn pac create repository

? Enter the Git repository url (default: https://github.com/chmouel/pac-demo):
? Please enter the namespace where the pipeline should run (default: pac-demo-pipelines):
! Namespace pac-demo-pipelines is not found
? Would you like me to create the namespace pac-demo-pipelines? (Y/n)
ℹ Directory .tekton has been created.
✓ We have detected your repository using the programming language Go.
✓ A basic template has been created in /tmp/pac-demo/.tekton/pipelinerun.yaml, feel free to customize it.
ℹ You can test your pipeline by pushing the generated template to your git repository

此时会在集群中创建一个 repository 资源，并且在代码仓库根目录创建一个 .tekton 的目录，我们重点关注下这个自动创建的文件夹

在该文件夹中会存在一个 pipelinerun.yaml 文件，这个文件定义了一个 CI 流程，里面包含了 clone 和 golang-ci-lint 两个步骤，看下文件内容了解一下

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pac-demo
  annotations:
    # The event we are targeting as seen from the webhook payload
    # this can be an array too, i.e: [pull_request, push]
    pipelinesascode.tekton.dev/on-event: "[pull_request, push]"

    # The branch or tag we are targeting (ie: main, refs/tags/*)
    pipelinesascode.tekton.dev/on-target-branch: "[main]"

    # Fetch the git-clone task from hub, we are able to reference later on it
    # with taskRef and it will automatically be embedded into our pipeline.
    pipelinesascode.tekton.dev/task: "git-clone"

    # Use golangci-lint from the hub to test our Golang project
    pipelinesascode.tekton.dev/task-1: "golangci-lint"

    # You can add more tasks by increasing the suffix number, you can specify
    # them as array to have multiple of them.
    # browse the tasks you want to include from hub on https://hub.tekton.dev/
    #
    # pipelinesascode.tekton.dev/task-2: "[curl, buildah]"

    # how many runs we want to keep attached to this event
    pipelinesascode.tekton.dev/max-keep-runs: "5"
spec:
  params:
    # The variable with brackets are special to Pipelines as Code
    # They will automatically be expanded with the events from Github.
    - name: repo_url
      value: "{{ repo_url }}"
    - name: revision
      value: "{{ revision }}"
  pipelineSpec:
    params:
      - name: repo_url
      - name: revision
    workspaces:
      - name: source
      - name: basic-auth
    tasks:
      - name: fetch-repository
        taskRef:
          name: git-clone
        workspaces:
          - name: output
            workspace: source
          - name: basic-auth
            workspace: basic-auth
        params:
          - name: url
            value: $(params.repo_url)
          - name: revision
            value: $(params.revision)
      - name: golangci-lint
        taskRef:
          name: golangci-lint
        runAfter:
          - fetch-repository
        params:
          - name: package
            value: .
        workspaces:
          - name: source
            workspace: source

  workspaces:
    - name: source
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 1Gi
    # This workspace will inject secret to help the git-clone task to be able to
    # checkout the private repositories
    - name: basic-auth
      secret:
        secretName: "{{ git_auth_secret }}"

这个就是一个标准的 Tekton PipelineRun 资源的定义，不同的是 annotations 中有很多 Pipelines as Code 自定义的值，用来指示不同场景下的配置

可以看到，spec.pipelineSpec 中接受 repo_url 和 revision 这两个参数来进行代码克隆，并且这里包含 clone 和 golangci-lint 两个步骤

此时我们提交代码到代码仓库，并且发起从当前分支到 main 分支的 PR，在 PR 的界面，应该可以看到该 PR 的 checks 会处于执行状态

checks.png

点击 Details 详情可以看到 checks 相关详情信息，通过这里我们可以看到，这个 PR 的 checks 没有通过，原因是 golangci-lint 的一些校验没有通过

details.png

代码里存在一些不合规范的内容

check-failure.png

我们可以修改 main.go 代码以更正 checks 中提到的问题，再次提交代码

package main

import (
    "fmt"
    "os"
)

func main() {
    fmt.Fprintf(os.Stdout, "Hello world")
}

再去查看 PR 时会发现，PR 的 checks 已经成功通过了

check-succeed.png

这些就是 Pipeline as Code 的能力体验，虽然只是一个简单的 Demo，但是他也满足你在 Github 上做开发时 CI 的基本需求，在代码变动时进行代码构建，并且将流水线结果同步到 Github 上

🤔 一些疑问

这一切都很神奇，也许你想问，这些 check 是在哪里做的呢，是在我本地吗?如果是的话，本地是如何接收到需要构建的消息又是怎么将结果同步到 Github 上的呢

对于第一个问题，你可以执行 tkn pac logs -n pac-demo-pipelines -L 来查看 pac-demo-pipelines 命名空间最新执行的 pipelinerun，这个对应的就是 Github 上的那个检查步骤，克隆代码，随后执行 golangci-lint 校验代码中存在的问题

第二个问题就是上面提到的 gosmee，它将 Github webhook 的事件信息转发到了本地

第三个问题是通过我们注册的 Github Application 完成的构建信息的同步，pipelines-as-code-controller 会将 pipelineRun 的执行状态和结果通过 Github Application 同步到 Github 代码仓库中

🥰 参考

Pipelines-as-Code
Getting started with Pipelines-as-Code
Github Pipelines as Code
gosmee