#tkn pac 命令参考

本指南提供 tkn pac CLI 插件命令的完整参考，包括仓库管理、pipeline 生成和解析。

#前提条件

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

#安装 tkn pac 插件

请参阅 tkn pac Releases 获取最新版本。

请使用官方 tkn pac 项目发布指南中的任意一种方法安装 tkn pac，并确保可执行文件在你的 PATH 中可用。

#验证安装

# 验证 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

根据 pipeline run 模板创建新的 Pipelines as Code 仓库和命名空间。

基本语法：

tkn pac create repo

交互模式：

该命令会提示你输入：

1. Git 仓库 URL（从当前目录自动检测）
2. pipeline 所在的命名空间（默认：project-pipelines）
3. Git 提供商特定信息（例如 GitLab 的项目 ID）
4. PAC 控制器 URL（自动检测）
5. Webhook secret（自动生成）
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 context 的命名空间）
• -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 context 的命名空间）
• -o, --output <format>：输出格式（default、json、yaml）

输出包含：

• Repository 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)

#Generate 命令

#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

# 生成 pipeline 模板
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!"

#Resolve 命令

#tkn pac resolve

以由 Pipelines as Code 服务拥有的方式执行 pipeline run。这对于在本地测试 pipeline 定义而无需创建新的 commit 非常有用。

基本语法：

tkn pac resolve -f <pipeline-file>

选项：

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

从文件解析：

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 信息
• 自动解析以下参数：
  • 当前 revision（commit SHA）
  • 分支名称
  • 仓库 URL
  • 仓库名称

示例：

# 从当前目录解析 pipeline
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 输出到 stdout。你可以：

• 保存到文件：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

使用场景：

• 在本地测试 pipeline 定义
• 在不创建 commit 的情况下调试 pipeline 问题
• 在提交前验证 pipeline 语法
• 测试参数解析

#全局选项

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

• -h, --help：显示命令帮助
• -v, --version：显示版本信息
• --kubeconfig：kubeconfig 文件路径
• --context：要使用的 Kubernetes context

#最佳实践

#1. 仓库管理

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

#2. pipeline 生成

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

#故障排查

#找不到命令

如果找不到 tkn pac 命令：

1. 验证安装：

   tkn pac version

   示例输出：

   0.39.2

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

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

#连接问题

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

1. 验证 kubectl：测试 kubectl 连接
2. 检查 context：验证 Kubernetes context
3. 检查权限：确保你拥有所需权限

#下一步

• Configure Repository - 仓库设置指南
• Incoming Webhooks - 通过 webhooks 触发 pipeline
• Manage PAC Component - PAC 组件管理
• Common Issues - 故障排查指南