Создание репозиториев GitHub

  • Статья

Azure DevOps Services

Azure Pipelines может автоматически создавать и проверять каждый запрос на вытягивание и фиксировать его в репозитории GitHub. В этой статье описывается, как настроить интеграцию между GitHub и Azure Pipelines.

Если вы не знакомы с интеграцией конвейеров с GitHub, выполните действия, описанные в статье Создание первого конвейера. Вернитесь к этой статье, чтобы узнать больше о настройке и настройке интеграции между GitHub и Azure Pipelines.

Организации и пользователи

GitHub и Azure Pipelines — это две независимые службы, которые хорошо интегрируются друг с другом. Каждый из них имеет собственную организацию и управление пользователями. В этом разделе приводятся рекомендации по репликации организации и пользователей из GitHub в Azure Pipelines.

Организации

Структура GitHub состоит из организаций и учетных записей пользователей , содержащих репозитории. См. документацию по GitHub.

Структура организации GitHub

Структура Azure DevOps состоит из организаций , которые содержат проекты. См. раздел Планирование организационной структуры.

Структура организации Azure DevOps

Azure DevOps может отражать структуру GitHub с помощью:

  • Организация DevOps для вашей организации или учетной записи пользователя GitHub
  • DevOps Projects для репозиториев GitHub

Структура GitHub, сопоставленная с Azure DevOps

Чтобы настроить идентичную структуру в Azure DevOps, выполните приведенные далее действия.

  1. Создайте организацию DevOps с именем вашей организации или учетной записи пользователя GitHub. Он будет иметь URL-адрес, например https://dev.azure.com/your-organization.
  2. В организации DevOps создайте проекты с именем ваших репозиториев. У них будут ТАКИЕ URL-адреса, как https://dev.azure.com/your-organization/your-repository.
  3. В проекте DevOps создайте конвейеры с именем организации GitHub и репозиторий, который они создают, например your-organization.your-repository. Затем ясно, для каких репозиториев они нужны.

В соответствии с этим шаблоном репозитории GitHub и Проекты Azure DevOps будут иметь совпадающие пути URL-адресов. Пример:

Служба URL-адрес
GitHub https://github.com/python/cpython
Azure DevOps https://dev.azure.com/python/cpython

Пользователи

Пользователи GitHub не получают автоматический доступ к Azure Pipelines. Azure Pipelines не знает об удостоверениях GitHub. По этой причине невозможно настроить Azure Pipelines для автоматического уведомления пользователей о сбое сборки или сбое проверки запроса на вытягивание, используя их удостоверение и адрес электронной почты GitHub. Необходимо явно создать новых пользователей в Azure Pipelines для репликации пользователей GitHub. После создания новых пользователей вы можете настроить их разрешения в Azure DevOps, чтобы отразить их разрешения в GitHub. Вы также можете настроить уведомления в DevOps с помощью удостоверения DevOps.

Роли организации GitHub

Роли участников организации GitHub находятся по адресу https://github.com/orgs/your-organization/people (замените your-organization).

Разрешения участников организации DevOps находятся по адресу https://dev.azure.com/your-organization/_settings/security (замените your-organization).

Ниже приведены роли в организации GitHub и эквивалентные роли в организации Azure DevOps.

Роль организации GitHub Эквивалент организации DevOps
Владелец Член Project Collection Administrators
Менеджер по выставлению счетов Член Project Collection Administrators
Член Член .Project Collection Valid Users По умолчанию группа участников не имеет разрешения на создание новых проектов. Чтобы изменить разрешение, задайте для группы Create new projects значение Allowили создайте новую группу с нужными разрешениями.

Роли учетной записи пользователя GitHub

Учетная запись пользователя GitHub имеет одну роль, которая является владельцем учетной записи.

Разрешения участников организации DevOps находятся по адресу https://dev.azure.com/your-organization/_settings/security (замените your-organization).

Роль учетной записи пользователя GitHub сопоставляется с разрешениями организации DevOps следующим образом.

Роль учетной записи пользователя GitHub Эквивалент организации DevOps
Владелец Член Project Collection Administrators

Разрешения репозитория GitHub

Разрешения репозитория GitHub находятся по адресу https://github.com/your-organization/your-repository/settings/collaboration (замените your-organization и your-repository).

Разрешения проекта DevOps находятся по адресу https://dev.azure.com/your-organization/your-project/_settings/security (замените your-organization и your-project).

Ниже приведены эквивалентные разрешения для репозиториев GitHub и Azure DevOps Projects.

Разрешение репозитория GitHub Эквивалент проекта DevOps
Административный Член Project Administrators
Write Член Contributors
Read Член Readers

Если репозиторий GitHub предоставляет разрешения для команд, вы можете создать соответствующие команды в Teams разделе параметров проекта Azure DevOps. Затем добавьте команды в указанные выше группы безопасности, как и пользователи.

Разрешения, относящиеся к конвейеру

Чтобы предоставить разрешения пользователям или командам для определенных конвейеров в проекте DevOps, выполните следующие действия.

  1. Посетите страницу конвейеров проекта (например, https://dev.azure.com/your-organization/your-project/_build).
  2. Выберите конвейер, для которого необходимо задать определенные разрешения.
  3. В контекстном меню "..." выберите Безопасность.
  4. Выберите Добавить... , чтобы добавить определенного пользователя, команду или группу и настроить их разрешения для конвейера.

Доступ к репозиториям GitHub

Чтобы создать новый конвейер, сначала выберите репозиторий GitHub, а затем YAML-файл в этом репозитории. Репозиторий, в котором присутствует YAML-файл, называется self репозиторием. По умолчанию это репозиторий, который выполняет сборки конвейера.

Позже вы сможете настроить конвейер для проверка из другого репозитория или нескольких репозиториев. Сведения о том, как это сделать, см. в разделе Извлечение из нескольких репозиторий.

Azure Pipelines необходимо предоставить доступ к репозиториям, чтобы активировать сборки и получить код во время сборки.

Существует три типа проверки подлинности для предоставления Azure Pipelines доступа к репозиториям GitHub при создании конвейера.

Authentication type (Тип проверки подлинности) Конвейеры выполняются с помощью Работает с проверками GitHub
1. Приложение GitHub Удостоверение Azure Pipelines Да
2. OAuth Ваше личное удостоверение GitHub Нет
3. Личный маркер доступа (PAT) Ваше личное удостоверение GitHub Нет

Проверка подлинности приложения GitHub

Приложение GitHub Azure Pipelines — это рекомендуемый тип проверки подлинности для конвейеров непрерывной интеграции. После установки Приложение GitHub в учетной записи или организации GitHub конвейер будет выполняться без использования личного удостоверения GitHub. Сборки и обновления состояния GitHub будут выполняться с помощью удостоверения Azure Pipelines. Приложение работает с GitHub Checks для отображения результатов сборки, тестирования и покрытия кода в GitHub.

Чтобы использовать Приложение GitHub, установите его в организации или учетной записи пользователя GitHub для некоторых или всех репозиториев. Приложение GitHub можно установить и удалить с домашней страницы приложения.

После установки Приложение GitHub станет стандартным методом проверки подлинности Azure Pipelines для GitHub (а не OAuth) при создании конвейеров для репозиториев.

Если вы устанавливаете Приложение GitHub для всех репозиториев в организации GitHub, вам не нужно беспокоиться об отправке массовых сообщений электронной почты в Azure Pipelines или автоматической настройке конвейеров от вашего имени. В качестве альтернативы установке приложения для всех репозиториев администраторы репозиториев могут устанавливать его по одному для отдельных репозиториев. Это требует больше работы для администраторов, но не имеет ни преимуществ, ни недостатков.

Необходимые разрешения в GitHub

Для установки приложения GitHub Azure Pipelines необходимо быть администратором владелец организации или репозитория GitHub. Кроме того, чтобы создать конвейер для репозитория GitHub с триггерами непрерывной интеграции и запросов на вытягивание, необходимо настроить необходимые разрешения GitHub. В противном случае репозиторий не будет отображаться в списке репозитория при создании конвейера. В зависимости от типа проверки подлинности и владельца репозитория убедитесь, что настроен соответствующий доступ.

  • Если репозиторий находится в вашей личной учетной записи GitHub, установите Приложение GitHub Azure Pipelines в личной учетной записи GitHub, и вы сможете получить список этого репозитория при создании конвейера в Azure Pipelines.

  • Если репозиторий находится в личной учетной записи GitHub другого пользователя, другой пользователь должен установить Приложение GitHub Azure Pipelines в личной учетной записи GitHub. Вы должны быть добавлены в качестве участника совместной работы в параметрах репозитория в разделе "Участники совместной работы". Примите приглашение стать участниками совместной работы, используя ссылку, отправленную вам по электронной почте. После этого можно создать конвейер для этого репозитория.

  • Если репозиторий находится в организации GitHub, принадлежащей вам, установите Приложение GitHub Azure Pipelines в организации GitHub. Вы также должны быть добавлены в качестве участника совместной работы или ваша команда должна быть добавлена в параметрах репозитория в разделе "Участники совместной работы и команды".

  • Если репозиторий находится в организации GitHub, принадлежащей другому пользователю, администратор владелец организации или репозитория GitHub должен установить Приложение GitHub Azure Pipelines в организации. Вы должны быть добавлены в качестве участника совместной работы или ваша команда в параметрах репозитория в разделе "Участники совместной работы и команды". Примите приглашение стать участниками совместной работы, используя ссылку, отправленную вам по электронной почте.

разрешения Приложение GitHub

Во время установки Приложение GitHub запрашивает следующие разрешения:

Разрешение Использование разрешения в Azure Pipelines
Доступ на запись к коду Только после преднамеренных действий Azure Pipelines упростит создание конвейера, зафиксировав YAML-файл в выбранной ветви репозитория GitHub.
Доступ на чтение к метаданным Azure Pipelines получит метаданные GitHub для отображения репозитория, ветвей и проблем, связанных со сборкой, в сводке сборки.
Доступ на чтение и запись для проверок Azure Pipelines будет считывать и записывать собственные результаты сборки, тестирования и покрытия кода, которые будут отображаться в GitHub.
Доступ на чтение и запись к запросам на вытягивание Только после преднамеренных действий Azure Pipelines упростит создание конвейера, создав запрос на вытягивание для файла YAML, который был зафиксирован в выбранной ветви репозитория GitHub. Конвейеры извлекают метаданные запроса для отображения в сводках сборки, связанных с запросами на вытягивание.

Устранение неполадок с установкой Приложение GitHub

GitHub может отобразить ошибку, например:

You do not have permission to modify this app on your-organization. Please contact an Organization Owner.

Это означает, что Приложение GitHub, скорее всего, уже установлена для вашей организации. При создании конвейера для репозитория в организации для подключения к GitHub будет автоматически использоваться Приложение GitHub.

Создание конвейеров в нескольких организациях и проектах Azure DevOps

После установки Приложение GitHub можно создать конвейеры для репозиториев организации в разных организациях и проектах Azure DevOps. Однако при создании конвейеров для одного репозитория в нескольких организациях Azure DevOps только конвейеры первой организации могут автоматически активироваться фиксациями или запросами на вытягивание GitHub. Сборки вручную или по расписанию по-прежнему возможны в дополнительных организациях Azure DevOps.

Аутентификация OAuth

OAuth — это самый простой тип проверки подлинности для репозиториев в личной учетной записи GitHub. Обновления состояния GitHub будут выполняться от имени личного удостоверения GitHub. Чтобы конвейеры не перестали работать, доступ к репозиторию должен оставаться активным. Некоторые функции GitHub, такие как проверки, недоступны в OAuth и требуют Приложение GitHub.

Чтобы использовать OAuth, выберите Выбрать другое подключение под списком репозиториев при создании конвейера. Затем выберите Авторизовать , чтобы войти в GitHub и авторизоваться с помощью OAuth. Подключение OAuth будет сохранено в проекте Azure DevOps для последующего использования и использовано в создаваемом конвейере.

Необходимые разрешения в GitHub

Чтобы создать конвейер для репозитория GitHub с непрерывной интеграцией и триггерами запросов на вытягивание, необходимо настроить необходимые разрешения GitHub. В противном случае репозиторий не будет отображаться в списке репозитория при создании конвейера. В зависимости от типа проверки подлинности и владельца репозитория убедитесь, что настроен соответствующий доступ.

  • Если репозиторий находится в вашей личной учетной записи GitHub, по крайней мере один раз, выполните проверку подлинности в GitHub с помощью OAuth, используя свои личные учетные данные учетной записи GitHub. Это можно сделать в параметрах проекта Azure DevOps в разделе Подключения к службе конвейеров > Новое подключение > к службе GitHub > Authorize.> Предоставьте Azure Pipelines доступ к репозиториям в разделе "Разрешения".

  • Если репозиторий находится в личной учетной записи GitHub другого пользователя, по крайней мере один раз, другой пользователь должен пройти проверку подлинности в GitHub с помощью OAuth, используя свои личные учетные данные учетной записи GitHub. Это можно сделать в параметрах проекта Azure DevOps в разделе Подключения к службе конвейеров > Новое подключение > к службе GitHub > Authorize.> Другой пользователь должен предоставить Azure Pipelines доступ к своим репозиториям в разделе "Разрешения". Вы должны быть добавлены в качестве участника совместной работы в параметрах репозитория в разделе "Участники совместной работы". Примите приглашение стать участниками совместной работы, используя ссылку, отправленную вам по электронной почте.

  • Если репозиторий находится в организации GitHub, которую вы владеете, по крайней мере один раз, выполните проверку подлинности в GitHub с помощью OAuth, используя ваши личные учетные данные учетной записи GitHub. Это можно сделать в параметрах проекта Azure DevOps в разделе Подключения к службе конвейеров > Новое подключение > к службе GitHub > Authorize.> Предоставьте Azure Pipelines доступ к вашей организации в разделе "Доступ к организации". Вы должны быть добавлены в качестве участника совместной работы или ваша команда в параметрах репозитория в разделе "Участники совместной работы и команды".

  • Если репозиторий находится в организации GitHub, принадлежащей другому пользователю, хотя бы один раз, владелец организации GitHub должны пройти проверку подлинности в GitHub с помощью OAuth с использованием личных учетных данных учетной записи GitHub. Это можно сделать в параметрах проекта Azure DevOps в разделе Подключения к службе конвейеров > Новое подключение > к службе GitHub > Authorize.> Владелец организации должен предоставить Azure Pipelines доступ к организации в разделе "Доступ к организации". Вы должны быть добавлены в качестве участника совместной работы или ваша команда в параметрах репозитория в разделе "Участники совместной работы и команды". Примите приглашение стать участниками совместной работы, используя ссылку, отправленную вам по электронной почте.

Отмена доступа OAuth

После авторизации Azure Pipelines для использования OAuth, чтобы позже отозвать его и предотвратить дальнейшее использование, перейдите на страницу Приложения OAuth в параметрах GitHub. Вы также можете удалить его из списка подключений к службе GitHub в параметрах проекта Azure DevOps.

Проверка подлинности с помощью личного маркера доступа (PAT)

PaTs фактически такие же, как OAuth, но позволяют контролировать, какие разрешения предоставляются Azure Pipelines. Сборки и обновления состояния GitHub будут выполняться от имени личного удостоверения GitHub. Чтобы сборки продолжались, доступ к репозиторию должен оставаться активным.

Чтобы создать PAT, перейдите на страницу Личные маркеры доступа в параметрах GitHub. Необходимые разрешения: repo, admin:repo_hook, read:userи user:email. Это те же разрешения, необходимые при использовании OAuth выше. Скопируйте созданный pat в буфер обмена и вставьте его в новое подключение к службе GitHub в параметрах проекта Azure DevOps. Для последующего отзыва назовите подключение службы именем имени пользователя GitHub. Он будет доступен в проекте Azure DevOps для последующего использования при создании конвейеров.

Необходимые разрешения в GitHub

Чтобы создать конвейер для репозитория GitHub с непрерывной интеграцией и триггерами запросов на вытягивание, необходимо настроить необходимые разрешения GitHub. В противном случае репозиторий не будет отображаться в списке репозитория при создании конвейера. В зависимости от типа проверки подлинности и владельца репозитория убедитесь, что настроен указанный ниже доступ.

  • Если репозиторий находится в вашей личной учетной записи GitHub, pat должен иметь необходимые области доступа в разделе Личные маркеры доступа: repo, admin:repo_hook, read:userи user:email.

  • Если репозиторий находится в личной учетной записи GitHub другого пользователя, pat должен иметь необходимые области доступа в разделе Личные маркеры доступа: repo, admin:repo_hook, read:userи user:email. Вы должны быть добавлены в качестве участника совместной работы в параметрах репозитория в разделе "Участники совместной работы". Примите приглашение стать участниками совместной работы, используя ссылку, отправленную вам по электронной почте.

  • Если репозиторий находится в организации GitHub, которую вы владеете, pat должен иметь необходимые области доступа в разделе Личные маркеры доступа: repo, admin:repo_hook, read:userи user:email. Вы должны быть добавлены в качестве участника совместной работы или ваша команда в параметрах репозитория в разделе "Участники совместной работы и команды".

  • Если репозиторий находится в организации GitHub, владельцем которых является кто-то другой, pat должен иметь необходимые области доступа в разделе Личные маркеры доступа: repo, admin:repo_hook, read:userи user:email. Вы должны быть добавлены в качестве участника совместной работы или ваша команда в параметрах репозитория в разделе "Участники совместной работы и команды". Примите приглашение стать участниками совместной работы, используя ссылку, отправленную вам по электронной почте.

Отмена доступа к PAT

После авторизации Azure Pipelines для использования PAT, а затем удалить его и предотвратить дальнейшее использование, перейдите на страницу Личные маркеры доступа в параметрах GitHub. Вы также можете удалить его из списка подключений к службе GitHub в параметрах проекта Azure DevOps.

Триггеры CI

Триггеры непрерывной интеграции (CI) приводят к запуску конвейера при отправке обновления в указанные ветви или при отправке указанных тегов.

Конвейеры YAML настраиваются по умолчанию с помощью триггера CI во всех ветвях.

Ветви

Вы можете управлять тем, какие ветви получают триггеры CI, с помощью простого синтаксиса:

trigger:
- main
- releases/*

Можно указать полное имя ветви (например, main) или подстановочный знак (например, releases/*). Сведения о синтаксисе с подстановочными знаками см. в разделе Подстановочные знаки.

Примечание

Нельзя использовать переменные в триггерах, так как переменные оцениваются во время выполнения (после срабатывания триггера).

Примечание

Если для создания файлов YAML используются шаблоны, триггеры можно указать только в файле YAML main для конвейера. Невозможно указать триггеры в файлах шаблонов.

Для более сложных триггеров, использующих exclude или batch, необходимо использовать полный синтаксис, как показано в следующем примере.

# specific branch build
trigger:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

В приведенном выше примере конвейер активируется, если изменение передается в main ветвь выпусков или в нее. Однако она не будет активирована, если в ветвь выпусков, начинающаяся с old, не активируется .

Если указать exclude предложение без include предложения , это эквивалентно указанию * в предложении include .

Помимо указания имен ветвей в branches списках, можно также настроить триггеры на основе тегов в следующем формате:

trigger:
  branches:
    include:
      - refs/tags/{tagname}
    exclude:
      - refs/tags/{othertagname}

Если триггеры не указаны, по умолчанию используется следующий код:

trigger:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

Важно!

При указании триггера он заменяет неявный триггер по умолчанию, и только отправки в ветви, которые явно настроены для включения, активируют конвейер. Сначала обрабатываются включения, а затем исключения удаляются из этого списка.

Выполнение CI пакетной обработки

Если у вас есть много участников команды, которые часто отправляют изменения, вам может потребоваться уменьшить количество запускаемых запусков. Если задано значение batchtrue, при выполнении конвейера система ожидает завершения выполнения, а затем запускает еще один запуск со всеми еще не созданными изменениями.

# specific branch build with batching
trigger:
  batch: true
  branches:
    include:
    - main

Примечание

batch не поддерживается в триггерах ресурсов репозитория.

Чтобы уточнить этот пример, предположим, что отправка A в main вызвала выполнение приведенного выше конвейера. Во время выполнения этого конвейера в репозиторий выполняются дополнительные отправки B и C . Эти обновления не запускают новые независимые запуски сразу. Но после завершения первого запуска все отправки до этого момента времени объединяются вместе и запускается новый запуск.

Примечание

Если конвейер содержит несколько заданий и этапов, первое выполнение должно по-прежнему достичь конечного состояния, завершив или пропустив все свои задания и этапы до начала второго запуска. По этой причине следует проявлять осторожность при использовании этой функции в конвейере с несколькими этапами или утверждениями. Если вы хотите пакетировать сборки в таких случаях, рекомендуется разделить процесс CI/CD на два конвейера: один для сборки (с пакетной обработкой) и один для развертываний.

Пути

Вы можете указать пути к файлам для включения или исключения.

# specific path build
trigger:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

При указании путей необходимо явно указать ветви для активации, если используется Azure DevOps Server 2019.1 или более поздней версии. Вы не можете активировать конвейер только с фильтром пути; Необходимо также иметь фильтр ветви, а измененные файлы, соответствующие фильтру пути, должны быть из ветви, соответствующей фильтру ветвей. Если вы используете Azure DevOps Server 2020 или более поздней версии, вы можете опустить branches фильтрацию по всем ветвям в сочетании с фильтром пути.

Для фильтров путей поддерживаются подстановочные карточки. Например, можно включить все пути, соответствующие src/app/**/myapp*. При указании фильтров пути можно использовать дикие карта символы (**, *или ?) ).

  • Пути всегда указываются относительно корня репозитория.
  • Если фильтры путей не заданы, корневая папка репозитория неявно включается по умолчанию.
  • Если вы исключите путь, вы также не сможете включить его, если не квалифицировать его в более глубокую папку. Например, если исключить /tools, можно включить /tools/trigger-runs-on-these.
  • Порядок фильтров путей не имеет значения.
  • Пути в Git чувствительны к регистру. Обязательно используйте тот же вариант, что и для реальных папок.
  • Нельзя использовать переменные в путях, так как переменные оцениваются во время выполнения (после срабатывания триггера).

Теги

Помимо указания тегов в branches списках, как описано в предыдущем разделе, можно напрямую указать теги для включения или исключения:

# specific tag
trigger:
  tags:
    include:
    - v2.*
    exclude:
    - v2.0

Если не указать триггеры тегов, по умолчанию теги не будут запускать конвейеры.

Важно!

Если вы укажете теги в сочетании с фильтрами ветвей, триггер сработает, если выполняется фильтр ветви или фильтр тегов. Например, если отправленный тег удовлетворяет фильтру ветви, конвейер активируется, даже если тег исключается фильтром тегов, так как отправка удовлетворяет фильтру ветви.

Отказ от CI

Отключение триггера CI

Вы можете полностью отказаться от триггеров CI, указав trigger: none.

# A pipeline with no CI trigger
trigger: none

Важно!

При отправке изменений в ветвь YAML-файл в этой ветви оценивается так, чтобы определить, следует ли запускать выполнение CI.

Пропуск CI для отдельных фиксаций

Вы также можете указать Azure Pipelines пропустить запуск конвейера, который обычно активируется при отправке. Просто включите [skip ci] в сообщение или описание любой из фиксаций, которые являются частью отправки, и Azure Pipelines пропустит выполнение CI для этой отправки. Можно также использовать любой из следующих вариантов.

  • [skip ci] или [ci skip]
  • skip-checks: true или skip-checks:true
  • [skip azurepipelines] или [azurepipelines skip]
  • [skip azpipelines] или [azpipelines skip]
  • [skip azp] или [azp skip]
  • ***NO_CI***

Использование типа триггера в условиях

Это распространенный сценарий для выполнения различных шагов, заданий или этапов в конвейере в зависимости от типа триггера, который запустил выполнение. Это можно сделать с помощью системной переменной Build.Reason. Например, добавьте следующее условие в шаг, задание или этап, чтобы исключить его из проверок запроса на вытягивание.

condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))

Поведение триггеров при создании новых ветвей

Обычно для одного репозитория настраивается несколько конвейеров. Например, у вас может быть один конвейер для создания документации для приложения, а другой — для сборки исходного кода. Триггеры CI можно настроить с помощью соответствующих фильтров ветвей и фильтров путей в каждом из этих конвейеров. Например, может потребоваться, чтобы один конвейер активировался при отправке обновления в docs папку, а другой — при отправке обновления в код приложения. В таких случаях необходимо понимать, как конвейеры активируются при создании новой ветви.

Ниже описано поведение при отправке новой ветви (которая соответствует фильтрам ветви) в репозиторий:

  • Если в конвейере есть фильтры путей, он активируется только в том случае, если новая ветвь содержит изменения в файлах, соответствующих фильтру путей.
  • Если в конвейере нет фильтров путей, он будет активирован, даже если в новой ветви нет изменений.

подстановочные знаки;

При указании ветви, тега или пути можно использовать точное имя или подстановочный знак. Шаблоны подстановочных знаков позволяют * сопоставлять ноль или более символов и ? сопоставлять один символ.

  • Если вы запускаете шаблон с * в конвейере YAML, необходимо заключит шаблон в кавычки, например "*-releases".
  • Для ветвей и тегов:
    • Подстановочный знак может отображаться в любом месте шаблона.
  • Для путей:
    • В Azure DevOps Server 2022 и более поздних версиях, включая Azure DevOps Services, подстановочный знак может отображаться в любом месте шаблона пути, и вы можете использовать * или ?.
    • В Azure DevOps Server 2020 и более низких версиях вы можете включить * в качестве конечного символа, но он не делает ничего другого, чем указание имени каталога само по себе. Вы можете не включать * в середину фильтра пути и не использовать ?.
trigger:
  branches:
    include:
    - main
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

Триггеры запроса на вытягивание

Триггеры запроса на вытягивание (PR) вызывают запуск конвейера при открытии запроса на вытягивание в одной из указанных целевых ветвей или при обновлении такого запроса на вытягивание.

Ветви

Вы можете указать целевые ветви при проверке запросов на вытягивание. Например, для проверки запросов на вытягивание, предназначенных для main и releases/*, можно использовать следующий pr триггер.

pr:
- main
- releases/*

Эта конфигурация запускает новый запуск при первом создании нового запроса на вытягивание и после каждого обновления запроса на вытягивание.

Можно указать полное имя ветви (например, main) или подстановочный знак (например, releases/*).

Примечание

Нельзя использовать переменные в триггерах, так как переменные оцениваются во время выполнения (после срабатывания триггера).

Примечание

Если для создания файлов YAML используются шаблоны, триггеры можно указать только в файле YAML main для конвейера. Триггеры нельзя указать в файлах шаблонов.

GitHub создает ссылку при создании запроса на вытягивание. Ссылка указывает на фиксацию слияния, которая представляет собой объединенный код между исходной и целевой ветвями запроса на вытягивание. Конвейер проверки запроса на вытягивание создает фиксацию, на которую указывает ссылка . Это означает, что ФАЙЛ YAML, используемый для запуска конвейера, также является слиянием между исходной и целевой ветвями. В результате изменения, внесенные в файл YAML в исходной ветви запроса на вытягивание, могут переопределить поведение, определенное файлом YAML в целевой ветви.

Если триггеры не pr отображаются в файле YAML, проверка запросов на вытягивание автоматически включается для всех ветвей, как если бы вы написали следующий pr триггер. Эта конфигурация активирует сборку при создании любого запроса на вытягивание и при попадании фиксаций в исходную ветвь любого активного запроса на вытягивание.

pr:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

Важно!

При указании триггера pr с подмножеством ветвей конвейер активируется только при отправке обновлений в эти ветви.

Для более сложных триггеров, которые должны исключать определенные ветви, необходимо использовать полный синтаксис, как показано в следующем примере. В этом примере запросы на вытягивание проверяются, что целевой main объект или , releases/* а ветвь releases/old* исключена.

# specific branch
pr:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

Пути

Можно указать пути к файлам для включения или исключения. Пример:

# specific path
pr:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

Советы

  • Azure Pipelines отправляет нейтральное состояние обратно в GitHub, когда он решает не запускать проверию сборки из-за правила исключения пути. Это дает четкое направление для GitHub, указывающее, что Azure Pipelines завершил обработку. Дополнительные сведения см. в разделе Публикация нейтрального состояния в GitHub при пропуске сборки.
  • Теперь с фильтрами путей поддерживаются подстановочные знаки.
  • Пути всегда указываются относительно корневого каталога репозитория.
  • Если фильтры путей не заданы, корневая папка репозитория будет включена неявно по умолчанию.
  • Если вы исключите путь, вы также не сможете включить его, пока не укажете его в более глубокой папке. Например, если исключить /tools, можно включить /tools/trigger-runs-on-these.
  • Порядок фильтров пути не имеет значения.
  • В путях в Git учитывается регистр. Обязательно используйте тот же вариант, что и для реальных папок.
  • Нельзя использовать переменные в путях, так как переменные вычисляются во время выполнения (после срабатывания триггера).
  • Azure Pipelines отправляет нейтральное состояние обратно в GitHub, когда он решает не запускать проверию сборки из-за правила исключения пути.

Несколько обновлений запроса на вытягивание

Вы можете указать, должны ли другие обновления запроса на вытягивание отменять выполняющиеся запуски проверки для того же запроса на вытягивание. Значение по умолчанию — true.

# auto cancel false
pr:
  autoCancel: false
  branches:
    include:
    - main

Проверка черновика запроса на вытягивание

По умолчанию триггеры запросов на вытягивание срабатывают для черновых запросов на вытягивание и запросов на вытягивание, готовых к проверке. Чтобы отключить триггеры запросов на вытягивание для черновых запросов на drafts вытягивание, задайте для свойства значение false.

pr:
  autoCancel: boolean # indicates whether additional pushes to a PR should cancel in-progress runs for the same PR. Defaults to true
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build
  drafts: boolean # whether to build draft PRs, defaults to true

Отказ от проверки запроса на вытягивание

Вы можете полностью отказаться от проверки запроса на вытягивание, указав pr: none.

# no PR triggers
pr: none

Дополнительные сведения см. в разделе Триггер запроса на вытягивание в схеме YAML.

Примечание

pr Если триггер не срабатывает, выполните действия по устранению неполадок в разделе Вопросы и ответы.

Примечание

Черновики запросов на вытягивание не активируют конвейер.

Если у вас есть открытый запрос на вытягивание и вы отправляете изменения в ее исходную ветвь, может выполняться несколько конвейеров:

  • Конвейеры с триггером запроса на вытягивание в целевой ветви запроса на вытягивание будут выполняться при фиксации слияния (объединенном коде между исходной и целевой ветвями запроса на вытягивание), независимо от того, существуют ли отправленные фиксации, сообщения или описания которых содержатся [skip ci] (или любой из его вариантов).
  • Конвейеры, активированные изменениями в исходной ветви запроса на вытягивание, если нет отправленных фиксаций, содержащих сообщения или описания [skip ci] (или любые из их вариантов). Если хотя бы одна отправленная фиксация содержит [skip ci], конвейеры не будут выполняться.

Наконец, после слияния запроса на вытягивание Azure Pipelines запустит конвейеры CI, активированные при отправке в целевую ветвь, если сообщение или описание фиксации слияния не содержит [skip ci] (или любой из его вариантов).

Защищенные ветви

Вы можете запустить проверочный сборок с каждой фиксацией или запросом на вытягивание, предназначенным для ветви, и даже предотвратить слияние запросов на вытягивание до тех пор, пока сборка проверки не будет успешно выполнена.

Чтобы настроить обязательные сборки проверки для репозитория GitHub, необходимо быть его владельцем, участником совместной работы с ролью Администратор или участником организации GitHub с ролью Записи.

  1. Сначала создайте конвейер для репозитория и создайте его хотя бы один раз, чтобы его состояние было опубликовано в GitHub, тем самым сделав GitHub осведомленным об имени конвейера.

  2. Затем следуйте документации GitHub по настройке защищенных ветвей в параметрах репозитория.

    Для проверка состояния выберите имя конвейера в списке Проверки состояния.

    состояние конвейера GitHub проверка

Важно!

Если конвейер не отображается в этом списке, убедитесь в следующем:

Вклады из внешних источников

Если репозиторий GitHub открытый код, вы можете сделать проект Azure DevOps общедоступным, чтобы любой пользователь мог просматривать результаты сборки, журналы и результаты тестирования конвейера без входа. Когда пользователи за пределами вашей организации создают вилку репозитория и отправляет запросы на вытягивание, они могут просматривать состояние сборок, которые автоматически проверяют эти запросы на вытягивание.

При использовании Azure Pipelines в общедоступном проекте при приеме вкладов из внешних источников следует учитывать следующие моменты.

Ограничения доступа

При запуске конвейеров в общедоступных проектах Azure DevOps следует учитывать следующие ограничения доступа:

  • Секреты: По умолчанию секреты, связанные с конвейером, недоступны для проверки запросов на вытягивание вилок. См . раздел Проверка вкладов из вилок.
  • Доступ между проектами: Все конвейеры в общедоступном проекте Azure DevOps выполняются с маркером доступа, ограниченным проектом. Конвейеры в общедоступном проекте могут получать доступ к таким ресурсам, как артефакты сборки или результаты тестирования, только внутри проекта, а не в других проектах организации Azure DevOps.
  • Пакеты Azure Artifacts: Если вашим конвейерам требуется доступ к пакетам из Azure Artifacts, необходимо явно предоставить разрешение учетной записи службы сборки project для доступа к веб-каналам пакетов.

Вклады из вилок

Важно!

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

При создании конвейера он автоматически активируется для запросов на вытягивание из вилок репозитория. Это поведение можно изменить, тщательно продумывая, как оно влияет на безопасность. Чтобы включить или отключить это поведение, выполните следующие действия:

  1. Перейдите к проекту Azure DevOps. Выберите Конвейеры, найдите конвейер и нажмите кнопку Изменить.
  2. Перейдите на вкладку Триггеры. После включения триггера запроса на вытягивание включите или отключите поле Сборка запросов на вытягивание из вилок этого репозитория проверка.

По умолчанию в конвейерах GitHub секреты, связанные с конвейером сборки, недоступны для сборок вилок запроса на вытягивание. Эти секреты включены по умолчанию с конвейерами GitHub Enterprise Server. Секреты включают в себя:

Чтобы обойти эту меру предосторожности в конвейерах GitHub, включите поле Сделать секреты доступными для сборок вилок проверка. Помните о влиянии этого параметра на безопасность.

Примечание

При включении вилки сборок для доступа к секретам Azure Pipelines по умолчанию ограничивает маркер доступа, используемый для сборок вилки. Он имеет более ограниченный доступ к открытым ресурсам, чем обычный маркер доступа. Чтобы предоставить вилкам те же разрешения, что и обычные сборки, включите параметр Сделать сборки вилки теми же разрешениями, что и обычные сборки .

Дополнительные сведения см. в разделе Защита репозитория — вилки.

Важные вопросы безопасности

Пользователь GitHub может создать вилку репозитория, изменить его и создать запрос на вытягивание, чтобы предложить изменения в репозитории. Этот запрос на вытягивание может содержать вредоносный код для запуска в рамках активированной сборки. Такой код может причинить вред следующим образом:

  • Утечка секретов из конвейера. Чтобы снизить этот риск, не включайте флажок Сделать секреты доступными для сборок вилок проверка, если репозиторий является общедоступным или ненадежные пользователи могут отправлять запросы на вытягивание, которые автоматически запускают сборки. Этот параметр по умолчанию отключен.

  • Компрометировать компьютер, на котором выполняется агент, для кражи кода или секретов из других конвейеров. Чтобы устранить эту проблему, выполните указанные ниже действия.

    • Используйте пул агентов, размещенный в Майкрософт , для создания запросов на вытягивание из вилок. Компьютеры с агентами, размещенными в Корпорации Майкрософт, сразу же удаляются после завершения сборки, поэтому в случае их компрометации это не повлияет.

    • Если необходимо использовать локальный агент, не храните секреты и не выполняйте другие сборки и выпуски, использующие секреты, в том же агенте, если только репозиторий не является частным и вы доверяете создателям запросов на вытягивание.

Триггеры комментариев

Участники совместной работы репозитория могут комментировать запрос на вытягивание для запуска конвейера вручную. Вот несколько распространенных причин, по которым это может потребоваться.

  • Возможно, вы не захотите автоматически создавать запросы на вытягивание от неизвестных пользователей, пока их изменения не будут проверены. Вы хотите, чтобы один из участников вашей команды сначала просмотрел свой код, а затем запускал конвейер. Обычно это используется в качестве меры безопасности при создании кода из вилки репозиториев.
  • Может потребоваться запустить дополнительный набор тестов или еще одну проверительную сборку.

Чтобы включить триггеры комментариев, необходимо выполнить следующие два шага.

  1. Включите триггеры запросов на вытягивание для конвейера и убедитесь, что вы не исключили целевую ветвь.
  2. На веб-портале Azure Pipelines измените конвейер и выберите Дополнительные действия, Триггеры. Затем в разделе Проверка запроса на вытягивание включите параметр Требовать комментарий участника команды перед созданием запроса на вытягивание.
    • Выберите Во всех запросах на вытягивание , чтобы запросить комментарий участника команды перед созданием запроса на вытягивание. В этом рабочем процессе член команды проверяет запрос на вытягивание и активирует сборку с комментарием, как только запрос на вытягивание считается безопасным.
    • Выберите только в запросах на вытягивание от участников, не являющихся участниками команды , чтобы требовать комментарий участника команды только в том случае, если запрос на вытягивание сделан не участником команды. В этом рабочем процессе участнику команды не требуется проверка участника вторичной команды для запуска сборки.

При этих двух изменениях сборка проверки запроса на вытягивание не будет запускаться автоматически, если только не выбраны запросы на вытягивание от участников, не являющихся участниками команды , и вытягивание не будет выполнено участником команды. Только владельцы репозиториев и участники совместной работы с разрешением "Запись" могут активировать сборку, комментируя запрос на вытягивание с /AzurePipelines run помощью или /AzurePipelines run <pipeline-name>.

В примечаниях в Azure Pipelines можно выполнить следующие команды:

Get-Help Результат
/AzurePipelines help Отображение справки по всем поддерживаемым командам.
/AzurePipelines help <command-name> Отображение справки по указанной команде.
/AzurePipelines run Запустите все конвейеры, связанные с этим репозиторием и триггеры которых не исключают этот запрос на вытягивание.
/AzurePipelines run <pipeline-name> Запустите указанный конвейер, если его триггеры не исключают этот запрос на вытягивание.

Примечание

Для краткости можно закомментировать, используя /azp вместо /AzurePipelines.

Важно!

Ответы на эти команды будут отображаться в обсуждении запроса на вытягивание, только если конвейер использует Приложение GitHub Azure Pipelines.

Устранение неполадок с триггерами комментариев к запросу на вытягивание

Если у вас есть необходимые разрешения репозитория, но конвейеры не активируются вашими комментариями, убедитесь, что ваше членство является общедоступным в организации репозитория, или непосредственно добавьте себя в качестве участника совместной работы репозитория. Конвейеры не могут видеть членов частной организации, если они не являются непосредственными участниками совместной работы или не принадлежат к команде, которая является непосредственным участником совместной работы. Вы можете изменить членство в организации GitHub с частного на общедоступное здесь (замените Your-Organization именем организации): https://github.com/orgs/Your-Organization/people.

Информационные запуски

Информационный запуск сообщает, что Azure DevOps не удалось получить исходный код конвейера YAML. Получение исходного кода происходит в ответ на внешние события, например при отправке фиксации. Это также происходит в ответ на внутренние триггеры, например, чтобы проверка, если есть изменения в коде, и запустить запланированное выполнение или нет. Получение исходного кода может завершиться сбоем по нескольким причинам, при этом часто используется регулирование запросов поставщиком репозитория Git. Наличие информационного запуска не обязательно означает, что Azure DevOps собирается запустить конвейер.

Информационный запуск выглядит, как показано на следующем снимке экрана.

Снимок экрана: запуск информационного конвейера.

Информационный запуск можно распознать по следующим атрибутам:

  • Состояние — Canceled
  • Длительность : < 1s
  • Имя запуска содержит один из следующих текстов:
    • Could not retrieve file content for {file_path} from repository {repo_name} hosted on {host} using commit {commit_sha}.
    • Could not retrieve content for object {commit_sha} from repository {repo_name} hosted on {host}.
    • Could not retrieve the tree object {tree_sha} from the repository {repo_name} hosted on {host}.
    • Could not find {file_path} from repository {repo_name} hosted on {host} using version {commit_sha}. One of the directories in the path contains too many files or subdirectories.
  • Имя запуска обычно содержит ошибку BitBucket или GitHub, которая привела к сбою загрузки конвейера YAML.
  • Нет этапов , заданий и шагов

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

Извлечение

При активации конвейера Azure Pipelines извлекает исходный код из репозитория Azure Repos Git. Вы можете контролировать различные аспекты того, как это происходит.

Примечание

Когда вы включаете шаг возврата в конвейер, мы выполняем следующую команду: git -c fetch --force --tags --prune --prune-tags --progress --no-recurse-submodules origin --depth=1. Если это не соответствует вашим потребностям, вы можете исключить встроенную регистрацию checkout: none , а затем использовать задачу скрипта для выполнения собственного оформления заказа.

Предпочтительная версия Git

Агент Windows поставляется с собственной копией Git. Если вы предпочитаете предоставлять собственный Git, а не использовать включенную копию, задайте для параметра значение System.PreferGitFromPathtrue. Этот параметр всегда имеет значение true для агентов, отличных от Windows.

Путь к оформлению заказа

Если вы извлекаете один репозиторий, по умолчанию исходный код будет извлечен в каталог с именем s. Для конвейеров YAML это можно изменить, указав checkout с pathпомощью . Указанный путь относительно $(Agent.BuildDirectory). Например, если значение пути к извлечению равно mycustompath и $(Agent.BuildDirectory) равно C:\agent\_work\1, исходный код будет извлечен в C:\agent\_work\1\mycustompath.

Если вы используете несколько checkout шагов и извлекаете несколько репозиториев и не указываете явно папку с помощью path, каждый репозиторий помещается во вложенную папку s с именем репозитория. Например, если проверка два репозитория с именами tools и code, исходный код будет извлечен в C:\agent\_work\1\s\tools и C:\agent\_work\1\s\code.

Обратите внимание, что значение пути к оформлению заказа не может быть задано так, чтобы перейти на любые уровни каталога выше $(Agent.BuildDirectory), поэтому path\..\anotherpath приведет к допустимому пути извлечения (т. е. C:\agent\_work\1\anotherpath), но такое значение ..\invalidpath не будет (т. е. C:\agent\_work\invalidpath).

Этот параметр можно настроить на path шаге Извлечь конвейера.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Подмодулы

Чтобы скачать файлы из подмодулей, этот параметр можно настроить submodules на шаге "Извлечь" конвейера.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Конвейер сборки проверка из подмодулей Git, если они:

  • Непроверенных: Общедоступный репозиторий без проверки подлинности без учетных данных, необходимых для клонирования или получения.

  • Проверкой подлинности:

    • Содержится в том же проекте, что и указанный выше репозиторий Azure Repos Git. Те же учетные данные, которые используются агентом для получения источников из репозитория main, также используются для получения источников для подмодулей.

    • Добавляется с помощью URL-адреса относительно репозитория main. Например.

      • Это будет извлечено: git submodule add ../../../FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

        В этом примере подмодул ссылается на репозиторий (FabrikamFiber) в той же организации Azure DevOps, но в другом проекте (FabrikamFiberProject). Те же учетные данные, которые используются агентом для получения источников из репозитория main, также используются для получения источников для подмодулей. Для этого маркер доступа задания должен иметь доступ к репозиторию во втором проекте. Если вы ограничили маркер доступа к заданию, как описано в разделе выше, вы не сможете сделать это. Вы можете разрешить маркеру доступа задания доступ к репозиторию во втором проекте, (а) явно предоставив доступ к учетной записи службы сборки проекта во втором проекте или (б) используя маркеры доступа уровня коллекции вместо маркеров уровня проекта для всей организации. Дополнительные сведения об этих параметрах и их последствиях для безопасности см. в статье Доступ к репозиториям, артефактам и другим ресурсам.

      • Этот не будет извлечен: git submodule add https://fabrikam-fiber@dev.azure.com/fabrikam-fiber/FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

Альтернатива использованию параметра "Подмодулы для оформления заказа"

В некоторых случаях вы не можете использовать параметр Подмодулы Оформления заказа. Может потребоваться другой набор учетных данных для доступа к подмодулям. Это может произойти, например, если репозитории main и репозитории подмодулей хранятся не в одной организации Azure DevOps или маркер доступа к заданию не имеет доступа к репозиторию в другом проекте.

Если вы не можете использовать параметр Извлечение подмодулей , вместо этого можно использовать настраиваемый шаг скрипта для получения подмодулей. Сначала получите личный маркер доступа (PAT) и добавьте к нему pat:префикс . Затем закодируйте строку с префиксом base64 , чтобы создать базовый маркер проверки подлинности. Наконец, добавьте следующий скрипт в конвейер:

git -c http.https://<url of submodule repository>.extraheader="AUTHORIZATION: Basic <BASE64_ENCODED_STRING>" submodule update --init --recursive

Обязательно замените "<BASE64_ENCODED_STRING>" строкой pat:token в кодировке Base64.

Используйте переменную секрета в проекте или конвейере сборки для хранения созданного базового маркера проверки подлинности. Эта переменная используется для заполнения секрета в приведенной выше команде Git.

Примечание

Вопрос. Почему я не могу использовать диспетчер учетных данных Git в агенте?A: Хранение учетных данных подмодуля в диспетчере учетных данных Git, установленном в частном агенте сборки, обычно не действует, так как диспетчер учетных данных может предложить повторно ввести учетные данные при каждом обновлении подмодуля. Это нежелательно при автоматизированных сборках, когда взаимодействие с пользователем невозможно.

Синхронизация тегов

Шаг извлечения использует --tags параметр при выборке содержимого репозитория Git. Это приводит к тому, что сервер получает все теги, а также все объекты, на которые указывают эти теги. Это увеличивает время выполнения задачи в конвейере, особенно при наличии большого репозитория с несколькими тегами. Кроме того, шаг оформления заказа синхронизирует теги даже при включении параметра неглубокой выборки, что может помешать его назначению. Чтобы уменьшить объем данных, извлекаемых или извлекаемых из репозитория Git, корпорация Майкрософт добавила новый параметр извлечения для управления поведением синхронизации тегов. Этот параметр доступен как в классическом конвейере, так и в конвейере YAML.

Можно ли настроить синхронизацию тегов при извлечении репозитория в YAML, задав fetchTags свойство и в пользовательском интерфейсе, настроив параметр Синхронизация тегов .

Этот параметр можно настроить на fetchTags шаге Извлечь конвейера.

Чтобы настроить параметр в YAML, задайте fetchTags свойство .

steps:
- checkout: self
  fetchTags: true

Этот параметр также можно настроить с помощью параметра Синхронизация тегов в пользовательском интерфейсе параметров конвейера.

  1. Измените конвейер YAML и выберите Дополнительные действия, Триггеры.

    Снимок экрана: меню

  2. Выберите YAML, Получить источники.

    Снимок экрана: получение источников.

  3. Настройте параметр Синхронизация тегов .

    Снимок экрана: параметр тегов синхронизации.

Примечание

Если вы явно задали fetchTags на шаге checkout , этот параметр имеет приоритет над параметром, настроенным в пользовательском интерфейсе параметров конвейера.

Поведение по умолчанию

  • Для существующих конвейеров, созданных до выпуска Azure DevOps sprint 209, выпущенного в сентябре 2022 г., значение по умолчанию для синхронизации тегов остается таким же, как и поведение, существующее до добавления параметров синхронизации тегов , то есть true.
  • Для новых конвейеров, созданных после выпуска 209 спринта Azure DevOps, по умолчанию для синхронизации тегов используется false.

Примечание

Если вы явно задали fetchTags на шаге checkout , этот параметр имеет приоритет над параметром, настроенным в пользовательском интерфейсе параметров конвейера.

Неглубокая выборка

Вы можете ограничить время загрузки в истории. Фактически это приводит к .git fetch --depth=n Если репозиторий большой, этот параметр может повысить эффективность конвейера сборки. Репозиторий может быть большим, если он использовался в течение длительного времени и имеет большой журнал. Он также может быть большим, если вы добавили и удалили большие файлы.

Важно!

Для новых конвейеров, созданных после обновления azure DevOps sprint 209 за сентябрь 2022 г., по умолчанию включена неполная выборка и настроена глубина 1. Ранее по умолчанию не было мелкой выборки. Чтобы проверка конвейера, просмотрите параметр Мелкой выборки в пользовательском интерфейсе параметров конвейера, как описано в следующем разделе.

Этот параметр можно настроить на fetchDepth шаге Извлечь конвейера.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Вы также можете настроить глубину выборки, задав параметр Малая глубина в пользовательском интерфейсе параметров конвейера.

  1. Измените конвейер YAML и выберите Дополнительные действия, Триггеры.

    Снимок экрана: меню

  2. Выберите YAML, Получить источники.

    Снимок экрана: получение источников.

  3. Настройте параметр мелкой выборки . Снимите флажок Поверхностная выборка, чтобы отключить неглубокую выборку, или проверка поле и введите значение Глубина, чтобы включить неглубокую выборку.

    Снимок экрана: параметры.

Примечание

Если вы явно задали fetchDepth на шаге checkout , этот параметр имеет приоритет над параметром, настроенным в пользовательском интерфейсе параметров конвейера. Параметр fetchDepth: 0 извлекает весь журнал и переопределяет параметр мелкой выборки .

В таких случаях этот параметр помогает сэкономить ресурсы сети и хранилища. Это также может сэкономить время. Причина, по которой это не всегда экономит время, заключается в том, что в некоторых ситуациях серверу может потребоваться потратить время на вычисление фиксаций для скачивания для указанной вами глубины.

Примечание

При запуске конвейера ветвь для сборки разрешается в ИД фиксации. Затем агент извлекает ветвь и извлекает нужную фиксацию. Существует небольшое окно между разрешением ветви в ИД фиксации и выполнением агентом извлечения. Если ветвь обновляется быстро и вы задали очень небольшое значение для неглубокой выборки, фиксация может не существовать, когда агент пытается проверка ее. В этом случае увеличьте значение параметра глубины неглубокой выборки.

Не синхронизировать источники

Вы можете пропустить получение новых фиксаций. Этот параметр может быть полезен в тех случаях, когда вы хотите:

  • Инициализация, настройка и выборка Git с помощью собственных настраиваемых параметров.

  • Используйте конвейер сборки для простого запуска автоматизации (например, некоторых скриптов), которые не зависят от кода в управлении версиями.

Вы можете настроить параметр Не синхронизировать источники на шаге Извлечение конвейера, задав .checkout: none

steps:
- checkout: none  # Don't sync sources

Примечание

При использовании этого параметра агент также пропускает выполнение команд Git, которые очищают репозиторий.

Чистая сборка

Перед выполнением сборки можно выполнить различные формы очистки рабочего каталога локального агента.

Как правило, для повышения производительности локальных агентов не очищайте репозиторий. В этом случае, чтобы добиться наилучшей производительности, убедитесь, что вы также выполняете добавочную сборку, отключив любой параметр Очистка задачи или средства, которые вы используете для сборки.

Если вам нужно очистить репозиторий (например, чтобы избежать проблем, вызванных остаточными файлами из предыдущей сборки), доступны следующие варианты.

Примечание

Очистка не является эффективной, если вы используете агент, размещенный в Майкрософт , так как вы будете получать новый агент каждый раз.

Этот параметр можно настроить на clean шаге Извлечь конвейера.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Если clean задано для true конвейера сборки, выполняется отмена всех изменений в $(Build.SourcesDirectory). В частности, перед получением источника выполняются следующие команды Git.

git clean -ffdx
git reset --hard HEAD

Для получения дополнительных параметров можно настроить workspace параметр задания.

jobs:
- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  ...
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs

Это дает следующие параметры очистки.

  • outputs: та же операция, что и параметр очистки, описанный в предыдущей задаче оформления, а также: удаляет и повторно создает $(Build.BinariesDirectory). Обратите внимание, что $(Build.ArtifactStagingDirectory) и $(Common.TestResultsDirectory) всегда удаляются и повторно создаются перед каждой сборкой независимо от любого из этих параметров.

  • resources: удаляет и повторно создает $(Build.SourcesDirectory). Это приводит к инициализации нового локального репозитория Git для каждой сборки.

  • all: удаляет и повторно создает $(Agent.BuildDirectory). Это приводит к инициализации нового локального репозитория Git для каждой сборки.

Источники меток

Вы можете пометить файлы исходного кода, чтобы команда могла легко определить, какая версия каждого файла включена в завершенную сборку. Вы также можете указать, следует ли пометить исходный код для всех сборок или только для успешных сборок.

В настоящее время вы не можете настроить этот параметр в YAML, но вы можете использовать классический редактор. При редактировании конвейера YAML вы можете получить доступ к классическому редактору, выбрав триггеры в меню редактора YAML.

Настройка параметров Git в YAML.

В классическом редакторе выберите YAML, выберите задачу Получить источники и настройте нужные свойства.

В классическом редакторе выберите YAML > Получить источники.

В формате тега можно использовать определяемые пользователем и предопределенные переменные с область "Все". Например:

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.BuildNumber)_$(My.Variable)

Первые четыре переменные являются предопределенными. My.Variable может быть определен вами на вкладке переменных.

Конвейер сборки помечает источники тегом Git.

Некоторые переменные сборки могут возвращать значение, которое не является допустимой меткой. Например, такие переменные, как $(Build.RequestedFor) и $(Build.DefinitionName) , могут содержать пробелы. Если значение содержит пробелы, тег не создается.

После добавления тегов к источникам в конвейер сборки в завершенную сборку автоматически добавляется артефакт с ссылкой refs/tags/{tag} на Git. Это обеспечивает команде дополнительную возможность трассировки и более удобный для пользователя способ перехода от сборки к созданному коду. Тег считается артефактом сборки, так как он создается сборкой. При удалении сборки вручную или с помощью политики хранения тег также удаляется.

Предварительно определенные переменные

При создании репозитория GitHub большинство предопределенных переменных доступны для ваших заданий. Однако, так как Azure Pipelines не распознает удостоверение пользователя, выполняющего обновление в GitHub, для следующих переменных устанавливается системное удостоверение, а не удостоверение пользователя:

  • Build.RequestedFor
  • Build.RequestedForId
  • Build.RequestedForEmail

Обновления состояния

Существует два типа состояний, которые Azure Pipelines публикует в GitHub: базовые состояния и GitHub Check Runs. Функции проверок GitHub доступны только в приложениях GitHub.

Состояния конвейера отображаются в различных местах в пользовательском интерфейсе GitHub.

  • Для запросов на вытягивание они отображаются на вкладке беседы запроса на вытягивание.
  • Для отдельных фиксаций они отображаются при наведении указателя мыши на метку состояния после времени фиксации на вкладке фиксаций репозитория.

Подключения GitHub pat или OAuth

Для конвейеров, использующих подключения PAT или OAuth GitHub, состояния отправляются обратно в фиксацию или запрос на вытягивание, которая активирует выполнение. Для публикации таких обновлений используется API состояния GitHub . Эти состояния содержат ограниченную информацию: состояние конвейера (сбой, успешное выполнение), URL-адрес для обратной связи с конвейером сборки и краткое описание состояния.

Состояния подключений PAT или OAuth GitHub отправляются только на уровне выполнения. Другими словами, вы можете обновить одно состояние для всего выполнения. Если у вас есть несколько заданий в выполнении, вы не сможете опубликовать отдельное состояние для каждого задания. Однако несколько конвейеров могут публиковать отдельные состояния в одной фиксации.

Проверки GitHub

Для конвейеров, настроенных с помощью приложения GitHub Azure Pipelines, состояние отображается в виде проверок GitHub. Проверки GitHub позволяют отправлять подробные сведения о состоянии конвейера, тесте, объеме протестированного кода и ошибках. API проверок GitHub можно найти здесь.

Для каждого конвейера, используюющего Приложение GitHub, возвращаются проверки для общего выполнения и каждого задания в этом запуске.

GitHub поддерживает три варианта при сбое одного или нескольких проверок для запроса на вытягивание или фиксацию. Вы можете повторно запустить отдельную проверку, повторно запустить все неудачные проверки для этого запроса на вытягивание или фиксацию или повторно запустить все проверки, независимо от того, успешно ли они были выполнены изначально.

Повторный запуск проверок GitHub

Щелкнув ссылку "Повторный запуск" рядом с именем проверки, Azure Pipelines повторит выполнение, сгенерировав выполнение проверки. Результат выполнения будет иметь тот же номер запуска и будет использовать ту же версию исходного кода, конфигурации и файла YAML, что и начальная сборка. Повторно будут выполняться только те задания, которые завершились сбоем в начальном запуске, и все зависимые подчиненные задания. Если щелкнуть ссылку Rerun all failing checks (Повторно выполнить все неудачные проверки), это приведет к тому же эффекту. Это то же поведение, что и при нажатии кнопки "Повторить запуск" в пользовательском интерфейсе Azure Pipelines. При нажатии кнопки "Повторно выполнить все проверки" будет выполнено новое выполнение с новым номером выполнения и будут внесены изменения в конфигурацию или файл YAML.

Вопросы и ответы

Проблемы, связанные с интеграцией GitHub, делятся на следующие категории:

Типы подключений

Как узнать тип подключения GitHub, используемого для конвейера, чтобы устранить неполадки с триггерами?

Устранение неполадок с триггерами во многом зависит от типа подключения GitHub, используемого в конвейере. Существует два способа определения типа подключения — из GitHub и из Azure Pipelines.

  • Из GitHub: если репозиторий настроен для использования приложения GitHub, то состояния на PR и фиксациях будут иметь значение Check Runs. Если в репозитории настроена служба Azure Pipelines с подключениями OAuth или PAT, это будет "старый" стиль состояний. Быстрый способ определить, являются ли состояниями Check Runs или простыми состояниями, — просмотреть вкладку "беседа" в запросе на вытягивание GitHub.

    • Если ссылка "Сведения" перенаправляется на вкладку Проверки, это запуск проверки, и репозиторий использует приложение.
    • Если ссылка "Сведения" перенаправляется в конвейер Azure DevOps, это состояние "старый стиль", и репозиторий не использует приложение.

  • Из Azure Pipelines. Вы также можете определить тип подключения, проверив конвейер в пользовательском интерфейсе Azure Pipelines. Откройте редактор для конвейера. Выберите Триггеры, чтобы открыть классический редактор для конвейера. Затем выберите вкладку YAML и шаг Получить источники . Вы увидите баннер Авторизовано с помощью подключения: с указанием подключения службы, которое использовалось для интеграции конвейера с GitHub. Имя подключения службы является гиперссылкой. Выберите его, чтобы перейти к свойствам подключения службы. Свойства подключения службы указывают тип используемого подключения:

    • Приложение Azure Pipelines указывает подключение к приложению GitHub
    • oauth указывает на подключение OAuth
    • personalaccesstoken указывает, что проверка подлинности pat

Разделы справки переключить конвейер на использование приложения GitHub вместо OAuth?

Рекомендуется использовать приложение GitHub вместо подключения OAuth или PAT между GitHub и Azure Pipelines. Чтобы переключиться на приложение GitHub, выполните следующие действия.

  1. Перейдите по этой ссылке и установите приложение в организации GitHub репозитория.
  2. Во время установки вы будете перенаправлены в Azure DevOps, чтобы выбрать организацию и проект Azure DevOps. Выберите организацию и проект, содержащие классический конвейер сборки, для которого вы хотите использовать приложение. Этот вариант связывает Приложение GitHub установку с вашей организацией Azure DevOps. Если вы выбрали неправильный вариант, посетите эту страницу , чтобы удалить приложение GitHub из организации GitHub и начать заново.
  3. На следующей странице, которая появится, вам не нужно продолжать создание нового конвейера.
  4. Измените конвейер, перейдя на страницу Конвейеры (например, https://dev.azure.com/YOUR_ORG_NAME/YOUR_PROJECT_NAME/_build)выберите конвейер и нажмите кнопку Изменить).
  5. Если это конвейер YAML, выберите меню Триггеры , чтобы открыть классический редактор.
  6. Выберите шаг "Получить источники" в конвейере.
  7. На зеленой панели с текстом "Авторизовано с помощью подключения" выберите "Изменить" и выберите Приложение GitHub подключение с тем же именем, что и у организации GitHub, в которой установлено приложение.
  8. На панели инструментов выберите "Сохранить и ставить в очередь", а затем "Сохранить и ставить в очередь". Выберите ссылку на запуск конвейера, который был поставлен в очередь, чтобы убедиться, что он успешно выполнен.
  9. Создайте (или закройте и снова откройте) запрос на вытягивание в репозитории GitHub, чтобы убедиться, что сборка успешно помещена в очередь в разделе "Проверки".

Почему репозиторий GitHub не отображается для выбора в Azure Pipelines?

В зависимости от типа проверки подлинности и владельца репозитория требуются определенные разрешения.

При выборе репозитория во время создания конвейера появляется сообщение об ошибке "Репозиторий {имя_репозитория} используется с azure Pipelines Приложение GitHub в другой организации Azure DevOps".

Это означает, что репозиторий уже связан с конвейером в другой организации. События CI и PR из этого репозитория не будут работать, так как они будут доставлены в другую организацию. Ниже приведены действия, которые необходимо предпринять, чтобы удалить сопоставление с другой организацией, прежде чем приступать к созданию конвейера.

  1. Откройте запрос на вытягивание в репозитории GitHub и сделайте комментарий /azp where. При этом сообщается о организации Azure DevOps, с которым сопоставлен репозиторий.

  2. Чтобы изменить сопоставление, удалите приложение из организации GitHub и переустановите его. При переустановке убедитесь, что выбрана правильная организация при перенаправлении в Azure DevOps.

Триггеры сбоя

Я только что создал новый конвейер YAML с триггерами CI/PR, но конвейер не активируется.

Выполните каждое из следующих действий, чтобы устранить неполадки триггеров:

  • Переопределяются ли триггеры CI yamL или PR с помощью параметров конвейера в пользовательском интерфейсе? При редактировании конвейера выберите ... , а затем — Триггеры.

    Пользовательский интерфейс параметров конвейера.

    Проверьте параметр Переопределить триггер YAML отсюда , чтобы узнать, какие типы триггеров (непрерывная интеграция или проверка запросов на вытягивание) доступны для вашего репозитория.

    Переопределите триггер YAML отсюда.

  • Вы используете подключение к приложению GitHub для подключения конвейера к GitHub? Сведения об определении типа подключения см. в разделе Типы подключений. Если вы используете подключение к приложению GitHub, выполните следующие действия.

    • Правильно ли настроено сопоставление между GitHub и Azure DevOps? Откройте запрос на вытягивание в репозитории GitHub и сделайте комментарий /azp where. При этом сообщается о организации Azure DevOps, с которым сопоставлен репозиторий.

      • Если ни в каких организациях не настроена сборка этого репозитория с помощью приложения, перейдите на страницу https://github.com/<org_name>/<repo_name>/settings/installations и завершите настройку приложения.

      • Если сообщается о другой организации Azure DevOps, то кто-то уже создал конвейер для этого репозитория в другой организации. В настоящее время у нас есть ограничение, что репозиторий GitHub можно сопоставить только с одной организацией DevOps. Автоматически можно активировать только конвейеры в первой организации Azure DevOps. Чтобы изменить сопоставление, удалите приложение из организации GitHub и переустановите его. При переустановке убедитесь, что выбрана правильная организация при перенаправлении в Azure DevOps.

  • Вы используете OAuth или PAT для подключения конвейера к GitHub? Сведения об определении типа подключения см. в разделе Типы подключений. Если вы используете подключение GitHub, выполните следующие действия.

    1. Подключения OAuth и PAT используют веб-перехватчики для передачи обновлений в Azure Pipelines. В GitHub перейдите к параметрам репозитория, а затем к веб-перехватчикам. Убедитесь, что веб-перехватчики существуют. Обычно вы увидите три веб-перехватчика: push, pull_request и issue_comment. В противном случае необходимо повторно создать подключение к службе и обновить конвейер для использования нового подключения службы.

    2. Выберите каждый из веб-перехватчиков в GitHub и убедитесь, что полезные данные, соответствующие фиксации пользователя, существуют и успешно отправлены в Azure DevOps. Если не удалось передать событие в Azure DevOps, может появиться сообщение об ошибке.

  • GitHub может регулировать трафик из Azure DevOps. Когда Azure Pipelines получает уведомление от GitHub, он пытается связаться с GitHub и получить дополнительные сведения о репозитории и файле YAML. Если у вас есть репозиторий с большим количеством обновлений и запросов на вытягивание, этот вызов может завершиться ошибкой из-за такого регулирования. В этом случае узнайте, можно ли уменьшить частоту сборок с помощью пакетной обработки или более строгих фильтров пути или ветви.

  • Ваш конвейер приостановлен или отключен? Откройте редактор конвейера и выберите Параметры, чтобы проверка. Если конвейер приостановлен или отключен, триггеры не работают.

  • Вы обновили файл YAML в правильной ветви? Если вы отправляете обновление в ветвь, то yaml-файл в этой же ветви управляет поведением CI. Если вы отправляете обновление в исходную ветвь, то файл YAML, полученный в результате слияния исходной ветви с целевой ветвью, управляет поведением запроса на вытягивание. Убедитесь, что файл YAML в правильной ветви имеет необходимую конфигурацию CI или PR.

  • Правильно ли настроен триггер? При определении триггера YAML можно указать предложения include и exclude для ветвей, тегов и путей. Убедитесь, что предложение include соответствует сведениям о фиксации и что предложение exclude не исключает их. Проверьте синтаксис триггеров и убедитесь, что он является точным.

  • Использовались ли переменные при определении триггера или путей? Это не поддерживается.

  • Вы использовали шаблоны для файла YAML? Если да, убедитесь, что триггеры определены в файле YAML main. Триггеры, определенные в файлах шаблонов, не поддерживаются.

  • Вы исключили ветви или пути, в которые были отправлены изменения? Тестирование путем отправки изменения в включенный путь в включенной ветви. Обратите внимание, что в путях в триггерах учитывается регистр. Убедитесь, что при указании путей в триггерах используется тот же регистр, что и в реальных папках.

  • Вы просто принудили новую ветвь? В этом случае новая ветвь может не запустить новый запуск. См. раздел "Поведение триггеров при создании новых ветвей".

Мои триггеры CI или PR работали нормально. Но сейчас они перестали работать.

Сначала выполните действия по устранению неполадок, описанные в предыдущем вопросе. Затем выполните следующие дополнительные действия.

  • У вас есть конфликты слияния в запросе на вытягивание? Для запроса на вытягивание, которое не активировало конвейер, откройте его и проверка, имеет ли он конфликт слияния. Устраните конфликт слияния.

  • Возникает ли задержка при обработке событий push-уведомлений или запросов на вытягивание? Обычно это можно проверить, посмотрев, связана ли проблема с одним конвейером или является ли она общей для всех конвейеров или репозиториев в проекте. Если этот симптом проявляется при принудительной отправке или обновлении запроса на вытягивание в любом из репозиториев, возможно, возникают задержки при обработке событий обновления. Проверьте, не возникает ли сбой службы на странице состояния. Если на странице состояния отображается проблема, значит, наша команда уже начала работать над ней. Регулярно проверяйте страницу на наличие обновлений по проблеме.

Я не хочу, чтобы пользователи переопределяли список ветвей для триггеров при обновлении файла YAML. Как это сделать?

Пользователи с разрешениями на внесение кода могут обновить файл YAML и включить или исключить дополнительные ветви. В результате пользователи могут включить собственный компонент или ветвь пользователя в файл YAML и отправить это обновление в компонент или в ветвь пользователя. Это может привести к активации конвейера для всех обновлений этой ветви. Если вы хотите предотвратить такое поведение, вы можете:

  1. Измените конвейер в пользовательском интерфейсе Azure Pipelines.
  2. Перейдите в меню Триггеры .
  3. Выберите Переопределить триггер непрерывной интеграции YAML здесь.
  4. Укажите ветви, которые нужно включить или исключить для триггера.

При выполнении этих действий все триггеры CI, указанные в файле YAML, игнорируются.

Сбой оформления заказа

На этапе оформления заказа в файле журнала отображается следующая ошибка. Как ее исправить?

remote: Repository not found.
fatal: repository <repo> not found

Это может быть вызвано сбоем GitHub. Попробуйте получить доступ к репозиторию в GitHub и убедитесь, что это возможно.

Неправильная версия

В конвейере используется неправильная версия файла YAML. Почему?

  • Для триггеров CI файл YAML, который находится в отталкиваемой ветви, оценивается, чтобы определить, следует ли выполнять сборку CI.
  • Для триггеров запроса на вытягивание оценивается файл YAML, полученный в результате слияния исходной и целевой ветвей запроса на вытягивание, чтобы определить, следует ли выполнять сборку запроса на вытягивание.

Отсутствующие обновления состояния

Мой запрос на вытягивание в GitHub заблокирован, так как Azure Pipelines не обновила состояние.

Это может быть временная ошибка, из-за которой Azure DevOps не может взаимодействовать с GitHub. Повторите попытку проверка в GitHub, если вы используете приложение GitHub. Или сделайте тривиальное обновление запроса на вытягивание, чтобы узнать, можно ли устранить проблему.