Alauda DevOps Pipelines Docs
  • 简体中文

    • 为私有仓库配置身份验证

    适用于所有用户

    本指南专门针对 GitLab 仓库。配置步骤是根据 GitLab 的身份验证和 API 要求定制的。

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

    了解 PAC 中的身份验证

    PAC 会将身份验证用于私有仓库：

    • Git Provider API 身份验证 (git_provider.secret)：用于 API 操作，例如创建 webhook、更新 PR 状态以及访问仓库元数据。PAC 还会自动从此令牌创建一个 git clone 身份验证 secret，以便在 PipelineRuns 中使用。

    目录

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

    前提条件

    在配置私有仓库的身份验证之前，请确保你已具备：

    • PAC 组件已部署并运行
    • 为你的仓库创建了一个 Repository CR（Custom Resource）。Repository CR 是一个 Kubernetes 资源，用于告诉 PAC 要监控哪个 Git 仓库以及如何配置它
    • 具有创建 Kubernetes Secrets 的管理员权限
    • 你的 Git provider 的访问令牌
    什么是 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 中创建访问令牌

    1. 转到 GitLab → User Settings → Access Tokens
    2. 创建一个具有 api scope 的令牌
    3. 生成并复制该令牌

    第 2 步：创建 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 provider 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，因此你无需手动创建它们

    第 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. 验证令牌权限：确保 GitLab 访问令牌具有 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

    令牌已过期

    问题：访问令牌已过期。

    解决方案：

    1. 从你的 Git provider 生成一个新的访问令牌

    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 pod：

      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. 令牌管理

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

    2. Secret 管理

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

    3. 安全性

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

    下一步