#Настройка репозитория 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 → Настройки пользователя → Access Tokens (или Настройки проекта → Access Tokens для токенов проекта)
2. Создайте новый токен с:
   • Имя: PAC Integration (или любое описательное имя)
   • Права: выберите api
   • Дата истечения: по необходимости (опционально)
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: 

• По умолчанию: определяется автоматически из удалённого репозитория текущей директории
• Формат: 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 → Настройки → Общие
  • Найдите "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)
• Для самохостинга 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 → Настройки → 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 → Настройки → 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 → Настройки → Webhooks
2. Добавьте новый webhook:
   • URL: http://pac.example.com
   • Секретный токен: секрет 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 имеет права 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. Проверьте права токена: убедитесь, что токен имеет права api
2. Проверьте наличие секрета: убедитесь, что секрет аутентификации существует в пространстве имён
3. Проверьте CR Repository: убедитесь, что секрет корректно указан
4. Проверьте логи PAC: ищите ошибки аутентификации в логах контроллера

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

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

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

Подробности смотрите в Настройка кастомных сертификатов.

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

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