#Основные понятия

Эта страница описывает ресурсы, компоненты runtime и модель триггеров, которые PAC добавляет поверх Tekton. Краткий обзор и карту разделов см. в Introduction.

#Архитектура

PAC запускает в кластере три controller и реагирует на события, поступающие от Git provider:

• PAC Webhook — это HTTP listener, доступный Git provider. Он проверяет каждый входящий запрос по общему webhook secret и пересылает подтвержденные payload в controller. Все, что не проходит проверку, отбрасывается еще до того, как коснется Tekton.
• PAC Controller отвечает за логику «что должно запускаться на это событие». Он находит соответствующий ресурс Repository, извлекает манифесты из .tekton/ для ref, на который указывает событие, фильтрует их по trigger annotations, подставляет переменные и создает PipelineRuns.
• PAC Watcher отслеживает PipelineRuns, созданные PAC, и сообщает их состояние обратно Git provider — в виде GitHub Check Run, commit status или comment, в зависимости от provider.

Все три компонента находятся в namespace PAC (по умолчанию: tekton-pipelines) и разворачиваются Tekton Operator из CR OpenShiftPipelinesAsCode.

#Ресурс Repository

Repository — единственный ресурс, который вы поддерживаете для каждого Git repository. Он связывает один Git URL с одним namespace Kubernetes: события от этого URL создают PipelineRuns в этом namespace и только в нем. Несколько ресурсов Repository могут указывать на один и тот же Git URL только в разных namespace — это типично для схемы «team namespace per environment».

Repository не содержит определений pipeline. Определения pipeline находятся в самом Git repository, в каталоге .tekton/. Удаление Repository только останавливает создание новых PipelineRuns PAC; уже созданные runs остаются без изменений.

#Ключевые поля spec

Пример (GitLab через Webhook):

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

В режиме GitHub App весь блок git_provider опускается; PAC аутентифицируется с помощью учетных данных App уровня кластера, поэтому per-repository token и webhook secret не нужны.

#Два режима интеграции

Git provider может доставлять события в PAC двумя способами, и форма spec Repository меняется в зависимости от режима.

• Режим GitHub App — GitHub App один раз устанавливается на GitHub organization или user. App отвечает за webhook и учетные данные на уровне organization. Любой repository, охваченный установкой, можно подключить с минимальным Repository (только spec.url). Статус передается через GitHub Checks API. Доступно только в GitHub.
• Режим Webhook — Personal Access Token и webhook настраиваются для каждого repository отдельно. Repository ссылается на Kubernetes Secret, содержащий token и webhook secret. Статус передается как commit status. Эта документация описывает режим GitHub Webhook и режим GitLab Webhook.

Эти два режима взаимоисключающи для одного и того же Repository. Пошаговые процедуры для каждого provider приведены в Guides.

#Соглашение о каталоге .tekton/

PAC считывает манифесты PipelineRun из каталога .tekton/ в корне Git repository. Соглашение такое:

• Сканируется любой файл .yaml или .yml в .tekton/. В одном файле может быть больше одного PipelineRun, и в repository может быть больше одного файла.
• Манифесты читаются из ref, на котором было сгенерировано событие — pull request читает исходную branch, push читает branch, в который был выполнен push, tag push читает ref тега.
• Каждый PipelineRun оценивается независимо. Одно событие может привести к нулю, одному или нескольким PipelineRuns в зависимости от того, сколько манифестов совпало.
• Применяется стандартная форма PipelineRun; PAC лишь добавляет поверх нее annotations и variables. Tasks могут быть inline (pipelineSpec), ссылаться на существующий Pipeline в кластере (pipelineRef) или разрешаться в момент отправки из Tekton Hub или удаленного URL.

#Жизненный цикл события

Несколько свойств, которые стоит учитывать:

• Этап проверки на webhook работает по принципу fail-closed: событие с неверной signature не попадает ни в controller, ни в Repository controller, ни в кластер.
• Controller выполняет фильтрацию и подстановку переменных до создания любого объекта Kubernetes, поэтому событие, которое не подходит, не приводит к созданию PipelineRun и не оставляет следов, кроме записи в log.
• Передача status выполняется асинхронно и происходит всякий раз при изменении состояния PipelineRun, включая завершение и сбой отдельных step, если provider поддерживает пошаговую передачу статуса.

#Модель триггеров

Манифесты PipelineRun объявляют события, которые им интересны, с помощью annotations в metadata.annotations. Controller фильтрует манифесты по событию с учетом этих annotations.

#Типы событий

#Грамматика annotations

Для большинства случаев достаточно пары простых matcher (on-event + on-target-branch). Для составных условий («только если PR head совпадает с feature/* И измененные файлы включают api/**») используйте выражение CEL:

annotations:
  pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request" &&
    source_branch.startsWith("feature/") &&
    files.modified.exists(f, f.startsWith("api/"))

Программы CEL получают event, event_title, target_branch, source_branch, body, headers и объект files со списками all, added, deleted, modified и renamed.

Полная грамматика annotations, дополнительные примеры CEL и правила разрешения конфликтов приведены в Define PipelineRuns in Git.

#Переменные и разрешение

В момент создания PipelineRun PAC подставляет небольшой набор шаблонов на основе payload события. Значения закрепляются за PipelineRun после создания; они не пересчитываются.

PAC также может встраивать манифесты Task и Pipeline в момент отправки — локальные файлы, на которые указывают paths, ссылки Tekton Hub по коротким именам или удаленные URL. Resolver выполняется до создания PipelineRun, поэтому итоговый объект является самодостаточным. Синтаксис и поддерживаемые источники см. в PAC Resolver.

#Передача статуса

PAC передает состояние PipelineRun обратно Git provider через три канала, автоматически выбираемые в зависимости от provider и режима интеграции:

• GitHub Checks API — используется в режиме GitHub App. Каждый PipelineRun отображается как Check Run с выводом по каждому step и значком «in progress / success / failure», привязанным к commit.
• Commit statuses — используются в режиме GitHub Webhook и в GitLab. К commit и, где это применимо, к PR / MR публикуется короткая строка статуса.
• Comment — при сбоях в PR / MR добавляется comment, содержащий имя PipelineRun и ссылку на cluster. Точный формат зависит от provider.

URL на стороне cluster, включаемый в эти отчеты о статусе, можно настроить через параметры custom-console-url-* в OpenShiftPipelinesAsCode; см. Manage PAC Component.

#Параллельность и отмена

По умолчанию каждое совпавшее событие немедленно создает свой PipelineRun. Это поведение определяется двумя настройками:

• Repository.spec.concurrency_limit ограничивает число PipelineRuns из этого repository, которые могут выполняться параллельно. Избыточные runs ставятся в очередь и запускаются, когда более старые завершаются.
• Annotation pipelinesascode.tekton.dev/cancel-in-progress на PipelineRun указывает PAC отменить любой более старый run, который соответствует той же группе событий (например, тому же PR), прежде чем запускать новый — это полезно, когда новый push в PR должен сделать предыдущую CI-сборку недействительной.

Это базовые параметры; полный набор дополнительных полей описан в Advanced Repository Configuration.

#Безопасность и доступ

• Payload webhook проверяются по webhook.secret; значение хранится только в cluster Secret и никогда не появляется в событиях или log.
• Git access token (режим Webhook) или private key GitHub App (режим App) также хранится в Kubernetes Secret; token никогда не попадает в spec PipelineRun.
• Repository — namespaced resource; стандартный RBAC Kubernetes определяет, кто может создавать или изменять его. Выдача прав на «read repositories» без «create» позволяет пользователю просматривать, что интегрировано, не изменяя это.
• Передача статуса обратно Git provider всегда использует identity на стороне cluster (App в режиме App, настроенный token в режиме Webhook). Права отдельных отправителей событий не делегируются.

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

• Quick Start — минимальный end-to-end пример.
• Guides — полное пошаговое описание настройки для каждого Git provider.
• Define PipelineRuns in Git — грамматика annotations и layout PipelineRun.
• Common Issues — устранение неполадок.