#快速开始

本指南帮助您快速部署 PAC 组件并配置第一个 Git 仓库集成。

#介绍

本快速开始指南涵盖：

• 在 Kubernetes 上部署 PAC 组件
• 使用 tkn pac CLI 配置 Git 仓库
  • 安装 tkn pac 插件
• 以代码方式创建您的第一个流水线

#预计阅读时间

20-30 分钟

#前提条件

• Kubernetes 集群（1.24+）
• 已安装 Tekton Operator
• 集群管理员权限
• 已安装并配置 kubectl
• 已安装带 pac 插件的 tkn CLI
• 拥有 Git 仓库的管理员访问权限

#步骤 1：部署 PAC 组件

#创建 OpenShiftPipelinesAsCode CR

尽管资源名称包含 “OpenShift”，PAC 仍可通过 Tekton Operator 部署在 Kubernetes 平台上。

创建名为 pac.yaml 的文件：

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  settings:
    application-name: Pipelines as Code CI
    hub-url: http://tekton-hub-api.tekton-pipelines:8000/v1
    remote-tasks: "true"
    
    # （可选）自定义 Console 集成
    # 取消注释并配置以集成您的自定义 Console
    # 将 'my-cluster' 替换为您的实际集群名称
    # custom-console-name: "My Console"
    # custom-console-url: "https://console.example.com"
    # custom-console-url-pr-details: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}"
    # custom-console-url-pr-tasklog: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}?tab=task_overview&id={{ task }}"
    # custom-console-url-namespace: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns"
    
  targetNamespace: tekton-pipelines  # 默认命名空间，可自定义

注意：targetNamespace 字段指定 PAC 组件部署的命名空间。默认是 tekton-pipelines，但您可以使用任意命名空间名称。确保在应用配置前该命名空间已存在。

自定义 Console 集成：注释中的自定义 Console 设置允许您将 PAC 与自定义监控面板集成。配置后，Git 提供商中的流水线状态链接将指向您的 Console。重要：请将 URL 中的 my-cluster 替换为您的实际集群名称（如不确定，请咨询集群管理员）。详细配置指南、分步说明及故障排查，请参见配置自定义 Console 链接。

应用配置：

kubectl apply -f pac.yaml

示例输出：

openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code created

#验证部署

检查 PAC 组件状态：

kubectl get openshiftpipelinesascodes.operator.tekton.dev

示例输出：

NAME                  VERSION   READY   REASON
pipelines-as-code    0.x.x     True    Ready

检查 PAC pods（如果您使用的命名空间不是 tekton-pipelines，请替换为实际命名空间）：

kubectl get pods -n tekton-pipelines | grep pipelines-as-code

示例输出：

NAME                                      READY   STATUS    RESTARTS   AGE
pipelines-as-code-controller-xxxxx        1/1     Running   0          2m
pipelines-as-code-watcher-xxxxx          1/1     Running   0          2m
pipelines-as-code-webhook-xxxxx          1/1     Running   0          2m

注意：本指南中默认使用 tekton-pipelines 作为示例命名空间。如果您在其他命名空间部署了 PAC，请将 tekton-pipelines 替换为实际命名空间名称。

您应看到三个处于 Running 状态的 pod：

• pipelines-as-code-controller-*
• pipelines-as-code-watcher-*
• pipelines-as-code-webhook-*

#配置访问

暴露 PAC controller 以便 GitLab webhook 能访问。您可以使用 Ingress 或 NodePort。详细配置选项请参见管理 PAC 组件。

重要：PAC controller URL 必须能被您的 GitLab 服务器访问。设置仓库时请确保配置正确的 URL。

#获取 PAC Controller URL

暴露 PAC controller 后，您可以通过以下方式获取 URL。普通用户如需查询 URL，可使用以下命令，或联系 PAC 管理员。

#查询 Ingress（如果配置）

检查 PAC controller 是否通过 Ingress 暴露（将 <pac-namespace> 替换为您的 PAC 命名空间，默认是 tekton-pipelines）：

kubectl get ingress -n <pac-namespace> | grep pipelines-as-code

示例输出（如果配置了 Ingress）：

NAME                  CLASS    HOSTS              ADDRESS        PORTS   AGE
pipelines-as-code     nginx    pac.example.com    192.168.1.10   80      5m

如果存在，获取 Ingress host：

kubectl get ingress pipelines-as-code -n <pac-namespace> -o jsonpath='{.spec.rules[0].host}'

示例输出：

pac.example.com

#查询 NodePort 服务（如果配置）

检查 PAC controller 是否通过 NodePort 暴露（将 <pac-namespace> 替换为您的 PAC 命名空间，默认是 tekton-pipelines）：

kubectl get svc -n <pac-namespace> pipelines-as-code-controller-nodeport

示例输出（如果配置了 NodePort）：

NAME                                      TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
pipelines-as-code-controller-nodeport    NodePort   10.96.123.45    <none>        8080:30080/TCP   5m

如果存在，获取 NodePort 和节点 IP：

# 设置您的 PAC 命名空间（默认：tekton-pipelines）
PAC_NAMESPACE="tekton-pipelines"

# 获取 NodePort
NODEPORT=$(kubectl get service -n ${PAC_NAMESPACE} pipelines-as-code-controller-nodeport -o jsonpath='{.spec.ports[?(@.name=="http-listener")].nodePort}')

# 获取节点 IP
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')

echo "PAC Controller URL: http://${NODE_IP}:${NODEPORT}"

示例输出：

PAC Controller URL: http://192.168.1.100:30080

#如果找不到 URL

如果以上方法均无效，或您无权限查询集群资源，请联系您的 PAC 管理员获取 PAC controller URL。

#步骤 2：配置仓库

kubectl get pods -n tekton-pipelines | grep pipelines-as-code

#安装 tkn pac 插件

确保已安装 tkn pac 插件：

tkn pac version

示例输出：

0.39.2

如果命令失败或报错，请参见安装 tkn pac 插件中的安装步骤。

#创建 GitLab 个人访问令牌

1. 进入 GitLab → 设置 → 访问令牌
2. 创建带有 api 权限的令牌
3. 妥善保存令牌

#使用 tkn pac 配置仓库

重要：请先切换到您的 Git 仓库目录再执行命令。.tekton 目录将在当前工作目录下创建。

cd /path/to/your/gitlab/repo
tkn pac create repo --pac-namespace tekton-pipelines

注意：如果您在其他命名空间部署了 PAC，请将 tekton-pipelines 替换为实际 PAC 命名空间。--pac-namespace 参数指定 PAC controller 部署位置。

按照交互提示操作：

1. 输入 Git 仓库 URL（自动检测当前目录，或手动输入）
2. 输入流水线命名空间（默认：default，可输入 project-pipelines 或您偏好的命名空间）
   • 注意：该命名空间必须存在。请先创建：kubectl create namespace project-pipelines
3. 此时将创建 Repository CR
4. 输入 GitLab 项目 ID（项目设置 → 常规中可查）
5. 输入 PAC controller URL（自动检测，检测失败可手动输入）
6. 输入 webhook secret（或直接回车使用自动生成的默认值）
7. 输入 GitLab 访问令牌（即您创建的个人访问令牌）
8. 输入 GitLab API URL（默认：https://gitlab.com，或输入您的自托管 GitLab URL）

该命令将：

• 在集群中创建 Repository CR
• 自动配置 GitLab webhook
• 创建 Kubernetes Secret 存储凭据
• 在您的仓库中生成 .tekton/pipelinerun.yaml 模板

#步骤 3：创建您的第一个流水线

tkn pac create repo 命令会在 .tekton/pipelinerun.yaml 创建一个基础模板。编辑该文件定义您的流水线：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: simple-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from Pipelines as Code!"

提交并推送到您的仓库：

git add .tekton/pipelinerun.yaml
git commit -m "Add PAC pipeline"
git push origin <your-branch-name>

注意：

• 将 <your-branch-name> 替换为您的分支名（如 main、master 或 develop）
• 确保注解 pipelinesascode.tekton.dev/on-target-branch 与您的分支名匹配。例如分支为 main，使用 "[refs/heads/main]"；分支为 test，使用 "[refs/heads/test]"
• 支持匹配多个分支，使用逗号分隔："[main, develop]" 或 "[refs/heads/main,refs/heads/develop]"
• 匹配所有分支，使用："[refs/heads/*]"

#步骤 4：测试流水线

#通过 Push 触发

向流水线注解指定的分支推送提交以触发流水线：

echo "test" >> README.md
git add README.md
git commit -m "Test pipeline trigger"
git push origin <your-branch-name>

#通过合并请求触发

创建合并请求触发流水线：

git checkout -b feature/test
echo "feature" >> feature.txt
git add feature.txt
git commit -m "Add feature"
git push origin feature/test

然后在 GitLab 创建合并请求。

#查看流水线状态

查看指定命名空间中的 PipelineRuns：

kubectl get pipelineruns -n project-pipelines

示例输出：

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   2 minutes ago  30s        Succeeded

查看流水线日志：

# 列出所有 PipelineRuns
tkn pipelinerun list -n project-pipelines

示例输出：

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   2 minutes ago  30s        Succeeded

# 查看指定 PipelineRun 的日志
tkn pipelinerun logs <pipelinerun-name> -n project-pipelines

示例输出：

[hello : echo] Hello from Pipelines as Code!

#后续步骤

• 管理 PAC 组件 - 部署、更新和卸载指南
• 配置仓库 - 高级仓库配置
• 维护流水线代码 - 流水线定义指南
• 触发流水线 - 事件触发指南