#Настройка GitHub Repository

Это руководство связывает GitHub repository с PAC от начала до конца: выбор режима интеграции, подготовка учетных данных, создание ресурса Repository и регистрация webhook.

PAC поддерживает два способа интеграции с GitHub:

• GitHub App — один GitHub App устанавливается администратором один раз для GitHub organization (или пользователя). Каждый repository, входящий в установку, затем представляется ресурсом Repository только с URL; настраивать отдельный token или webhook для каждого repository не требуется.
• Webhook — Personal Access Token и webhook настраиваются отдельно для каждого repository. Подходит, если вы не владеете GitHub organization или не можете установить App.

Для одного и того же ресурса Repository эти два режима взаимоисключающие.

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

• Развернутый и доступный компонент PAC; см. Manage PAC Component.
• URL webhook PAC; см. Get the PAC Webhook URL.
• Административный доступ к GitHub repository (для добавления webhook) или к GitHub organization (для установки App).
• Целевая namespace Kubernetes, в которой будут находиться ресурс Repository и его PipelineRun.
• Доступ kubectl к этой namespace.
• tkn CLI с установленным плагином pac, если вы используете tkn pac bootstrap; см. tkn pac Command Reference.

#Выберите режим интеграции

Используйте режим GitHub App, если вы администрируете GitHub organization и планируете подключить много repository. Используйте режим Webhook для разового repository, для repository вне вашей organization или если установка App невозможна.

#Режим интеграции 1: GitHub App

#Как это работает

GitHub App, один раз установленный в GitHub organization или для пользователя, отправляет события для каждого repository, входящего в установку, в контроллер PAC. PAC выполняет аутентификацию в GitHub от имени App. Учетные данные на стороне Kubernetes (App ID, private key, webhook secret) хранятся в cluster-wide Secret в namespace PAC; вам не нужно помещать какие-либо учетные данные для отдельного repository в namespace пользователя.

#Шаг 1 (администратор): Создайте и установите GitHub App

Этот шаг выполняется один раз на cluster администратором cluster.

#Вариант A: Используйте tkn pac bootstrap

tkn pac bootstrap проводит вас через создание GitHub App и сохраняет полученные учетные данные в cluster Secret:

tkn pac bootstrap

Следуйте подсказкам. Команда создает App, генерирует private key и создает Secret pipelines-as-code-secret в namespace PAC.

#Вариант B: Создайте GitHub App вручную

1. Перейдите в GitHub → Settings → Developer settings → GitHub Apps и нажмите New GitHub App.

2. Заполните форму:

   • GitHub App name: любое описательное имя, например Alauda DevOps Pipelines.
   • Homepage URL: URL на ваш выбор, например URL консоли платформы.
   • Webhook URL: URL webhook PAC из предварительных требований.
   • Webhook secret: любая случайная строка. Сохраните ее; на следующем шаге вы сохраните ее в Kubernetes.

3. Задайте Repository permissions:

   Permission	Access
   Checks	Read & Write
   Contents	Read & Write
   Issues	Read & Write
   Metadata	Read-only
   Pull requests	Read & Write

4. Задайте Organization permissions:

   Permission	Access
   Members	Read-only

5. Подпишитесь на события: Check run, Check suite, Commit comment, Issue comment, Pull request, Push.

6. Нажмите Create GitHub App.

7. На странице сведений об App запишите App ID.

8. В разделе Private keys нажмите Generate a private key и сохраните загруженный файл .pem.

Установите App: на странице App нажмите Install App и выберите organization или пользователя, а также repository, которые PAC должен обрабатывать.

#Шаг 2 (администратор): Сохраните учетные данные GitHub App в Kubernetes

Создайте Secret в namespace PAC, который будет содержать App ID, private key и webhook secret. Замените <pac-namespace> (по умолчанию tekton-pipelines), <app-id>, <webhook-secret> и <path-to-private-key>:

kubectl -n <pac-namespace> create secret generic pipelines-as-code-secret \
  --from-literal github-application-id='<app-id>' \
  --from-literal webhook.secret='<webhook-secret>' \
  --from-file github-private-key='<path-to-private-key>'

PAC читает этот Secret при каждом входящем событии. Перезапуск контроллера не требуется.

#Шаг 3 (пользователь): Создайте ресурс Repository

После того как App установлен для GitHub repository, обычный пользователь создает минимальный ресурс Repository в своем namespace. Требуется только URL repository; блок git_provider не нужен.

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://github.com/<owner>/<repo>

Примените его:

kubectl apply -f repository.yaml

Проверьте:

kubectl get repositories -n project-pipelines

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

NAME      URL                                  SUCCEEDED   REASON   STARTTIME   COMPLETIONTIME
my-repo   https://github.com/owner/repo

#Шаг 4 (пользователь): Добавьте PipelineRun и запустите его

Добавьте манифест PipelineRun в .tekton/ в repository и отправьте его. PAC подхватит событие и создаст PipelineRun в namespace. См. Define PipelineRuns in Git для описания структуры файлов и грамматики аннотаций, а также Trigger Pipelines для Git-операций, на которые реагирует PAC.

#Режим интеграции 2: Webhook

#Как это работает

Personal Access Token и webhook настраиваются напрямую для одного GitHub repository. PAC использует token для чтения метаданных repository и публикации commit statuses; webhook secret общий для GitHub и cluster, чтобы PAC мог проверять источник каждого события.

#Шаг 1: Создайте Personal Access Token

Следуйте инструкциям в Create a Git Secret for PAC для получения scopes, требуемых GitHub. Вкратце, достаточно классического Personal Access Token со scope repo (или public_repo только для public repository).

#Шаг 2: Создайте Kubernetes Secret

Создайте Secret, содержащий и Git access token, и webhook secret. Процедуру см. в Create a Git Secret for PAC.

Далее в этом руководстве Secret называется github-webhook-config.

#Шаг 3: Создайте ресурс Repository

Укажите Secret в Repository:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://github.com/<owner>/<repo>
  git_provider:
    secret:
      name: github-webhook-config
    webhook_secret:
      name: github-webhook-config

Примените его:

kubectl apply -f repository.yaml

#Шаг 4: Зарегистрируйте webhook в GitHub

1. Откройте GitHub repository, затем перейдите в Settings → Webhooks → Add webhook.
2. Заполните форму:
   • Payload URL: URL webhook PAC из предварительных требований.
   • Content type: application/json.
   • Secret: то же значение webhook.secret, которое хранится в Kubernetes Secret.
   • SSL verification: включено (рекомендуется).
3. В разделе Which events would you like to trigger this webhook? выберите Let me select individual events и отметьте:
   • Commit comments
   • Issue comments
   • Pull requests
   • Pushes
4. Нажмите Add webhook.

GitHub немедленно отправляет событие ping. Зеленая галочка в записи webhook подтверждает, что PAC его принял.

#Шаг 5: Добавьте PipelineRun и запустите его

То же, что и в режиме App: добавьте PipelineRun в .tekton/ в repository. См. Define PipelineRuns in Git и Trigger Pipelines.

#Проверка

После поступления Git-события PAC создает PipelineRun в namespace Repository. Проверьте:

kubectl get pipelineruns -n project-pipelines \
  -l pipelinesascode.tekton.dev/repository=my-repo

Логи контроллера PAC показывают обработку события:

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100

Для отправки статусов GitHub отображает:

• В режиме App: Check Run в commit с подробным выводом по шагам.
• В режиме Webhook: commit status со ссылкой обратно в cluster.

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

Полную матрицу устранения неполадок см. в Common Issues.

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

• Define PipelineRuns in Git — определяйте и развивайте pipelines в .tekton/.
• Trigger Pipelines — триггеры на основе push, pull request и комментариев.
• Advanced Repository Configuration — concurrency, параметры, пользовательские настройки.
• Configure Custom Certificates — для GitHub Enterprise с private CA.