#Configure Authentication for Private Repositories

本指南说明如何为 PAC 中的私有仓库配置认证。私有仓库需要认证凭据，以允许 PAC 访问和克隆仓库内容。

#Prerequisites

在配置私有仓库认证之前，请确保您已具备：

• 已部署并运行 PAC 组件
• 已为您的仓库创建 Repository CR（自定义资源）。Repository CR 是一个 Kubernetes 资源，用于告诉 PAC 监控哪个 Git 仓库以及如何配置它
• 具有创建 Kubernetes Secret 的管理员权限
• 拥有您的 Git 提供商的访问令牌

#Overview

PAC 支持使用 Personal Access Tokens (PAT) 和 HTTPS URL 对私有 GitLab 仓库进行认证。

#Configuration Steps

按照以下步骤为私有仓库配置认证。

#Step 1: Create Access Token in GitLab

1. 进入 GitLab → 用户设置 → 访问令牌
2. 创建一个具有 api 权限范围的令牌
3. 生成并复制该令牌

#Step 2: Create Kubernetes Secret

创建一个包含您的 GitLab 访问令牌的 secret：

kubectl create secret generic gitlab-secret \
  --from-literal=token=your-gitlab-token-here \
  -n <your-namespace>

示例输出：

secret/gitlab-secret created

注意：PAC 将使用此令牌进行 Git 提供商的 API 操作（webhook 管理、PR 状态更新等），并自动从中创建 git clone 认证 secret。

#创建 Webhook Secret（可选）

如果您计划配置 webhook，请创建一个用于 webhook 验证的 secret：

kubectl create secret generic webhook-secret \
  --from-literal=secret=your-webhook-secret-here \
  -n <your-namespace>

安全最佳实践：

• 安全存储令牌，并为不同仓库或环境使用独立的 secret
• PAC 会自动创建 git clone 认证 secret，无需手动创建

#Step 3: Update Repository CR

更新您的 Repository CR，引用认证 secret：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-private-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/private-repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

注意：PAC 使用 git_provider.secret 进行 API 操作，并自动从中创建 git clone 认证 secret，用于 PipelineRuns。

#Verifying Private Repository Access

配置认证后，验证 PAC 是否能访问您的私有仓库：

#Check Repository CR

kubectl get repository <repo-name> -n <your-namespace> -o yaml

示例输出（简略）：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/private-repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token

#Check PAC Controller Logs

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

kubectl logs -n ${PAC_NAMESPACE} \
  -l app=pipelines-as-code-controller \
  --tail=100

查看是否有认证错误或连接 Git 提供商的问题。

#Test Pipeline Trigger

触发测试 pipeline 以验证访问：

# 提交一个空提交以触发 pipeline
git commit --allow-empty -m "Test private repo access"
git push origin main

示例输出：

[main abc1234] Test private repo access
Enumerating objects: 3, done.
Writing objects: 100% (2/2), 240 bytes | 240.00 KiB/s, done.
To https://gitlab.com/user/private-repo
   def5678..abc1234  main -> main

检查 PipelineRun 是否成功创建：

kubectl get pipelineruns -n <your-namespace>

示例输出：

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   1 minute ago  25s        Succeeded

#Troubleshooting

#Check for Authentication Errors

问题：PAC 无法访问私有仓库。

解决方案：

1. 验证令牌权限：确保 GitLab 访问令牌具有 api 权限范围

2. 检查 secret 是否存在：确认 GitLab secret 存在于正确的命名空间：

   kubectl get secret gitlab-secret -n <your-namespace>

   示例输出：

   NAME              TYPE     DATA   AGE
   gitlab-secret     Opaque   1      5m

3. 验证 secret key：确保 secret 中包含 token 键：

   kubectl get secret gitlab-secret -n <your-namespace> -o yaml

   示例输出（简略，token 为 base64 编码）：

   apiVersion: v1
   kind: Secret
   metadata:
     name: gitlab-secret
     namespace: project-pipelines
   data:
     token: Z2xwYXQt...

4. 检查 Repository CR：确认 Repository CR 中的 secret 引用正确：

   kubectl get repository <repo-name> -n <your-namespace> -o yaml | grep -A 5 git_provider

   示例输出：

   git_provider:
     type: gitlab
     url: "https://gitlab.com"
     secret:
       name: gitlab-secret
       key: token

#Token Expired

问题：访问令牌已过期。

解决方案：

1. 从您的 Git 提供商生成新的访问令牌

2. 更新 Kubernetes Secret：

   kubectl create secret generic gitlab-secret \
     --from-literal=token=new-token-here \
     -n <your-namespace> \
     --dry-run=client -o yaml | kubectl apply -f -

   示例输出：

   secret/gitlab-secret configured

3. 如有需要，重启 PAC controller pods：

   kubectl rollout restart deployment pipelines-as-code-controller -n <tekton-namespace>  # 将 <tekton-namespace> 替换为您的实际命名空间（默认：tekton-pipelines）

   示例输出：

   deployment.apps/pipelines-as-code-controller restarted

#Best Practices

#1. Token Management

• 使用独立令牌：为不同仓库或环境使用不同令牌
• 设置过期时间：为令牌设置过期时间以提升安全性
• 定期轮换：定期更换访问令牌
• 限制权限范围：仅授予最低所需权限

#2. Secret Management

• 使用命名空间：在合适的命名空间中存储 secrets
• RBAC 控制：使用 RBAC 控制谁可以访问 secrets
• 外部 secret 管理：考虑使用外部 secret 管理工具（如 Sealed Secrets、Vault）

#3. Security

• 最小权限原则：授予最低所需权限
• 审计访问：定期审计谁有仓库访问权限
• 监控日志：监控 PAC controller 日志中的认证问题

#Next Steps

• Configure Custom Certificates - 配置自签名证书的自定义 CA 证书
• Advanced Repository Configuration - 了解高级仓库配置选项
• Configure GitLab Repository - GitLab 专用配置指南
• Common Issues - 故障排除指南