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

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

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

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

• Развернутый и работающий компонент PAC (см. Управление компонентом PAC)
• Доступный и открытый контроллер PAC (через Ingress или NodePort)
• Установленный CLI tkn с плагином pac
• Репозиторий GitLab с правами администратора на уровне репозитория
• Личный токен доступа GitLab с необходимыми правами

#Обзор

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

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

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

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

tkn pac version

Если плагин не установлен, следуйте инструкции по установке в Справочнике команд tkn pac.

#Шаг 2: Подготовка токена доступа GitLab

Вам нужен Личный токен доступа GitLab с следующими правами:

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

#Создание Личного токена доступа

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

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

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

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

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

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

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

Проверьте, открыт ли контроллер PAC через Ingress (замените <pac-namespace> на ваше пространство имён PAC, по умолчанию 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

Если найден, получите хост 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, по умолчанию 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 узла:

# Установите ваше пространство имён PAC (по умолчанию: tekton-pipelines)
PAC_NAMESPACE="tekton-pipelines"

# Получите NodePort
NODEPORT=$(kubectl get service -n ${PAC_NAMESPACE} pipelines-as-code-controller-nodeport -o jsonpath='{.spec.ports[?(@.name=="http-listener")].nodePort}')

# Получите 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, по умолчанию 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

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

# Сначала получите имя сервиса
SERVICE_NAME=$(kubectl get svc -n <pac-namespace> | grep pipelines-as-code-controller | grep LoadBalancer | awk '{print $1}')

# Получите внешний 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

Если ни один из методов не сработал или у вас нет прав на запрос ресурсов кластера:

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

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

#Перейдите в ваш репозиторий

Клонируйте или перейдите в каталог вашего репозитория GitLab:

cd /path/to/your/gitlab-repo

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

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

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

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

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

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

#1. URL Git репозитория

? Enter the Git repository URL: 

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

#2. Пространство имён для пайплайнов

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

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

Важно:

• Пространство имён должно существовать до того, как PAC сможет создавать PipelineRuns в нём

• Если пространства имён нет, создайте его:

  kubectl create namespace <your-namespace>

  Пример:

  kubectl create namespace project-pipelines

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

• В пространстве имён должны быть настроены RBAC права для PAC на создание ресурсов

#3. ID проекта GitLab

? Enter the GitLab project ID: 

• Как найти:
  • Перейдите в ваш проект GitLab → 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): 

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

#5. Секрет webhook

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

• По умолчанию: Автоматически сгенерированная случайная строка
• Описание: Секрет для проверки запросов webhook от GitLab
• Действие: Нажмите Enter для использования значения по умолчанию или введите свой секрет

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

#6. Токен доступа GitLab

? Enter the GitLab access token: 

• Описание: Личный токен доступа, созданный на Шаге 2
• Действие: Вставьте ваш токен

#7. URL API GitLab

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

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

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

? 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: Проверка настройки

#Проверка CR Repository

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

kubectl get repositories --all-namespaces

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

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

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

kubectl get repositories -n <your-namespace>

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

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

Просмотр деталей CR Repository:

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

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

Замените <repo-name> на фактическое имя репозитория из списка (например, 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"

#Проверка webhook GitLab

1. Перейдите в ваш проект GitLab → Settings → Webhooks
2. Убедитесь, что webhook создан с:
   • URL: URL вашего контроллера PAC
   • Триггеры: Push events, Merge request events, Comments
   • Секретный токен: секрет webhook, который вы настроили

#Проверка Kubernetes Secret

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

kubectl get secrets -n <your-namespace>

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

NAME                          TYPE     DATA   AGE
my-repo                       Opaque   2      2m

Просмотр деталей секрета:

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

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

Пример вывода (значения закодированы в 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>

Секрет содержит:

• provider.token: ваш личный токен доступа GitLab
• webhook.secret: секрет для проверки webhook

#Проверка сгенерированного шаблона

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

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 → Settings → Webhooks
2. Найдите ваш webhook PAC
3. Нажмите Test → Push events
4. Проверьте ответ webhook

#Запуск тестового пайплайна

Создайте простой коммит для запуска пайплайна:

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

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

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

#Ручное создание CR Repository

Создайте файл 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

#Создание секрета GitLab

Создайте секрет с вашим токеном GitLab:

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

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

secret/gitlab-secret created

#Создание секрета webhook

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

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

secret/webhook-secret created

#Ручная настройка webhook GitLab

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

#Использование приватных репозиториев

PAC поддерживает приватные репозитории GitLab. Для настройки аутентификации приватных репозиториев смотрите руководство Настройка аутентификации для приватных репозиториев.

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

• Аутентификацию с помощью Личного токена доступа (PAT)
• Аутентификацию по SSH-ключам
• Шаги проверки и устранения неполадок

#Работа с пользовательскими сертификатами

Если ваш экземпляр GitLab использует самоподписанные сертификаты или пользовательские CA-сертификаты, необходимо настроить PAC для доверия этим сертификатам. Смотрите руководство Настройка пользовательских сертификатов для подробных инструкций.

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

• Создание ConfigMap с CA-сертификатами
• Монтирование сертификатов в поды контроллера PAC
• Настройка Git для использования пользовательских сертификатов
• Шаги проверки и устранения неполадок

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

#Проверка, что CR Repository не создан

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

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 имеет scope api
2. Проверьте валидность токена: curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.com/api/v4/user"
3. Создайте webhook вручную (см. раздел Ручная настройка выше)

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

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

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100  # Замените <pac-namespace> на ваше пространство имён (по умолчанию: 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 совпадает в GitLab и CR Repository

#Проверка, что PipelineRuns не создаются

1. Проверьте CR Repository:

   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 существует в вашем репозитории
4. Проверьте права в пространстве имён

#Проверка проблем с доступом к приватным репозиториям

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

Для подробностей смотрите Настройка аутентификации для приватных репозиториев.

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

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

Для подробностей смотрите Настройка пользовательских сертификатов.

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

• Настройка аутентификации для приватных репозиториев — настройка аутентификации для приватных репозиториев
• Настройка пользовательских сертификатов — настройка пользовательских CA-сертификатов
• Поддержка кода пайплайна — как определять пайплайны в вашем репозитории
• Запуск пайплайнов — различные методы запуска пайплайнов
• Распространённые проблемы — руководство по устранению неполадок