#tkn pac 命令参考

本指南提供了 tkn pac CLI 插件命令的全面参考，包括仓库管理、流水线生成和解析。

#前提条件

• 已安装 tkn CLI
• 已安装 tkn pac 插件
• 已配置 kubectl 以访问您的集群
• 已部署 PAC 组件

#验证安装

# 验证 tkn CLI
tkn version

示例输出：

Client version: 0.43.0
Pipeline version: v0.65.0

# 验证 tkn-pac 插件
tkn pac version

示例输出：

0.39.2

#仓库命令

#tkn pac create repository

基于流水线运行模板创建新的 Pipelines as Code 仓库和命名空间。

基本语法：

tkn pac create repo

交互模式：

命令将提示您输入：

1. Git 仓库 URL（自动检测当前目录）
2. 流水线运行的命名空间（默认：project-pipelines）
3. Git 提供商特定信息（例如 GitLab 的项目 ID）
4. PAC 控制器 URL（自动检测）
5. Webhook 密钥（自动生成）
6. Git 提供商访问令牌
7. Git 提供商 API URL（因提供商而异）

功能说明：

• 在 Kubernetes 集群中创建 Repository CR
• 自动配置 Git 提供商的 webhook
• 创建包含 Git 提供商凭据的 Kubernetes Secret
• 在仓库中生成 .tekton/pipelinerun.yaml 模板

示例：

cd /path/to/your/repo
tkn pac create repo

交互式示例输出：

? Enter the Git repository URL: https://gitlab.com/user/repo
? Enter the namespace where the pipeline should run (default: default): project-pipelines
? Enter the GitLab project ID: 12345678
? Enter the Pipelines as Code controller URL (default: http://pac.example.com): 
? Enter the webhook secret (default: auto-generated): 
? Enter the GitLab access token: glpat-xxxxxxxxxxxxxxxxxxxx
? Enter the GitLab API URL (default: https://gitlab.com): 
✓ Repository CR created successfully
✓ Webhook configured in GitLab
✓ Secret created
✓ Template generated at .tekton/pipelinerun.yaml

详细用法请参见 Configure Repository。

#tkn pac list

列出所有 Pipelines as Code 仓库，并显示关联运行的最新状态。

基本语法：

tkn pac list

指定命名空间列出：

tkn pac list -n <namespace>

输出格式：

REPOSITORY          NAMESPACE          URL                                    LAST RUN STATUS
my-repo            project-pipelines  https://gitlab.com/user/repo       Succeeded
another-repo       production         https://gitlab.com/user/another    Running

选项：

• -n, --namespace <namespace>：指定命名空间列出仓库（默认：当前 kubectl 上下文命名空间）
• -A, --all-namespaces：列出所有命名空间中的仓库
• -o, --output <format>：输出格式（default、json、yaml、wide）

示例：

# 列出当前命名空间所有仓库
tkn pac list

# 列出指定命名空间的仓库
tkn pac list -n project-pipelines

# 列出所有命名空间的仓库
tkn pac list -A

#tkn pac repo describe

描述一个 Pipelines as Code 仓库及其关联的运行。

基本语法：

tkn pac repo describe <repository-name>

选项：

• -n, --namespace <namespace>：指定仓库所在命名空间（默认：当前 kubectl 上下文命名空间）
• -o, --output <format>：输出格式（default、json、yaml）

输出内容包括：

• 仓库 CR 详情
• Git 提供商配置
• Webhook 配置
• 最近 PipelineRun 状态
• 最近运行信息

示例：

# 描述当前命名空间中的仓库
tkn pac repo describe my-repo

# 描述指定命名空间中的仓库
tkn pac repo describe my-repo -n project-pipelines

示例输出：

Repository: my-repo
Namespace: project-pipelines
URL: https://gitlab.com/user/repo
Git Provider: gitlab
Status: Ready

Recent Runs:
  - pipelinerun-abc123: Succeeded (2 minutes ago)
  - pipelinerun-def456: Running (5 minutes ago)
  - pipelinerun-ghi789: Failed (10 minutes ago)

#生成命令

#tkn pac generate

生成一个简单的 PipelineRun 模板。

基本语法：

tkn pac generate

功能：

• 自动检测当前目录的 Git 信息
• 使用基础语言检测能力
• 根据检测到的语言添加额外任务
• 创建 .tekton/pipelinerun.yaml 模板

语言检测：

命令会检测项目语言并添加相应任务：

• Python：检测到 setup.py 或 requirements.txt，添加 pylint 任务
• Go：检测到 go.mod，添加 golangci-lint 任务
• Node.js：检测到 package.json，添加 npm 任务
• Java：检测到 pom.xml，添加 maven 任务

示例：

# 进入您的仓库目录
cd /path/to/your/repo

# 生成流水线模板
tkn pac generate

示例输出：

✓ Pipeline template generated at .tekton/pipelinerun.yaml

生成的模板示例：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: generated-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 generated pipeline!"

#解析命令

#tkn pac resolve

执行一个流水线运行，模拟其由 Pipelines as Code 服务拥有。此命令适用于在本地测试流水线定义，无需创建新的提交。

基本语法：

tkn pac resolve -f <pipeline-file>

选项：

• -f, --file：流水线文件或目录路径（必填）
• -p, --param：覆盖参数值（格式：key=value）
• -o, --output：输出格式（yaml、json 或默认）

从文件解析：

tkn pac resolve -f .tekton/pull-request.yaml

从目录解析：

tkn pac resolve -f .tekton/

命令会处理目录下所有 .yaml 和 .yml 文件。

覆盖参数：

您可以覆盖从 Git 仓库派生的默认参数值：

tkn pac resolve -f .tekton/pipelinerun.yaml \
  -p revision=main \
  -p repo_name=my-repo

多个文件：

可以多次使用 -f 标志：

tkn pac resolve -f .tekton/pipeline1.yaml -f .tekton/pipeline2.yaml

自动检测：

在源代码仓库中运行时，命令会尝试：

• 检测当前 Git 信息
• 自动解析参数，如：
  • 当前修订版本（commit SHA）
  • 分支名称
  • 仓库 URL
  • 仓库名称

示例：

# 从当前目录解析流水线
cd /path/to/your/repo
tkn pac resolve -f .tekton/pipelinerun.yaml

示例输出：

Resolved pipeline:
- revision: abc1234
- repo_url: https://gitlab.com/user/repo
- branch: main
✓ Pipeline resolved successfully

输出格式：

命令将解析后的 PipelineRun YAML 输出到标准输出。您可以：

• 保存到文件：tkn pac resolve -f .tekton/pipelinerun.yaml > resolved.yaml

• 直接查看：tkn pac resolve -f .tekton/pipelinerun.yaml

• 用于验证：在提交前检查变量是否正确解析

  # 使用自定义参数解析
  tkn pac resolve -f .tekton/pipelinerun.yaml \
    -p revision=feature-branch \
    -p repo_name=custom-repo

示例输出：

Resolved pipeline:
- revision: feature-branch
- repo_url: https://gitlab.com/user/custom-repo
- branch: feature-branch
✓ Pipeline resolved successfully

使用场景：

• 本地测试流水线定义
• 调试流水线问题，无需创建提交
• 提交前验证流水线语法
• 测试参数解析

#全局选项

所有 tkn pac 命令支持以下全局选项：

• -h, --help：显示命令帮助
• -v, --version：显示版本信息
• --kubeconfig：指定 kubeconfig 文件路径
• --context：指定 Kubernetes 上下文

#最佳实践

#1. 仓库管理

• 使用描述性名称：选择清晰的仓库名称
• 按命名空间组织：将相关仓库分组到命名空间
• 定期监控：使用 tkn pac list 监控仓库状态

#2. 流水线生成

• 审查生成模板：始终审查并自定义生成的流水线
• 本地测试：使用 tkn pac resolve 在提交前测试流水线
• 版本控制：将流水线定义提交到 Git

#故障排除

#命令未找到

如果找不到 tkn pac 命令：

1. 验证安装：

   tkn pac version

   示例输出：

   0.39.2

2. 检查 PATH：确保 tkn-pac 在您的 PATH 中

3. 重新安装：如有需要，重新安装插件

#连接问题

如果命令无法连接到集群：

1. 验证 kubectl：测试 kubectl 连接
2. 检查上下文：确认 Kubernetes 上下文
3. 检查权限：确保拥有所需权限

#后续步骤

• Configure Repository - 仓库设置指南
• Incoming Webhooks - 通过 webhook 触发流水线
• Manage PAC Component - PAC 组件管理
• Common Issues - 故障排除指南