#Определение PipelineRun в Git

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

#Расположение файла Pipeline

PAC ищет определения pipeline в определенных расположениях внутри вашего репозитория:

#Расположение по умолчанию

Расположение по умолчанию — .tekton/pipelinerun.yaml в корне вашего репозитория.

your-repo/
├── .tekton/
│   └── pipelinerun.yaml
├── src/
└── README.md

#Несколько файлов Pipeline

Вы можете организовать pipeline в нескольких файлах:

.tekton/
├── pipelinerun.yaml          # Main pipeline
├── test-pipeline.yaml        # Test pipeline
└── deploy-pipeline.yaml      # Deploy pipeline

PAC обработает все файлы .yaml и .yml в каталоге .tekton/.

#Структура определения Pipeline

PAC pipeline — это стандартный ресурс Tekton PipelineRun с аннотациями, специфичными для PAC.

#Базовая структура

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-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 PAC!"

#Использование существующего Pipeline

Вы можете сослаться на существующий ресурс Pipeline, который уже определен в вашем кластере Kubernetes:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineRef:
    name: my-pipeline-resource

#Аннотации событий

PAC использует аннотации, чтобы определять, когда запускать pipeline. Эти аннотации добавляются в metadata PipelineRun. Вы можете сопоставлять разные события Git-провайдера с каждым pipeline, используя специальные аннотации в pipeline run. Если для одного события подходит несколько pipeline run, Pipelines as Code запускает их параллельно и публикует результаты в Git-провайдер сразу после завершения pipeline run.

#Сопоставление события Pull Request с Pipeline Run

Вы можете использовать следующий пример, чтобы сопоставить pipeline с событием pull_request, которое нацелено на ветку main:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-pr-main
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
spec:
  pipelineSpec:
    tasks:
    - name: test
      taskSpec:
        steps:
        - name: test
          image: alpine:latest
          script: |
            echo "Running tests for PR to main"

#Сопоставление события Push с Pipeline Run

Вы можете использовать следующий пример, чтобы сопоставить pipeline с событием push, нацеленным на ветку refs/heads/main:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-push-on-main
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: build
      taskSpec:
        steps:
        - name: build
          image: alpine:latest
          script: |
            echo "Building on push to main"

#Указание веток

Вы можете указать несколько веток, добавив элементы, разделенные запятыми. Например, "[main, release-nightly]". Кроме того, можно указать следующее:

• Полные ссылки на ветки, например "refs/heads/main"
• Globs с сопоставлением по шаблону, например "refs/heads/*"
• Теги, например "refs/tags/1.*"

Примеры:

Несколько веток:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main, release-nightly]"
    pipelinesascode.tekton.dev/on-event: "[push]"

Все ветки с использованием glob:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/*]"
    pipelinesascode.tekton.dev/on-event: "[push]"

Шаблон ветки:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/feature/*]"
    pipelinesascode.tekton.dev/on-event: "[push]"

Теги:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/tags/1.*]"
    pipelinesascode.tekton.dev/on-event: "[push]"

Примечание: Аннотации on-target-branch и on-event являются стандартным форматом, как указано в официальной документации. Для триггеров на основе комментариев используйте аннотацию pipelinesascode.tekton.dev/on-comment.

#Фильтрация по веткам и путям

#Фильтрация по ветке

Фильтруйте по целевой ветке с помощью аннотации on-target-branch. Для сопоставления нескольких веток можно использовать glob patterns:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/feature/*]"
    pipelinesascode.tekton.dev/on-event: "[push]"

Фильтрация по нескольким конкретным веткам:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main, develop]"
    pipelinesascode.tekton.dev/on-event: "[push, pull_request]"

#Фильтрация по пути

Чтобы запускать PipelineRun на основе изменений в определенных путях события, используйте аннотацию pipelinesascode.tekton.dev/on-path-change.

Можно указать несколько путей, разделенных запятыми. Первый glob, который совпадет с файлами, измененными в PR, запустит PipelineRun. Если вам нужно сопоставить файл или путь, содержащий запятую, можно экранировать ее в HTML с помощью сущности ,.

Также необходимо указать тип события и целевую ветку с помощью аннотаций on-target-branch и on-event.

:::important Ограничение аннотации изменения пути

Если вы используете выражение CEL (on-cel-expression), аннотации on-path-change и on-path-change-ignore будут игнорироваться. При использовании CEL для фильтрации по путям используйте выражения CEL со свойствами files.* или функцию .pathChanged().

:::

Пример:

metadata:
  name: pipeline-docs-and-manual
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-path-change: "[docs/**.md, manual/**.rst]"

Эта конфигурация будет соответствовать и запускать PipelineRun, когда событие pull_request нацелено на ветку main и содержит изменения файлов с суффиксом .md в каталоге docs (и его подкаталогах) или файлов с суффиксом .rst в каталоге manual.

Шаблоны путей:

• Используйте glob patterns, а не regex
• src/** - соответствует всем файлам в каталоге src и его подкаталогах
• *.go - соответствует всем файлам Go в корне репозитория
• Для нескольких шаблонов используйте значения, разделенные запятыми: "[src/**,*.go,config/**]"

Проверка glob patterns: CLI tkn pac предоставляет удобную команду globbing для проверки сопоставления glob pattern:

tkn pac info globbing "[PATTERN]"

#Исключение изменений путей

Вы можете использовать обратную аннотацию pipelinesascode.tekton.dev/on-path-change-ignore, чтобы запускать PipelineRun, когда указанные пути не изменились.

По-прежнему необходимо указать тип события и целевую ветку. Если вы используете выражение CEL, аннотация on-path-change-ignore будет игнорироваться.

Этот PipelineRun будет выполняться, когда есть изменения вне каталога docs:

metadata:
  name: pipeline-not-on-docs-change
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-path-change-ignore: "[docs/***]"

#Комбинирование изменения и игнорирования путей

Вы можете комбинировать аннотации on-path-change и on-path-change-ignore:

metadata:
  name: pipeline-docs-not-generated
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-path-change: "[docs/***]"
    pipelinesascode.tekton.dev/on-path-change-ignore: "[docs/generated/***]"

Эта конфигурация запускает PipelineRun, когда есть изменения в каталоге docs, но не в каталоге docs/generated.

Важно: Аннотация on-path-change-ignore всегда имеет приоритет над аннотацией on-path-change. Если файл соответствует обоим шаблонам, PipelineRun не будет запущен.

#Расширенное сопоставление событий

Pipelines as Code поддерживает фильтрацию на основе Common Expression Language (CEL) для расширенного сопоставления событий.

:::important CEL vs сопоставление по аннотациям

• Если вы используете on-cel-expression: PAC будет использовать выражение CEL и игнорировать аннотации on-target-branch и on-event
• Если вы не используете on-cel-expression: PAC будет использовать аннотации on-target-branch и on-event для сопоставления

Нельзя использовать выражения CEL и простые аннотации одновременно. Выберите один подход в зависимости от ваших задач:

• Используйте простые аннотации (on-target-branch, on-event) для базового сопоставления
• Используйте выражения CEL для сложной фильтрации, отрицаний и расширенных условий

:::

По сравнению с простым сопоставлением по аннотации on-target-branch, выражения CEL позволяют выполнять сложную фильтрацию и отрицания.

#Формат выражения CEL

Используйте аннотацию pipelinesascode.tekton.dev/on-cel-expression с выражением CEL:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: cel-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "pull_request" && target_branch == "main"
spec:
  pipelineSpec:
    tasks:
    - name: test
      taskSpec:
        steps:
        - name: test
          image: alpine:latest
          script: |
            echo "Running tests"

#Доступные поля и функции CEL

#Базовые поля

• event: событие push или pull_request
• target_branch: целевая ветка
• source_branch: исходная ветка для события pull_request. Для событий push это то же самое, что и target_branch
• event_title: сопоставляет заголовок события, например заголовок commit для события push и заголовок pull или merge request для события pull_request. Эта документация охватывает GitHub и GitLab.
• last_commit_title: заголовок последнего commit в событии (улучшение Platform — недоступно в upstream Tekton)

#Поля изменения файлов

Эти поля позволяют фильтровать по конкретным изменениям файлов в событии:

• files.all: все измененные файлы (added, modified, deleted, renamed)
• files.added: добавленные файлы
• files.deleted: удаленные файлы
• files.modified: измененные файлы
• files.renamed: переименованные файлы

Примечание: Для pull request будет указан каждый файл, относящийся к pull request. Эти свойства доступны и для событий push, и для событий pull_request.

#Расширенные поля

• body: полное тело payload от Git-провайдера (Technology Preview)
• headers: HTTP-заголовки от Git-провайдера (доступны как map, заголовки всегда в нижнем регистре)

#Функции

• .matches(pattern): сопоставляет строку с шаблоном регулярного выражения
• .pathChanged(): суффиксная функция для строки. Строка может быть glob pattern для проверки, изменился ли путь. В настоящее время в качестве провайдеров поддерживаются только GitHub и GitLab. Примечание: .pathChanged() поддерживает glob patterns, но не поддерживает разные типы изменений (added, modified, deleted). Для более точной фильтрации используйте свойства files.*
• .startsWith(prefix): проверяет, начинается ли строка с указанного префикса
• .contains(substring): проверяет, содержит ли строка указанную подстроку
• .exists(iterator, condition): проверяет, соответствует ли какой-либо элемент в коллекции условию (используется со свойствами files.*)

#Примеры выражений CEL

#Сопоставление Pull Request из конкретной ветки

Чтобы сопоставить событие pull_request, нацеленное на ветку main и исходящее из ветки wip:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "pull_request" &&
      target_branch == "main" &&
      source_branch.startsWith("wip")

#Фильтрация по путям с использованием .pathChanged()

Чтобы запускать pipeline только если путь изменился, можно использовать суффиксную функцию .pathChanged() с glob pattern:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "pull_request" &&
      "docs/*.md".pathChanged()

Это соответствует каждому markdown-файлу в каталоге docs.

#Сопоставление нескольких шаблонов путей

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "push" &&
      ("src/**".pathChanged() || "config/**".pathChanged())

Примечание: .pathChanged() поддерживает glob patterns, но не различает типы изменений файлов (added, modified, deleted, renamed). Для более точной фильтрации используйте свойства files.*, описанные ниже.

#Сопоставление по заголовку события

Чтобы сопоставить все pull request, начинающиеся с заголовка [DOWNSTREAM]:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "pull_request" &&
      event_title.startsWith("[DOWNSTREAM]")

#Исключение ветки

Чтобы запускать pipeline по событию pull_request, но пропускать экспериментальную ветку:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "pull_request" &&
      !source_branch.matches("^experimental.*")

#Пример сложного выражения CEL

Полный пример, объединяющий несколько условий:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |-
      (
        source_branch.matches("^(main|master|release-.*)$") ||
        !event_title.contains("Auto-commit")
      ) && ((
        event == "push" && (
          source_branch.matches("^(main|master|release-.*)$") ||
          target_branch.matches("^(main|master|release-.*)$") ||
          target_branch.startsWith("refs/tags/")
        )
      ) || (
        event == "pull_request" && (
          target_branch.matches("^(main|master|release-.*)$")
        )
      ))

Это выражение:

• Сопоставляет события push или pull_request
• Запускается только для веток main, master или release-* (или тегов)
• Исключает commit с "Auto-commit" в заголовке (если только они не находятся в защищенных ветках)

#Сопоставление PipelineRun по ветке с использованием regex

Сопоставьте имя ветки с помощью регулярных выражений. Например, запускайте PipelineRun для событий pull_request, где имя исходной ветки содержит подстроку feat/:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "pull_request" &&
      source_branch.matches(".*feat/.*")

#Сопоставление PipelineRun по изменениям файлов с использованием свойства Files

Вы можете использовать свойство files для сопоставления конкретных типов изменений файлов. Это более мощно, чем .pathChanged(), поскольку позволяет нацеливаться на конкретные типы изменений (added, modified, deleted, renamed).

Сопоставление любого измененного файла в каталоге tmp:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      files.all.exists(x, x.matches('tmp/'))

Сопоставление любого добавленного файла в каталоге src или pkg:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      files.added.exists(x, x.matches('src/|pkg/'))

Сопоставление измененных файлов с именем test.go:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      files.modified.exists(x, x.matches('test.go'))

Доступные свойства файлов:

• files.all: все измененные файлы (added, modified, deleted, renamed)
• files.added: добавленные файлы
• files.deleted: удаленные файлы
• files.modified: измененные файлы
• files.renamed: переименованные файлы

#Фильтрация PipelineRun для исключения изменений, не относящихся к коду

Исключайте PipelineRun, когда изменяются только файлы документации или конфигурации. Этот пример фильтрует события pull_request, исключая изменения, которые затрагивают только документацию, файлы конфигурации или другие файлы, не относящиеся к коду:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "pull_request" &&
      target_branch == "main" &&
      !files.all.all(x, x.matches('^docs/') || x.matches('\\.md$') || x.matches('(\\.gitignore|OWNERS|PROJECT|LICENSE)$'))

Это выражение будет:

• Сопоставлять только события pull_request, нацеленные на ветку main
• Исключать PipelineRun, если все измененные файлы соответствуют любому из следующих шаблонов:
  • Файлы в каталоге docs/ (^docs/)
  • Markdown-файлы (\\.md$)
  • Стандартные файлы метаданных репозитория (.gitignore, OWNERS, PROJECT, LICENSE)

Примечание: При использовании regex patterns в выражениях CEL не забывайте правильно экранировать специальные символы. Обратную косую черту (\) нужно удваивать (\\), чтобы корректно экранировать ее в контексте строки CEL.

#Сопоставление PipelineRun с заголовком события

Сопоставляйте pull request или commit по их заголовку. event_title будет заголовком pull request для событий pull_request и заголовком commit для событий push:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "pull_request" &&
      event_title.startsWith("[DOWNSTREAM]")

Сопоставление commit, которые не содержат "Auto-commit" в заголовке:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "push" &&
      !event_title.contains("Auto-commit")

#Сопоставление PipelineRun по body payload

Тело payload, переданное Git-провайдером, доступно в переменной CEL как body. Вы можете использовать ее для фильтрации по любым данным, которые отправляет Git-провайдер.

Например, на GitHub сопоставляйте только те события, где pull request нацелен на main, автор — superuser, а действие — synchronize (то есть произошло обновление pull request):

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      body.pull_request.base.ref == "main" &&
      body.pull_request.user.login == "superuser" &&
      body.action == "synchronize"

Важные примечания:

• При сопоставлении body payload в Pull Request комментарии GitOps, такие как /retest, не будут работать ожидаемым образом, потому что body payload становится payload комментария, а не исходного pull request
• Чтобы повторно протестировать Pull Request при использовании CEL по body payload, сделайте фиктивное обновление, внеся и отправив force-push: git commit --amend --no-edit && git push --force-with-lease

#Сопоставление PipelineRun с заголовком запроса

Фильтруйте по заголовкам, отправленным Git-провайдером. Заголовки доступны как список и всегда приводятся к нижнему регистру.

Сопоставляйте только события GitHub pull_request, проверяя заголовок:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      headers['x-github-event'] == "pull_request"

Сопоставляйте только события GitLab merge request:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      headers['x-gitlab-event'] == "Merge Request Hook"

#Отмена выполняющихся pipeline

Аннотация pipelinesascode.tekton.dev/cancel-in-progress позволяет автоматически отменять выполняющийся pipeline, когда запускается новый pipeline того же типа.

#Настройка отмены

Установите аннотацию в "true", чтобы включить автоматическую отмену:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/cancel-in-progress: "true"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from PAC!"

Поведение:

• Когда запускается новый pipeline, например новый push в ту же ветку, любой выполняющийся в данный момент pipeline с той же аннотацией будет автоматически отменен
• Это полезно, чтобы предотвратить одновременный запуск нескольких pipeline в одной и той же ветке
• Отмененные pipeline будут отображаться в Git-провайдере со статусом "Cancelled"

#Примеры использования

Предотвращение дублирующихся запусков в ветке main:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/cancel-in-progress: "true"

Это гарантирует, что если в ветку main быстро поступает несколько push, будет запущен только последний pipeline, что предотвращает расход ресурсов.

Использование с Pull Request:

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/cancel-in-progress: "true"

Когда PR обновляется новым commit, любой выполняющийся pipeline для этого PR будет отменен, и запустится новый.

#Параметризация commit и URL

Вы можете задавать параметры вашего commit и URL, используя динамические расширяемые переменные в формате {{<var>}}. Эти переменные можно использовать в:

• Значения params в PipelineRun
• Параметры Task
• Скрипты и команды step
• Любое строковое значение в определении pipeline

#Доступные переменные

В настоящее время можно использовать следующие переменные:

#Примеры использования переменных

#Информация о Git-репозитории

spec:
  params:
  - name: repo-url
    value: "{{ repo_url }}"
  - name: revision
    value: "{{ revision }}"
  - name: branch
    value: "{{ source_branch }}"
  pipelineSpec:
    tasks:
    - name: clone
      taskSpec:
        steps:
        - name: clone
          image: alpine/git:latest
          script: |
            git clone {{ repo_url }}
            cd {{ repo_name }}
            git checkout {{ revision }}

#Информация о событии

spec:
  params:
  - name: sender
    value: "{{ sender }}"
  - name: branch
    value: "{{ target_branch }}"
  pipelineSpec:
    tasks:
    - name: notify
      taskSpec:
        steps:
        - name: notify
          image: alpine:latest
          script: |
            echo "Pipeline triggered by {{ sender }} on branch {{ target_branch }}"

#Информация о Pull Request

spec:
  params:
  - name: pr-number
    value: "{{ pull_request_number }}"
  pipelineSpec:
    tasks:
    - name: test
      taskSpec:
        steps:
        - name: test
          image: alpine:latest
          script: |
            echo "Testing Pull Request #{{ pull_request_number }}"

Примечание: Переменная {{ pull_request_number }} доступна только для типов событий pull_request. Для событий push эта переменная не заполняется.

#Использование secret аутентификации Git

Для private repositories PAC автоматически генерирует secret для аутентификации Git. Вы можете ссылаться на этот secret в задачах pipeline:

spec:
  pipelineSpec:
    tasks:
    - name: clone
      taskSpec:
        steps:
        - name: clone
          image: alpine/git:latest
          env:
          - name: GIT_CREDENTIALS
            valueFrom:
              secretKeyRef:
                name: "{{ git_auth_secret }}"
                key: password
          script: |
            git clone https://github.com/user/private-repo

Примечание: Переменная {{ git_auth_secret }} доступна только для private repositories. PAC автоматически создает этот secret, когда Repository ссылается на Git access token; см. Создание Git Secret для PAC. Формат имени secret: pac-gitauth-<repository-name>-<hash>.

#Разрешение Task

PAC может автоматически разрешать tasks из нескольких источников. Вы можете использовать либо аннотации PAC (рекомендуется), либо синтаксис Tekton resolver.

#Использование аннотаций PAC (рекомендуется)

PAC предоставляет аннотации для автоматического получения и встраивания удаленных tasks из Tekton Hub. Это проще, чем использование синтаксиса resolver.

#Аннотации удаленных Task

Ссылайтесь на tasks из Tekton Hub с помощью аннотаций:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/task: "git-clone"
    pipelinesascode.tekton.dev/task-1: "golangci-lint"
spec:
  pipelineSpec:
    tasks:
    - name: fetch
      taskRef:
        name: git-clone
      params:
        - name: url
          value: "{{ repo_url }}"
        - name: revision
          value: "{{ revision }}"
    - name: lint
      taskRef:
        name: golangci-lint
      runAfter: [fetch]

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

• Аннотация pipelinesascode.tekton.dev/task: "git-clone" указывает PAC получить task из Tekton Hub
• Используйте нумерованные аннотации (task-1, task-2 и т. д.), чтобы ссылаться на дополнительные tasks
• PAC автоматически встраивает все определенные ссылки на tasks в ваш PipelineRun
• После этого вы можете ссылаться на них с помощью taskRef.name, используя имя task из Tekton Hub

Нумерация аннотаций:

• pipelinesascode.tekton.dev/task: первая task (эквивалент task-0)
• pipelinesascode.tekton.dev/task-1: вторая task
• pipelinesascode.tekton.dev/task-2: третья task
• И так далее...

Подробнее см. в PAC Resolver.

#Использование синтаксиса Resolver

Вы также можете использовать синтаксис resolver Tekton для ссылки на tasks.

#Локальные Task

Ссылайтесь на tasks, определенные в том же репозитории:

.tekton/
├── pipelinerun.yaml
└── tasks/
    └── build-task.yaml

spec:
  pipelineSpec:
    tasks:
    - name: build
      taskRef:
        resolver: git
        params:
        - name: url
          value: "{{ repo_url }}"
        - name: revision
          value: "{{ revision }}"
        - name: pathInRepo
          value: .tekton/tasks/build-task.yaml

#Task из Tekton Hub

Ссылайтесь на tasks из Tekton Hub:

spec:
  pipelineSpec:
    tasks:
    - name: git-clone
      taskRef:
        resolver: hub
        params:
        - name: name
          value: git-clone
        - name: kind
          value: task

#Task по удаленному URL

Ссылайтесь на tasks по удаленным URL с помощью аннотаций PAC (рекомендуется):

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    # PAC automatically handles authentication for remote tasks
    pipelinesascode.tekton.dev/task: "https://raw.githubusercontent.com/tektoncd/catalog/main/task/git-clone/0.9/git-clone.yaml"
spec:
  pipelineSpec:
    tasks:
    - name: build
      taskRef:
        name: git-clone  # Reference the task by name

#Примеры Pipeline

#Простой pipeline сборки

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: build
      taskSpec:
        steps:
        - name: build
          image: golang:1.21
          script: |
            go build -o app ./cmd/app
            go test ./...

#Pipeline тестирования для PR

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: test-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
spec:
  pipelineSpec:
    tasks:
    - name: test
      taskSpec:
        steps:
        - name: run-tests
          image: golang:1.21
          script: |
            go test -v ./...
            go vet ./...
            go fmt ./...

#Многоэтапный pipeline

Этот пример демонстрирует полный CI pipeline с этапами clone, test и build с использованием реального репозитория:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: ci-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[push, pull_request]"
spec:
  workspaces:
  - name: source
    emptyDir: {}
  pipelineSpec:
    workspaces:
    - name: source
    tasks:
    - name: clone
      workspaces:
      - name: source
      taskSpec:
        workspaces:
        - name: source
        steps:
        - name: clone
          image: alpine/git:latest
          script: |
            git clone https://github.com/tektoncd/catalog $(workspaces.source.path)
            cd $(workspaces.source.path)
            echo "Cloned repository successfully"
            ls -la
    - name: check-content
      runAfter: [clone]
      workspaces:
      - name: source
      taskSpec:
        workspaces:
        - name: source
        steps:
        - name: check
          image: alpine:latest
          script: |
            cd $(workspaces.source.path)
            echo "Repository structure:"
            ls -la
            echo "Total files:"
            find . -type f | wc -l
    - name: validate-yaml
      runAfter: [check-content]
      workspaces:
      - name: source
      taskSpec:
        workspaces:
        - name: source
        steps:
        - name: validate
          image: alpine:latest
          script: |
            cd $(workspaces.source.path)
            echo "Checking for YAML files"
            find . -name "*.yaml" -o -name "*.yml" | head -10

#Условный pipeline

Используйте разные pipeline в зависимости от ветки:

# .tekton/pipelinerun-main.yaml
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: main-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: deploy
      taskSpec:
        steps:
        - name: deploy
          image: deploy-tool:latest
          script: |
            deploy.sh production

# .tekton/pipelinerun-develop.yaml
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: develop-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/develop]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: deploy
      taskSpec:
        steps:
        - name: deploy
          image: deploy-tool:latest
          script: |
            deploy.sh staging

#Рекомендуемые практики

#1. Управление версиями

• Храните все определения pipeline в Git
• Проверяйте изменения pipeline через Merge Request
• Помечайте версии pipeline тегами для воспроизводимости

#2. Организация

• Используйте информативные имена pipeline
• Группируйте связанные tasks вместе
• Используйте отдельные файлы для разных типов pipeline

#3. Безопасность

• Не встраивайте secret напрямую в файлы pipeline
• Используйте Kubernetes Secrets для чувствительных данных
• Ограничивайте права pipeline с помощью RBAC

#4. Повторное использование

• Создавайте повторно используемые определения task
• Используйте tasks из Tekton Hub, когда это возможно
• Делитесь общими tasks между репозиториями

#5. Тестирование

• Тестируйте изменения pipeline в feature branches
• Используйте pipeline Merge Request для проверки изменений
• Делайте pipeline простыми и поддерживаемыми

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

#Pipeline не запускается

1. Проверьте, что аннотации указаны корректно:

   cat .tekton/pipelinerun.yaml | grep pipelinesascode.tekton.dev

2. Убедитесь, что имена веток совпадают:

   git branch --show-current

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

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

#Переменные не разрешаются

1. Проверьте синтаксис переменных: используйте формат {{ variable_name }}, например {{ revision }} или {{ repo_url }}
2. Проверьте правильность написания имен переменных: убедитесь, что имена переменных совпадают точно (например, {{ repo_owner }}, {{ source_branch }})
3. Проверьте доступность переменных: некоторые переменные, например {{ pull_request_number }}, доступны только для событий pull_request
4. Просмотрите логи контроллера PAC на наличие ошибок разрешения переменных

#Task не найдены

1. Проверьте, что ссылки на tasks указаны корректно
2. Убедитесь, что файлы task существуют в репозитории
3. Проверьте имена tasks в Tekton Hub
4. Проверьте сетевое подключение для удаленных tasks

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

• PAC Resolver - Узнайте об аннотациях удаленных task и pipeline
• Запуск Pipeline - Узнайте о различных способах запуска
• Руководства - Пошаговые инструкции по настройке репозитория
• Распространенные проблемы - Руководство по устранению неполадок