#Поддержка кода Pipeline

В этом руководстве объясняется, как поддерживать определения pipeline в репозитории исходного кода с помощью PAC.

#Расположение файла 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

Pipeline PAC — это стандартный ресурс 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"
• Glob-шаблоны с сопоставлением по шаблону, например "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-шаблоны для сопоставления нескольких веток:

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 с помощью 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-шаблоны, а не regex
• src/** — соответствует всем файлам в каталоге src и подкаталогах
• *.go — соответствует всем файлам Go в корне репозитория
• Для нескольких шаблонов используйте значения через запятую: "[src/**,*.go,config/**]"

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

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 против сопоставления по аннотациям

• Если вы используете 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: совпадает с заголовком события, например заголовком коммита для события push и заголовком pull или merge request для события pull_request. В настоящее время поддерживаются только GitHub, GitLab и Bitbucket Cloud
• last_commit_title: заголовок последнего коммита в событии (улучшение платформы — недоступно в upstream Tekton)

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

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

• files.all: все измененные файлы (добавленные, измененные, удаленные, переименованные)
• 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): сопоставляет строку с шаблоном regular expression
• .pathChanged(): суффиксная функция для строки. Строка может быть glob-шаблоном для проверки того, изменился ли путь. В настоящее время поддерживаются только GitHub и GitLab. Примечание: .pathChanged() поддерживает glob-шаблоны, но не поддерживает разные типы изменений (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-шаблоном:

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-шаблоны, но не различает типы изменений файлов (added, modified, deleted, renamed). Для более точной фильтрации используйте свойства files.*, описанные ниже.

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

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

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

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

Чтобы запускать pipeline при событии pull_request, но пропускать experimental-ветку:

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-* (или тегов)
• Исключает коммиты с "Auto-commit" в заголовке (если только они не находятся в защищенных ветках)

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

Сопоставление имени ветки с помощью regular expressions. Например, запуск 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: все измененные файлы (добавленные, измененные, удаленные, переименованные)
• 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-шаблонов в выражениях CEL не забывайте правильно экранировать специальные символы. Backslash (\) нужно удваивать (\\), чтобы корректно экранировать его в контексте строки CEL.

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

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

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

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

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

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

Тело 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, выполните фиктивное обновление через amend и force-push: git commit --amend --no-edit && git push --force-with-lease

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

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

Сопоставление только событий 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 run в одной и той же ветке
• Отмененные 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 обновляется новым коммитом, любой выполняющийся pipeline для этого PR будет отменен, и запустится новый.

#Параметризация коммитов и URL

Вы можете задавать параметры коммита и 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 при настройке аутентификации для private repository (см. Настройка аутентификации для private repositories). Формат имени secret: pac-gitauth-<repository-name>-<hash>.

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

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

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

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

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

Ссылки на задачи из 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, что нужно получить задачу из Tekton Hub
• Используйте нумерованные аннотации (task-1, task-2 и т. д.) для ссылки на дополнительные задачи
• PAC автоматически встраивает все указанные определения задач в ваш PipelineRun
• Затем вы можете ссылаться на них через taskRef.name, используя имя задачи из Tekton Hub

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

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

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

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

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

#Локальные Task

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

.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

Ссылка на задачи из Tekton Hub:

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

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

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

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    # PAC автоматически обрабатывает аутентификацию для удаленных задач
    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 Requests
• Помечайте версии pipeline тегами для воспроизводимости

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

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

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

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

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

• Создавайте повторно используемые определения задач
• По возможности используйте задачи Tekton Hub
• Делитесь общими задачами между репозиториями

#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 на наличие ошибок разрешения переменных

#Задачи не найдены

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

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

• PAC Resolver — Узнайте больше об аннотациях для удаленных задач и pipeline
• Trigger Pipelines — Узнайте о различных способах запуска
• Configure Repository — Руководство по настройке репозитория
• Common Issues — Руководство по устранению неполадок