Alauda DevOps Pipelines Docs
  • 简体中文

    • 为私有仓库配置认证

    适用于所有用户

    本指南专门针对 GitLab 仓库。配置步骤针对 GitLab 的认证和 API 要求进行了定制。

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

    了解 PAC 中的认证

    PAC 对私有仓库使用认证：

    • Git Provider API 认证（git_provider.secret）：用于创建 webhooks、更新 PR 状态以及访问仓库元数据等 API 操作。PAC 还会根据此 token 自动创建一个 git clone 认证 Secret，供 PipelineRuns 使用。

    目录

    先决条件概述配置步骤第 1 步：在 GitLab 中创建 Access Token第 2 步：创建 Kubernetes Secret创建 Webhook Secret（可选）第 3 步：更新 Repository CR验证私有仓库访问检查 Repository CR检查 PAC Controller 日志测试 Pipeline 触发故障排查检查认证错误Token 已过期最佳实践1. Token 管理2. Secret 管理3. 安全性后续步骤

    先决条件

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

    • 已部署并运行 PAC 组件
    • 为你的仓库创建了一个 Repository CR（Custom Resource）。Repository CR 是一个 Kubernetes 资源，它告诉 PAC 要监控哪个 Git 仓库以及如何进行配置
    • 具有创建 Kubernetes Secrets 的管理员访问权限
    • 你的 Git provider 的访问 token
    什么是 Repository CR？

    Repository CR 是一个 Kubernetes Custom Resource，用于定义：

    • 要监控的 Git 仓库 URL
    • Git provider 配置（GitHub、GitLab 等）
    • 认证凭据
    • Webhook 设置
    • Pipeline 执行设置

    PAC 会监视 Repository CR，并在配置的 Git 仓库中发生事件时自动创建 PipelineRuns。

    概述

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

    配置步骤

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

    第 1 步：在 GitLab 中创建 Access Token

    1. 前往 GitLab → User Settings → Access Tokens
    2. 创建一个具有 api scope 的 token
    3. 生成并复制该 token

    第 2 步：创建 Kubernetes Secret

    创建一个包含你的 GitLab access token 的 Secret：

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

    示例输出：

    secret/gitlab-secret created

    注意：PAC 将使用此 token 执行 Git provider API 操作（webhook 管理、PR 状态更新等），并自动基于它创建一个 git clone 认证 Secret。

    创建 Webhook Secret（可选）

    如果你计划配置 webhooks，请创建一个用于 webhook 验证的 Secret：

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

    安全最佳实践：

    • 安全地存储 token，并为不同的仓库或环境使用单独的 Secret
    • PAC 会自动创建 git clone 认证 Secret，因此你无需手动创建它们

    第 3 步：更新 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 使用。

    验证私有仓库访问

    配置认证后，请验证 PAC 是否可以访问你的私有仓库：

    检查 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

    检查 PAC Controller 日志

    # Set your PAC namespace (default: tekton-pipelines)
PAC_NAMESPACE="tekton-pipelines"

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

    查找认证错误或连接 Git provider 的问题。

    测试 Pipeline 触发

    触发一个测试 Pipeline，以验证访问权限：

    # Push a commit to trigger the 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

    故障排查

    检查认证错误

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

    解决方案：

    1. 验证 token 权限：确保 GitLab access token 具有 api scope

    2. 检查 Secret 是否存在：验证 GitLab Secret 是否存在于正确的 namespace 中：

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

      示例输出：

      NAME              TYPE     DATA   AGE
gitlab-secret     Opaque   1      5m

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

      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 已过期

    问题：Access token 已过期。

    解决方案：

    1. 从你的 Git provider 生成一个新的 access token

    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>  # Replace <tekton-namespace> with your actual namespace (default: tekton-pipelines)

      示例输出：

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

    最佳实践

    1. Token 管理

    • 使用独立 token：为不同的仓库或环境使用不同的 token
    • 设置过期时间：为 token 设置过期日期，以提高安全性
    • 定期轮换：定期轮换 access token
    • 限制 scope：仅授予所需的最小权限

    2. Secret 管理

    • 使用 namespace：将 Secret 存储在合适的 namespace 中
    • RBAC：使用 RBAC 控制谁可以访问 Secret
    • 外部 Secret：考虑使用外部 Secret 管理工具（例如 Sealed Secrets、Vault）

    3. 安全性

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

    后续步骤