#Настройка репозитория GitLab

В этом руководстве описано, как настроить репозиторий GitLab для работы с PAC, чтобы pipeline можно было запускать по событиям GitLab.

#Предварительные требования

Перед настройкой репозитория GitLab убедитесь, что у вас есть:

• Развернутый и запущенный компонент PAC (см. Manage PAC Component)
• Контроллер PAC, доступный извне и reachable (через Ingress или NodePort)
• Установленный CLI tkn с плагином pac
• Репозиторий GitLab с доступом администратора в рамках repo-scope
• GitLab Personal Access Token с подходящими scopes

#Обзор

Команда tkn pac create repo — рекомендуемый способ настройки репозитория GitLab для PAC. Она автоматизирует весь процесс настройки:

1. Создает Repository CR в вашем cluster Kubernetes
2. Автоматически настраивает GitLab webhook
3. Создает Kubernetes Secret с учетными данными GitLab
4. Генерирует базовый шаблон .tekton/pipelinerun.yaml в вашем репозитории

#Шаг 1: Установите плагин tkn pac

Убедитесь, что плагин tkn pac установлен:

tkn pac version

Если он не установлен, следуйте инструкции по установке в tkn pac Command Reference.

#Шаг 2: Подготовьте GitLab Access Token

Вам нужен GitLab Personal Access Token со следующими scopes:

• api: Полный доступ к API

#Создание Personal Access Token

1. Перейдите в GitLab → User Settings → Access Tokens (или в Project Settings → Access Tokens для project tokens)
2. Создайте новый token со следующими параметрами:
   • Name: PAC Integration (или любое описательное имя)
   • Scopes: выберите api
   • Expiration date: задайте при необходимости (необязательно)
3. Нажмите Create personal access token
4. Сразу скопируйте token — он больше не будет показан

#Безопасное хранение token

Сохраните token в безопасном месте. Он понадобится вам при запуске tkn pac create repo.

Рекомендация по безопасности: Для лучшего контроля доступа рассмотрите использование project token вместо personal token.

#Шаг 3: Получите URL контроллера PAC

Перед настройкой repository вам нужен URL контроллера PAC. Этот URL используется GitLab для отправки webhook-событий в PAC.

#Способ 1: Запрос через Ingress (если настроен)

Проверьте, доступен ли контроллер PAC через Ingress (замените <pac-namespace> на ваш PAC namespace; по умолчанию это tekton-pipelines):

kubectl get ingress -n <pac-namespace> | grep pipelines-as-code

Пример вывода (если Ingress настроен):

NAME                  CLASS    HOSTS              ADDRESS        PORTS   AGE
pipelines-as-code     nginx    pac.example.com    192.168.1.10   80      5m

Если найден, получите host Ingress:

kubectl get ingress pipelines-as-code -n <pac-namespace> -o jsonpath='{.spec.rules[0].host}'

Пример вывода:

pac.example.com

URL контроллера будет следующим:

• HTTP: http://<ingress-host>
• HTTPS: https://<ingress-host>

#Способ 2: Запрос через NodePort Service (если настроен)

Проверьте, доступен ли контроллер PAC через NodePort (замените <pac-namespace> на ваш PAC namespace; по умолчанию это tekton-pipelines):

kubectl get svc -n <pac-namespace> pipelines-as-code-controller-nodeport

Пример вывода (если NodePort настроен):

NAME                                      TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
pipelines-as-code-controller-nodeport    NodePort   10.96.123.45    <none>        8080:30080/TCP   5m

Если найден, получите NodePort и IP узла:

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

# Get NodePort
NODEPORT=$(kubectl get service -n ${PAC_NAMESPACE} pipelines-as-code-controller-nodeport -o jsonpath='{.spec.ports[?(@.name=="http-listener")].nodePort}')

# Get Node IP
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')

echo "PAC Controller URL: http://${NODE_IP}:${NODEPORT}"

Пример вывода:

PAC Controller URL: http://192.168.1.100:30080

#Способ 3: Запрос через LoadBalancer Service (если настроен)

Проверьте, доступен ли контроллер PAC через LoadBalancer (замените <pac-namespace> на ваш PAC namespace; по умолчанию это tekton-pipelines):

kubectl get svc -n <pac-namespace> | grep pipelines-as-code-controller | grep LoadBalancer

Пример вывода (если LoadBalancer настроен):

NAME                                      TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)          AGE
pipelines-as-code-controller-lb          LoadBalancer   10.96.123.45    192.168.1.200   8080:30080/TCP   5m

Если найден, получите имя service и внешний IP:

# Get the service name first
SERVICE_NAME=$(kubectl get svc -n <pac-namespace> | grep pipelines-as-code-controller | grep LoadBalancer | awk '{print $1}')

# Get the external IP
kubectl get svc -n <pac-namespace> ${SERVICE_NAME} -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Пример вывода:

192.168.1.200

#Автоматическое определение в tkn pac

Команда tkn pac create repo может автоматически определить URL контроллера, проверяя:

1. Ресурсы Ingress
2. Сервисы LoadBalancer
3. Сервисы NodePort

Если автоматическое определение не удалось, вы сможете вручную ввести URL при появлении запроса.

#Если не удается найти URL

Если ни один из указанных выше способов не работает или у вас нет прав на запрос cluster resources:

1. Обратитесь к администратору PAC, чтобы получить URL контроллера PAC
2. Администратор может найти его, используя способы из Manage PAC Component
3. Обычно формат URL такой: http://<host-or-ip>:<port> или https://<host-or-ip>

#Шаг 4: Настройте repository с помощью tkn pac

#Перейдите в ваш repository

Склонируйте repository GitLab или перейдите в него:

cd /path/to/your/gitlab-repo

#Запустите tkn pac create repo

Важно: Перед запуском команды перейдите в каталог вашего repository GitLab. Каталог .tekton будет создан в текущем рабочем каталоге.

cd /path/to/your/gitlab/repo
tkn pac create repo --pac-namespace tekton-pipelines

Примечание: Если PAC установлен в другом namespace, скорректируйте параметр --pac-namespace соответствующим образом. Замените tekton-pipelines на фактический PAC namespace, если вы развернули PAC в другом namespace. Параметр --pac-namespace указывает, где развернут контроллер PAC (по умолчанию: tekton-pipelines).

#Интерактивная настройка

Команда запросит у вас следующую информацию:

#1. URL Git repository

? Enter the Git repository URL: 

• По умолчанию: автоматически определяется по git remote текущего каталога
• Формат: https://gitlab.com/username/repo или git@gitlab.com:username/repo
• Действие: нажмите Enter, чтобы использовать значение по умолчанию, или введите другой URL

#2. Namespace для Pipeline

? Enter the namespace where the pipeline should run (default: default): 

• По умолчанию: default
• Описание: Kubernetes namespace, в котором будут создаваться PipelineRun
• Действие: введите предпочитаемый namespace (например, project-pipelines) или нажмите Enter, чтобы использовать default

Важно:

• Namespace должен существовать до того, как PAC сможет создавать в нем PipelineRun

• Если namespace не существует, сначала создайте его:

  kubectl create namespace <your-namespace>

  Пример:

  kubectl create namespace project-pipelines

• Рекомендуется использовать отдельный namespace, например project-pipelines, вместо default

• Для создания ресурсов PAC в namespace должны быть настроены RBAC permissions

#3. GitLab Project ID

? Enter the GitLab project ID: 

• Как найти:
  • Перейдите в ваш GitLab project → Settings → General
  • Найдите "Project ID" в разделе "Project information"
  • Или используйте API: curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.com/api/v4/projects?search=<repo-name>"

#4. URL контроллера PAC

? Enter the Pipelines as Code controller URL (default: http://pac.example.com): 

• По умолчанию: автоматически определяется по ресурсам cluster
• Действие:
  • Если определен автоматически корректно, нажмите Enter
  • Если не определен, введите URL вручную
  • Если вы не знаете URL: см. Шаг 3: Получите URL контроллера PAC выше, где приведены команды для запроса, или обратитесь к администратору PAC

#5. Webhook Secret

? Enter the webhook secret (default: auto-generated): 

• По умолчанию: случайная строка, сгенерированная автоматически
• Описание: Secret, используемый для проверки webhook-запросов от GitLab
• Действие: нажмите Enter, чтобы использовать значение по умолчанию, или введите собственный secret

Безопасность: Храните этот secret в безопасности. Он хранится в Kubernetes Secret.

#6. GitLab Access Token

? Enter the GitLab access token: 

• Описание: Personal Access Token, созданный на шаге 2
• Действие: вставьте ваш token

#7. GitLab API URL

? Enter the GitLab API URL (default: https://gitlab.com): 

• По умолчанию: https://gitlab.com (для GitLab.com)
• Для self-hosted GitLab: введите URL вашей GitLab instance, например https://gitlab.example.com
• Действие: нажмите Enter для GitLab.com или введите URL вашей instance

#Пример интерактивной сессии

? Enter the Git repository URL: https://gitlab.com/myuser/myproject
? Enter the namespace where the pipeline should run (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): 

#Шаг 5: Проверьте настройку

#Проверьте Repository CR

Сначала определите ваш namespace (тот, который вы указали при создании Repository CR). Если вы его не помните, выведите список всех Repository CR:

kubectl get repositories --all-namespaces

Пример вывода:

NAMESPACE          NAME       URL                              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
project-pipelines  my-repo    https://gitlab.com/user/repo     True        Succeeded

Затем проверьте, что Repository CR создан в вашем namespace:

kubectl get repositories -n <your-namespace>

Пример вывода:

NAME       URL                              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
my-repo    https://gitlab.com/user/repo     True        Succeeded

Просмотрите сведения о Repository CR:

Сначала возьмите имя repository из списка выше, затем посмотрите подробности:

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

Замените <repo-name> на фактическое имя repository из списка (например, my-repo).

Пример вывода (сокращенно):

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

#Проверьте GitLab Webhook

1. Перейдите в ваш GitLab project → Settings → Webhooks
2. Убедитесь, что webhook создан со следующими параметрами:
   • URL: URL вашего контроллера PAC
   • Trigger: Push events, Merge request events, Comments
   • Secret token: webhook secret, который вы настроили

#Проверьте Kubernetes Secret

При использовании tkn pac create repo secret с вашими учетными данными GitLab создается автоматически. Проверьте secret:

kubectl get secrets -n <your-namespace>

Пример вывода:

NAME                          TYPE     DATA   AGE
my-repo                       Opaque   2      2m

Посмотрите сведения о secret:

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

Замените <secret-name> на фактическое имя secret (обычно совпадает с именем repository).

Пример вывода (значения закодированы в base64):

apiVersion: v1
kind: Secret
metadata:
  name: my-repo
  namespace: project-pipelines
data:
  provider.token: <base64-encoded-gitlab-token>
  webhook.secret: <base64-encoded-webhook-secret>

Secret содержит:

• provider.token: ваш GitLab personal access token
• webhook.secret: secret для проверки webhook

#Проверьте сгенерированный шаблон

Убедитесь, что шаблон .tekton/pipelinerun.yaml создан в вашем repository:

cat .tekton/pipelinerun.yaml

Пример вывода:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: simple-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 Pipelines as Code!"

#Шаг 6: Проверьте настройку

#Проверьте подключение webhook

Вы можете протестировать webhook из GitLab:

1. Перейдите в GitLab project → Settings → Webhooks
2. Найдите ваш webhook PAC
3. Нажмите Test → Push events
4. Проверьте ответ webhook

#Запустите тестовый pipeline

Создайте простой commit, чтобы запустить pipeline:

echo "test" >> README.md
git add README.md
git commit -m "Test PAC integration"
git push origin main

Проверьте, был ли создан PipelineRun:

kubectl get pipelineruns -n <your-namespace>

Пример вывода:

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

#Ручная настройка (альтернатива)

Если вы предпочитаете настраивать вручную или вам нужен больший контроль, вы можете создать Repository CR и настроить webhook отдельно.

#Создайте Repository CR вручную

Создайте файл repository.yaml:

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

Примените CR:

kubectl apply -f repository.yaml

Пример вывода:

repository.pipelinesascode.tekton.dev/my-repo created

#Создайте Secret GitLab

Создайте secret с вашим GitLab token:

kubectl create secret generic gitlab-secret \
  --from-literal=token=glpat-xxxxxxxxxxxxxxxxxxxx \
  -n project-pipelines

Пример вывода:

secret/gitlab-secret created

#Создайте Webhook Secret

kubectl create secret generic webhook-secret \
  --from-literal=secret=your-webhook-secret \
  -n project-pipelines

Пример вывода:

secret/webhook-secret created

#Настройте GitLab Webhook вручную

1. Перейдите в GitLab project → Settings → Webhooks
2. Добавьте новый webhook:
   • URL: http://pac.example.com
   • Secret token: webhook secret из предыдущего шага
   • Trigger: выберите "Push events" и "Merge request events"
3. Нажмите Add webhook

#Использование private repositories

PAC поддерживает private repositories GitLab. Чтобы настроить аутентификацию для private repositories, см. руководство Configure Authentication for Private Repositories.

В этом руководстве описаны методы аутентификации, которые работают со всеми Git providers, включая:

• Аутентификация с использованием Personal Access Token (PAT)
• Аутентификация с использованием SSH key
• Шаги проверки и устранение неполадок

#Работа с custom certificates

Если ваш GitLab instance использует self-signed certificates или custom CA certificates, необходимо настроить PAC на доверие к этим сертификатам. Подробные инструкции см. в руководстве Configure Custom Certificates.

В этом руководстве рассматриваются:

• Создание ConfigMaps с CA certificates
• Монтирование сертификатов в pod'ы контроллера PAC
• Настройка Git для использования custom certificates
• Шаги проверки и устранение неполадок

#Устранение неполадок

#Проверка, если Repository CR не создан

Проверьте наличие ошибок:

kubectl describe repository <repo-name> -n <your-namespace>

Пример вывода (сокращенно):

Name:         my-repo
Namespace:    project-pipelines
Status:       Ready
Events:
  Type    Reason   Age   From     Message
  ----    ------   ----  ----     -------
  Normal  Ready    5m    pac      Repository validated

#Проверка, если webhook не настроен

Если webhook не был создан автоматически:

1. Убедитесь, что GitLab token имеет scope api
2. Проверьте, что token действителен: curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.com/api/v4/user"
3. Создайте webhook вручную (см. раздел Manual Configuration выше)

#Проверка, если webhook-события не получаются

1. Проверьте логи контроллера PAC:

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100  # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)

Пример вывода:

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Processing webhook event","repository":"my-repo","namespace":"project-pipelines"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"PipelineRun created","pipelineRun":"simple-pipeline-xxxxx"}

2. Убедитесь, что URL webhook доступен из GitLab
3. Проверьте, что webhook secret совпадает и в GitLab, и в Repository CR

#Проверка, если PipelineRun не создаются

1. Проверьте 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

2. Проверьте логи контроллера PAC на наличие ошибок
3. Убедитесь, что .tekton/pipelinerun.yaml существует в вашем repository
4. Проверьте permissions namespace

#Проверка, если есть проблемы с доступом к private repository

1. Проверьте permissions token: убедитесь, что token имеет scope api
2. Проверьте наличие secret: убедитесь, что secret для аутентификации существует в namespace
3. Проверьте Repository CR: убедитесь, что secret указан корректно
4. Проверьте логи PAC: найдите ошибки аутентификации в логах контроллера

Подробнее см. Configure Authentication for Private Repositories.

#Проверка, если есть проблемы с сертификатами

1. Проверьте монтирование сертификата: убедитесь, что сертификат смонтирован в pod
2. Проверьте срок действия сертификата: убедитесь, что сертификат не истек
3. Проверьте конфигурацию Git: убедитесь, что Git настроен на использование сертификата
4. Просмотрите логи: найдите ошибки SSL/сертификатов в логах контроллера PAC

Подробнее см. Configure Custom Certificates.

#Следующие шаги

• Configure Authentication for Private Repositories - Настройка аутентификации для private repositories
• Configure Custom Certificates - Настройка custom CA certificates
• Maintain Pipeline Code - Узнайте, как определять pipeline в вашем repository
• Trigger Pipelines - Узнайте о различных способах запуска
• Common Issues - Руководство по устранению неполадок