Справочник по Azure Repos Git

СПРАВОЧНИК

Назначение

CLI, конфигурация и типовые сценарии Azure Repos Git (DevOps, CI/CD, инфраструктура). Учебный курс: раздел.

Краткое пояснение

Azure Repos Git — управляемый Git в Azure DevOps — репозитории, ветки, pull request, политики веток и интеграция с Azure Pipelines. В CI/CD события PR и push запускают пайплайны; политики блокируют merge без успешной сборки и ревью.

Быстрый старт

az repos create --name MyRepo --project MyProject
az repos pr create --repository MyRepo --source-branch feature/x --target-branch main
az repos policy list --repository-id {id}

Справочные таблицы

Azure Repos Git — это управляемая облачная система контроля версий на основе Git, входящая в состав Azure DevOps Services. Она предоставляет полную поддержку распределённого рабочего процесса Git с дополнительными возможностями управления, безопасности, интеграции и аналитики.

Основные элементы Azure Repos Git

Репозиторий (Repository)

Репозиторий — центральная единица хранения кода и истории изменений. Каждый репозиторий содержит:

Все коммиты
Ветки
Теги
Файлы и папки проекта
.git-метаданные (внутренне)

В Azure Repos один проект может содержать множество репозиториев. Репозитории создаются в рамках организации Azure DevOps.

Проект (Project)

Проект — контейнер для репозиториев, рабочих элементов, конвейеров, тестов и других артефактов. Проект определяет:

Область видимости доступа
Правила безопасности по умолчанию
Интеграцию с другими службами Azure DevOps

Организация (Organization)

Организация — корневой уровень в Azure DevOps. Она объединяет:

Проекты
Участников
Лицензии
Настройки безопасности на уровне организации
Политики по умолчанию

Ветвление и управление ветками

Главная ветка (Main / Master)

По умолчанию при создании репозитория создаётся ветка main (или master, в зависимости от настроек). Эта ветка считается стабильной и защищённой.

Feature-ветки

Используются для разработки новых функций. Имена часто начинаются с префикса feature/.

Release-ветки

Создаются для подготовки релизов. Префикс — release/.

Hotfix-ветки

Применяются для срочных исправлений в production. Префикс — hotfix/.

Защищённые ветки (Protected Branches)

Azure Repos позволяет настраивать политики защиты для веток. Защита применяется через Branch Policies.

Политики веток (Branch Policies)

Политики веток — правила, которые применяются к конкретным веткам или шаблонам имён веток. Политики можно настроить в интерфейсе Azure DevOps или через REST API.

Обязательные политики

Require a minimum number of reviewers
Минимальное количество ревьюеров, которые должны одобрить pull request.
Значения: от 1 до 10.
Дополнительно: можно требовать, чтобы каждый ревьюер явно нажал "Approve".
Check for linked work items
Требует привязки хотя бы одного рабочего элемента (work item) к pull request.
Значения: включено / выключено.
Check for comment resolution
Требует разрешения всех комментариев в pull request перед слиянием.
Значения: включено / выключено.
Build validation
Требует успешного прохождения указанного конвейера CI перед слиянием.
Параметры:
- Pipeline: имя или ID пайплайна
- Trigger: автоматический запуск или ручной
- Policy status: required / optional
- Display name: отображаемое имя проверки
Status checks
Требует наличия внешних статусов (например, от сторонних систем) со значением succeeded.
Параметры:
- Status name
- Author
- Expiration
File path restrictions
Запрещает изменения в указанных путях без специального разрешения.
Пример: *.prod.config — только члены группы "Release Managers" могут изменять.
Automatically include reviewers
Автоматически добавляет ревьюеров на основе пути к файлу или шаблона имени.
Пример: все изменения в /src/api/ → автоматически добавляется команда Backend.
Merge strategies
Определяет допустимые стратегии слияния:
- Basic merge
- Squash merge
- Rebase and fast-forward
- Semi-linear merge (rebase + merge commit)
Можно разрешить одну или несколько стратегий.

Pull Request (PR)

Pull Request — механизм предложения изменений из одной ветки в другую с последующим ревью, обсуждением и валидацией.

Состояния PR

Active — открыт, ожидает ревью
Completed — успешно слит
Abandoned — отменён

Возможности PR

Комментирование строк кода
Обсуждение на уровне файла или всего PR
Автоматическое назначение ревьюеров
Шаблоны описания PR
Автоматическое закрытие связанных work items при слиянии (через ключевые слова: Closes #123)
Draft PR — черновик, не готов к ревью

Шаблоны PR

Шаблоны создаются в файле .azuredevops/pull_request_template.md или в корне репозитория как PULL_REQUEST_TEMPLATE.md. Поддерживаются несколько шаблонов с разными именами.

Разрешения и безопасность

Уровни доступа

Reader — просмотр кода, PR, веток
Contributor — push, создание PR, комментирование
Collaborator — то же, что Contributor, но с дополнительными правами в некоторых организациях
Administrator — полный контроль над репозиторием, включая настройку политик

Группы безопасности

Project Readers
Project Contributors
Build Administrators
Project Administrators

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

Права на уровне ветки

Для каждой ветки или шаблона ветки можно задать:

Force push
Delete branch
Contribute
Contribute to pull requests
Create branch
Bypass policies
Manage permissions

Настройки репозитория

Общие настройки

Default branch — ветка по умолчанию для клонирования и PR
Repository URL — HTTPS и SSH ссылки
Clone in VS Code / Visual Studio — кнопки быстрого клонирования
Initialize with README — опция при создании репозитория

Параметры обслуживания

Garbage collection — автоматическая очистка неиспользуемых объектов
Loose object compression — сжатие объектов Git
Prune unreachable objects — удаление недостижимых коммитов

Включение функций

Forks — разрешить создание форков (внутри проекта или публично)
Public access — сделать репозиторий публичным (только в публичных проектах)
Wiki — включить отдельный Wiki-репозиторий
Issues — использовать встроенные задачи (не путать с Azure Boards)

Интеграции

Azure Pipelines

Полная интеграция с CI/CD:

Автоматический запуск пайплайнов по push или PR
Отображение статуса сборки в PR
Блокировка слияния при провале сборки

Azure Boards

Автоматическая связь коммитов и PR с work items через #ID
Отображение связанных задач в интерфейсе PR
Автоматическое обновление состояния work item

REST API

Azure DevOps предоставляет полный REST API для управления репозиториями:

Создание/удаление репозиториев
Управление ветками
Создание PR
Получение истории коммитов
Загрузка файлов

Базовый URL: https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repoId}

Webhooks

Поддержка исходящих webhook-уведомлений на события:

git.push
git.pullrequest.created
git.pullrequest.merged
git.ref.updated

Целевой URL, секрет, фильтрация по событиям — настраиваются вручную.

CLI и инструменты

Azure CLI

Команды для работы с репозиториями:

az repos create --name MyRepo --project MyProject
az repos pr create --repository MyRepo --source-branch feature/x --target-branch main
az repos policy list --repository-id {id}

Требуется установка расширения: az extension add --name azure-devops

Git CLI

Стандартные команды Git работают без изменений:

git clone https://dev.azure.com/org/project/_git/repo
git checkout -b feature/new
git add .
git commit -m "Add new feature"
git push --set-upstream origin feature/new

Для аутентификации используется:

Personal Access Token (PAT)
Azure AD credentials (через credential manager)
SSH keys

Visual Studio / VS Code

Встроенные инструменты:

Создание PR из IDE
Просмотр изменений
Синхронизация веток
Интеграция с Azure Boards

Аналитика и отчётность

Insights (вкладка Analytics)

Commit trends — активность по дням/неделям
Code churn — объём изменений по файлам
Author contributions — вклад каждого участника
PR cycle time — время от создания PR до слияния
PR review depth — количество комментариев, ревьюеров

Экспорт данных

Через OData или REST API можно экспортировать:

Список всех коммитов
Историю PR
Статусы сборок
Связи с work items

Продвинутые функции

Git Hooks (серверные)

Azure Repos не поддерживает пользовательские серверные Git hooks. Вместо этого используются:

Branch policies
Pipeline triggers
Webhooks

Submodules и Subtrees

Полностью поддерживаются стандартные механизмы Git:

git submodule add

git submodule add

git subtree add

git subtree add

Но требуют ручного управления зависимостями.

Large File Storage (LFS)

Поддержка Git LFS:

Включается в настройках репозитория
Требует установки Git LFS локально
Хранение больших бинарных файлов вне основной истории

Файлы отслеживаются через .gitattributes:

*.psd filter=lfs diff=lfs merge=lfs -text

Sparse Checkout

Поддерживается через стандартный Git. Полезен для крупных монорепозиториев.

Partial Clone / Shallow Clone

Работает как в любом Git-хостинге:

git clone --depth 1 https://...

Ограничения и квоты

Максимальный размер репозитория: 250 ГБ (рекомендуется < 10 ГБ)
Максимальный размер файла: 5 ГБ (с LFS), 100 МБ без LFS
Количество репозиториев в проекте: не ограничено
Количество веток: не ограничено
Количество PR одновременно: не ограничено
Хранение LFS: включено по умолчанию, объём зависит от лицензии

Резервное копирование и восстановление

Azure Repos не предоставляет встроенных средств резервного копирования. Рекомендации:

Использовать локальные зеркала (git clone --mirror)

git clone --mirror

Настроить регулярный push в сторонний Git-сервер
Экспортировать через REST API

Восстановление после ошибок:

git reflog — для локального восстановления
Защита веток — предотвращает потерю истории
Администраторы могут восстановить удалённые ветки через UI (в течение 30 дней)

REST API — ключевые эндпоинты и параметры

Azure DevOps предоставляет полноценный REST API для управления репозиториями, ветками, коммитами и pull request’ами. Все запросы требуют аутентификации через Personal Access Token (PAT) или OAuth.

Базовый URL

https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}

Основные ресурсы

Репозитории

GET /repositories — список всех репозиториев в проекте
Параметры: includeLinks, includeAllUrls
POST /repositories — создание нового репозитория
Тело: { "name": "MyRepo", "project": { "id": "..." } }
удаление репозитория

DELETE /repositories/{id}

Ветки

GET /refs?filter=heads/ — список всех веток
Фильтр: filter=heads/release/ — только release-ветки
POST /refs — создание или обновление ветки
Тело — массив объектов с name, oldObjectId, newObjectId
удаление ветки

DELETE /refs?filter=heads/feature/x

Коммиты

GET /commits — история коммитов
Параметры: searchCriteria.itemPath, searchCriteria.fromCommitId, searchCriteria.toCommitId, top, skip
GET /commits/{commitId} — детали конкретного коммита
POST /commits — создание коммита напрямую через API (редко используется)

Pull Requests

GET /pullrequests — список PR
Параметры — status (active, completed, abandoned), creatorId, reviewerId, sourceRefName, targetRefName
POST /pullrequests — создание PR
Тело:

  {
    "sourceRefName": "refs/heads/feature/login",
    "targetRefName": "refs/heads/main",
    "title": "Add login form",
    "description": "Implements basic auth UI",
    "reviewers": [
      { "id": "user-guid" }
    ]
  }

PATCH /pullrequests/{id} — обновление PR (например, статуса)
POST /pullrequests/{id}/threads — добавление комментария к PR

Политики

GET /policies/configurations — список политик для репозитория
POST /policies/configurations — создание политики
Пример политики "минимум 2 ревьюера":

  {
    "type": { "id": "fa4e907d-c16b-4a4c-9df2-095f3e1c938b" },
    "settings": {
      "minimumApproverCount": 2,
      "creatorVoteCounts": false,
      "allowDownvotes": false
    }
  }

Интеграция с Azure Pipelines — триггеры на Pull Request

В YAML-пайплайнах можно настроить автоматический запуск при открытии или обновлении PR.

Пример конфигурации

Код ITЗагрузка примера кода…

Параметры секции `pr`

branches.include — ветки, в которые слияние запускает пайплайн
branches.exclude — исключения
paths.include/exclude — фильтрация по изменённым файлам
Можно использовать autoCancel — отмена предыдущих запусков при новых коммитах

Статус в PR

После выполнения пайплайн отправляет статус:

succeeded — зелёная галочка
failed — красный крест
pending — ожидание

Этот статус учитывается в политике Build validation.

Аутентификация и доступ

Personal Access Token (PAT)

Создаётся в User Settings → Personal Access Tokens
Область: Code (read and write)
Используется как пароль при HTTPS-клонировании:

  git clone https://<username>:<PAT>@dev.azure.com/org/project/_git/repo

SSH-ключи

Генерируются локально: ssh-keygen -t rsa -b 4096
Публичный ключ добавляется в User Settings → SSH Public Keys
Клонирование:

  git clone git@ssh.dev.azure.com:v3/org/project/repo

Azure AD

Для корпоративных аккаунтов поддерживается SSO через Azure Active Directory
Требует настройки в организации DevOps

Git Credential Manager

Автоматически сохраняет PAT или использует интерактивный вход
Поддерживается в Windows, macOS, Linux

Миграция в Azure Repos

Из GitHub / GitLab / Bitbucket

Клонировать исходный репозиторий с --mirror:

   git clone --mirror https://github.com/user/repo.git

Добавить remote Azure Repos:

   cd repo.git
   git remote set-url --push origin https://dev.azure.com/org/project/_git/repo

Запушить всё:

   git push --mirror

Перенос истории, тегов, веток

--mirror переносит всё — коммиты, ветки, теги, заметки
LFS-объекты требуют отдельной миграции через git lfs fetch --all && git lfs push --all

git lfs fetch --all && git lfs push --all

Сохранение авторов

Имена и email из коммитов сохраняются без изменений
Если email не совпадает с Azure AD, автор отображается как "Unknown"

Сравнение с другими платформами

Функция	Azure Repos	GitHub	GitLab
Защита веток	Branch Policies	Branch Protection Rules	Protected Branches
PR ↔ Work Items	Встроенная интеграция	Projects + Issues	Issues + Epics
CI/CD	Azure Pipelines	GitHub Actions	GitLab CI
LFS	Включено по умолчанию	Требует включения	Включено
Fork внутри проекта	Да	Только в рамках аккаунта/организации	Да
REST API	Полный, версионированный	GraphQL + REST	REST + GraphQL
Webhooks	Да	Да	Да
Code Owners	Через политики	CODEOWNERS файл	CODEOWNERS файл
Draft PR	Да	Да	WIP Merge Requests

Azure Repos особенно силён в глубокой интеграции с Azure DevOps — рабочие элементы, пайплайны, тесты, артефакты — всё в единой системе.

Практические рекомендации

Именование веток

Используйте префиксы — feature/, hotfix/, release/
Избегайте пробелов и специальных символов
Добавляйте Jira/GitHub ID, если используется внешняя система: feature/PROJ-123-login

Шаблоны PR

Создайте .azuredevops/pull_request_template.md:

### Описание

Краткое описание изменений.

### Связанные задачи

- closes #123
- relates to #456

### Проверки

- [ ] Пройдены unit-тесты
- [ ] Обновлена документация
- [ ] Проверено вручную

Автоматическое удаление веток

В настройках репозитория включите:

Automatically delete source branch after merge

Это снижает количество "мёртвых" веток.

Использование squash merge

Для feature-веток рекомендуется Squash merge — один чистый коммит в main.

Для долгоживущих веток (например, develop) — Basic merge для сохранения истории.

Работа с большими репозиториями

Крупные репозитории (монорепозитории, legacy-код, мультимедийные проекты) требуют особых подходов к управлению производительностью и хранению.

Ограничения

Максимальный размер репозитория: 250 ГБ
Максимальный размер файла без LFS: 100 МБ
Рекомендуемый рабочий размер: < 10 ГБ

Оптимизация клонирования

Использование shallow clone:

  git clone --depth 1 https://dev.azure.com/org/project/_git/repo

Sparse checkout — выборочное извлечение файлов:

  git clone --filter=blob:none --sparse https://...
  git sparse-checkout set src/backend

Partial clone — загрузка только нужных объектов:

  git clone --filter=tree:0 https://...

Управление историей

BFG Repo-Cleaner или git filter-repo — для удаления больших файлов из истории

git filter-repo

После очистки — принудительный push с флагом --force-with-lease
Включение garbage collection в настройках репозитория

Разделение монорепозитория

Создание отдельных репозиториев по микросервисам
Использование submodules или subtrees для зависимостей
Поддержка общих библиотек через Azure Artifacts или private npm/PyPI

Git LFS (Large File Storage)

Git LFS заменяет большие файлы указателями, храня их отдельно.

Настройка

Установка LFS:

   git lfs install

Отслеживание файлов:

   git lfs track "*.psd"
   git lfs track "assets/**/*.mp4"

Файл .gitattributes автоматически обновляется:

   *.psd filter=lfs diff=lfs merge=lfs -text
   assets/**/*.mp4 filter=lfs diff=lfs merge=lfs -text

Хранение и квоты

LFS включён по умолчанию в Azure Repos
Объём хранения зависит от лицензии:
- Free: 1 ГБ
- Basic: 10 ГБ
- Stakeholder: не поддерживается
Дополнительное хранилище можно приобрести отдельно

Перенос LFS из других систем

Экспорт:

  git lfs fetch --all

Импорт в Azure Repos:

  git remote set-url origin https://dev.azure.com/...
  git lfs push --all origin

Ошибки и диагностика

This repository is over its Данные quota — превышена квота LFS
Smudge error — клиент не может скачать LFS-объект (часто из-за отсутствия аутентификации)
Решение: использовать PAT с правами Code (read) или настроить SSH

Политики на уровне организации

Политики могут применяться глобально ко всем проектам в организации.

Типы политик

Default branch name — задаёт имя ветки по умолчанию (main, trunk, и т.д.)
Forking policy — разрешить/запретить форки внутри организации
Repository creation policy — кто может создавать репозитории (только администраторы / все участники)
Public repository policy — разрешить публичные репозитории (только в публичных проектах)

Применение через REST API

PATCH https://dev.azure.com/{org}/_apis/policy/configurations?api-version=7.0

Тело запроса определяет тип политики и её параметры.

Наследование

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

Аудит действий и логирование

Azure DevOps предоставляет журналы аудита для отслеживания изменений.

Доступные события

Создание/удаление репозитория
Изменение политик веток
Push в защищённую ветку с обходом (bypass)
Удаление ветки
Изменение прав доступа

Просмотр журналов

Через UI: Organization Settings → Auditing
Через REST API:

  GET https://auditservice.dev.azure.com/{org}/_apis/audit/auditlog

Фильтрация по типу события, пользователю, дате

Экспорт

CSV-выгрузка через UI
Интеграция с Azure Monitor и SIEM-системами через вебхуки

Webhook-события и payload

Webhooks отправляют JSON-уведомления на внешние URL при событиях в репозитории.

Поддерживаемые события

git.push
git.pullrequest.created
git.pullrequest.merged
git.pullrequest.abandoned
git.ref.updated
git.repository.created
git.repository.deleted

Пример payload — `git.push`

Код ITЗагрузка примера кода…

Безопасность webhooks

Поддержка HMAC-подписи (в заголовке X-VSS-Signature)
Возможность задать secret token для проверки источника
Автоматическая повторная отправка при ошибке (до 5 попыток)

Ошибки

Ситуация	Что проверить
Команда не найдена	PATH, установка пакета, alias
Permission denied	пользователь, группа, sudo, ACL
Неверная версия	см. "Совместимость", `--version`

Совместимость

Область	Примечание
Версии	актуальные LTS/стабильные релизы Azure Repos Git
Платформы	официальная матрица поддержки вендора
Стандарты	RFC, ISO, спецификация API — см. таблицы выше

Основа по протоколу

Базовый разбор HTTP и HTTPS находится в отдельной статье — HTTP как основа веб-интеграций.

В подборках

Статья входит в тематические подборки и блок "С чего начать?" на главной. Соседние шаги того же маршрута:

Справочники — E2E-тесты и CI с Playwright и GitHub Actions, Справочник по SOAP, Справочник по Tempo, Справочник по gRPC, Справочник по Loki, Справочник по GraphQL.

Назначение​

Краткое пояснение​

Быстрый старт​

Справочные таблицы​

Основные элементы Azure Repos Git​

Репозиторий (Repository)​

Проект (Project)​

Организация (Organization)​

Ветвление и управление ветками​

Главная ветка (Main / Master)​

Feature-ветки​

Release-ветки​

Hotfix-ветки​

Защищённые ветки (Protected Branches)​

Политики веток (Branch Policies)​

Обязательные политики​

Pull Request (PR)​

Состояния PR​

Возможности PR​

Шаблоны PR​

Разрешения и безопасность​

Уровни доступа​

Группы безопасности​

Права на уровне ветки​

Настройки репозитория​

Общие настройки​

Параметры обслуживания​

Включение функций​

Интеграции​

Azure Pipelines​

Azure Boards​

REST API​

Webhooks​

CLI и инструменты​

Azure CLI​

Git CLI​

Visual Studio / VS Code​

Аналитика и отчётность​

Insights (вкладка Analytics)​

Экспорт данных​

Продвинутые функции​

Git Hooks (серверные)​

Submodules и Subtrees​

Large File Storage (LFS)​

Sparse Checkout​

Partial Clone / Shallow Clone​

Ограничения и квоты​

Резервное копирование и восстановление​

REST API — ключевые эндпоинты и параметры​

Базовый URL​

Основные ресурсы​

Репозитории​

Ветки​

Коммиты​

Pull Requests​

Политики​

Интеграция с Azure Pipelines — триггеры на Pull Request​

Пример конфигурации​

Параметры секции pr​

Статус в PR​

Аутентификация и доступ​

Personal Access Token (PAT)​

SSH-ключи​

Azure AD​

Git Credential Manager​

Миграция в Azure Repos​

Из GitHub / GitLab / Bitbucket​

Перенос истории, тегов, веток​

Сохранение авторов​

Сравнение с другими платформами​

Практические рекомендации​

Именование веток​

Шаблоны PR​

Автоматическое удаление веток​

Использование squash merge​

Работа с большими репозиториями​

Ограничения​

Оптимизация клонирования​

Управление историей​

Разделение монорепозитория​

Назначение

Краткое пояснение

Быстрый старт

Справочные таблицы

Основные элементы Azure Repos Git

Репозиторий (Repository)

Проект (Project)

Организация (Organization)

Ветвление и управление ветками

Главная ветка (Main / Master)

Feature-ветки

Release-ветки

Hotfix-ветки

Защищённые ветки (Protected Branches)

Политики веток (Branch Policies)

Обязательные политики

Pull Request (PR)

Состояния PR

Возможности PR

Шаблоны PR

Разрешения и безопасность

Уровни доступа

Группы безопасности

Права на уровне ветки

Настройки репозитория

Общие настройки

Параметры обслуживания

Включение функций

Интеграции

Azure Pipelines

Azure Boards

REST API

Webhooks

CLI и инструменты

Azure CLI

Git CLI

Visual Studio / VS Code

Аналитика и отчётность

Insights (вкладка Analytics)

Экспорт данных

Продвинутые функции

Git Hooks (серверные)

Submodules и Subtrees

Large File Storage (LFS)

Sparse Checkout

Partial Clone / Shallow Clone

Ограничения и квоты

Резервное копирование и восстановление

REST API — ключевые эндпоинты и параметры

Базовый URL

Основные ресурсы

Репозитории

Ветки

Коммиты

Pull Requests

Политики

Интеграция с Azure Pipelines — триггеры на Pull Request

Пример конфигурации

Параметры секции `pr`

Статус в PR

Аутентификация и доступ

Personal Access Token (PAT)

SSH-ключи

Azure AD

Git Credential Manager

Миграция в Azure Repos

Из GitHub / GitLab / Bitbucket

Перенос истории, тегов, веток

Сохранение авторов

Сравнение с другими платформами

Практические рекомендации

Именование веток

Шаблоны PR

Автоматическое удаление веток

Использование squash merge

Работа с большими репозиториями

Ограничения

Оптимизация клонирования

Управление историей

Разделение монорепозитория