Git-хостинги

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

Настраивайте интеграции исходного кода в Settings > Integrations. Поддерживаются GitLab, GitHub и обычный Git. Коннекторы GitHub и обычного Git доступны на всех тарифах; интеграция GitLab, включая обнаружение реестра GitLab, требует Personal или выше. Коннекторы GitLab, созданные на Community до 2.11, сохраняются, но их нельзя открыть, пока не активирован ключ Personal или выше. Сборки из Git требуют Business или Enterprise. Доступ к удалённой ОС описан отдельно в разделе SSH-подключения.

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

URL репозитория не должны содержать встроенные учётные данные. Проверка ключей хоста SSH и сертификатов HTTPS должна завершаться безопасным отказом. Удаляйте интеграцию только после обнаружения и миграции зависимых источников Docker, Compose Project и Pages.

Типы интеграций

• GitLab: обнаружение проектов и групп, операции с репозиторием, webhooks, переменные, процессы CI и необязательное обнаружение реестра в соответствии с правами по тарифу.
• GitHub: обнаружение репозиториев и поддерживаемые операции с репозиторием или Actions через настроенное приложение или токен.
• Generic Git: ограниченный аутентифицированный доступ к репозиторию, когда отдельный поставщик не требуется.

GitLab

1. Используйте отдельного пользователя GitLab с членством только в нужных группах/проектах. В меню аватара откройте Edit profile > Access > Personal access tokens. Создайте токен: интерфейс может называть его классическим персональным токеном.
2. Задайте имя, срок действия и права из таблицы. Сразу скопируйте секрет.
3. В интеграции GitLab в Opfield укажите адрес экземпляра, например https://gitlab.example.com, без /api/v4, и токен. Выберите разрешённые проекты/группы вместо всех обнаруженных проектов.
4. Проверьте токен, обнаружение разрешённого проекта и доступ к репозиторию и ветке. Токен развёртывания GitLab не заменяет эту учётную запись API.

Сценарий	Права токена GitLab
Обнаружение проектов и чтение метаданных API	read_api
Чтение/клонирование кода для сборок	read_repository вместе с read_api для специализированного коннектора
Обнаружение/скачивание приватных образов реестра	Дополнительно read_registry и нужное членство в проекте
Запись файлов через API, управление обработчиками событий/переменными, изменяющие операции CI	api; роль пользователя в проекте также должна разрешать операцию
Отправка изменений через Git по HTTPS	write_repository; это не даёт общего права записи через API

Для сборок с чтением исходников начните с read_api + read_repository, а не с api. Широкое право api нужно только для включённых сценариев записи. Токен не обходит защиту веток и отсутствие членства в проекте. Персональная авторизация GitLab для интерактивных инструментов остаётся отдельной от сохранённого системного токена.

Источники: создание персонального токена GitLab, права токенов GitLab.

GitHub

Если настроено подключение OAuth, используйте Connect GitHub и проверьте запрашиваемый доступ к организациям и репозиториям на экране согласия GitHub. Для подключения токеном:

1. В GitHub откройте Settings > Developer settings > Personal access tokens > Tokens (classic) > Generate new token (classic).
2. Задайте отдельное имя и срок действия. Выберите repo для приватных репозиториев или public_repo, если нужны только публичные. Это широкие права на репозиторий, а не только чтение: ограничьте доступ самой учётной записи нужными репозиториями.
3. Дополнительные права выбирайте только для сценариев из таблицы ниже. Создайте и скопируйте токен. При необходимости авторизуйте его для SSO организации.
4. Добавьте токен в интеграцию GitHub в Opfield, выберите разрешённые репозитории/организации и проверьте обнаружение репозитория и доступ к нужной ревизии.

Дополнительный сценарий	Право классического токена
Чтение членства в организациях и командах	read:org
Скачивание пакетов GitHub Packages	read:packages
Изменение файлов процессов GitHub Actions	workflow вместе с доступом к репозиторию

Ограничение текущей реализации: Opfield определяет возможности токена GitHub по классическим правам OAuth. Детализированный персональный токен (fine-grained PAT) может пройти аутентификацию GitHub, но коннектор не распознает доступ к репозиториям. Не заменяйте им токен из инструкции выше. Если организация запрещает классические токены, используйте одобренное настроенное подключение OAuth либо сначала решите вопрос совместимости коннектора; не ослабляйте политику организации. Для сборки сохранённого репозитория не нужны delete_repo и администрирование организации.

Источники: управление персональными токенами GitHub, значения классических прав OAuth.

Generic Git

1. На Git-сервере создайте отдельные учётные данные для клонирования выбранных репозиториев. Например, токен развёртывания GitLab с read_repository подходит для Git по HTTPS, но не заменяет токен специализированного коннектора API GitLab.
2. В Opfield выберите обычный Git. Укажите Git host URL, например https://git.example.com, и явный список Repositories, например https://git.example.com/team/app.git.
3. Заполните Username и Access token отдельно. Для токена развёртывания используйте выданное с ним имя пользователя. Не добавляйте учётные данные в URL репозитория.
4. Нажмите Test connection и сохраните. Тест проверяет первый репозиторий: перед использованием в сборках отдельно проверьте доступ к остальным разрешённым репозиториям.

Это подключение по HTTPS, а не импорт приватного ключа из External SSH. У него нет универсального набора прав всех Git-провайдеров или полного набора возможностей API GitLab/GitHub. Успешное клонирование не подтверждает права управления обработчиками событий, переменными или CI через API.

Безопасная настройка

1. Создайте отдельную идентичность поставщика или машинную идентичность.
2. Выдайте доступ к репозиторию только для чтения, если документированный процесс не требует записи.
3. Ограничьте организации, группы, проекты и репозитории через поддерживаемый коннектором режим выбора.
4. Добавьте интеграцию в Settings → Integrations.
5. Проверьте TLS-сертификат или SSH-ключ сервера до сохранения учётных данных.
6. Проверьте обнаружение репозитория и доступ к одной разрешённой ревизии.
7. Убедитесь, что репозиторий или хост вне области отклоняется.
8. Настраивайте проверку подлинности и доставку webhook только после успешной работы пути чтения.

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

Список разрешённых репозиториев коннектора определяет, до каких репозиториев Opfield вообще может дотянуться. Скоупы интеграций Git определяют, какие пользователи, группы, API-токены и разрешения OAuth могут ими пользоваться. Любой скоуп Git, кроме manage, можно ограничить уровнем ниже коннектора:

• GitLab: группой, которая охватывает и свои подгруппы со всеми проектами в них, или одним проектом. Opfield получает родительские группы проекта из GitLab, поэтому проект, перенесённый в другую группу, следует за новой группой.
• GitHub: владельцем — это все репозитории организации или пользователя — или одним репозиторием.
• Обычный Git: только коннектором.

Для администрирования коннектора — настроек, токенов, списка разрешённых репозиториев, синхронизации, проверки и удаления — нужен integrations:<provider>:manage на этот коннектор или без ограничения; право на группу, владельца, проект или репозиторий его никогда не даёт.

Чтобы ограничить право, откройте ограничение скоупа в редакторе группы, дополнительных правах пользователя, форме API-токена или согласии OAuth и MCP. Отметьте коннектор, чтобы охватить все его репозитории, или откройте под коннектором Add groups or projects… либо Add owners or repositories…, найдите цели у поставщика и выберите их. Права хранят числовые идентификаторы поставщика, поэтому переименование и перенос их не ломают; удалённая с тех пор цель показывается как Unavailable, и её по-прежнему можно убрать.

При ограниченных правах:

• Списки коннекторов, проектов и репозиториев, включая выбор источника сборки, показывают только то, что охватывают права. Если проекта нет в списке, чаще всего он вне выданного права, а не не синхронизирован.
• Каждая операция с репозиторием проверяет сам репозиторий — файлы, ветки, коммиты, конвейеры и журналы заданий, переменные, вебхуки, токены развёртывания, настройки реестра и клонирование в песочницу — одинаково в Console, REST API, AI Workspace и MCP. Проект GitLab вне выданного права отвечает так же, как несинхронизированный проект: 404 GITLAB_PROJECT_NOT_FOUND без пути, поэтому перебирать идентификаторы проектов бесполезно. Для GitHub и обычного Git, где вызывающий сам указывает репозиторий, отказ возвращает 403 CONNECTOR_SCOPE_DENIED с нужным скоупом.
• Opfield использует учётные данные коннектора для репозитория, только если use охватывает этот репозиторий; иначе используются личные учётные данные пользователя.
• Запись, секреты, клонирование в песочницу и выбор учётных данных читают группы проекта GitLab или владельца репозитория GitHub у поставщика заново, поэтому перенесённый репозиторий оценивается по его текущему месту; обычное чтение может использовать значение из кэша не старше пяти минут. Синхронизация коннектора и доставка вебхуков источника очищают кэш.
• Поиск целей предлагает только цели из списка разрешённых репозиториев коннектора и ограничен 60 запросами в минуту на учётную запись; сверх этого он возвращает 429 SCOPE_TARGET_RATE_LIMITED с Retry-After.
• API-токены и разрешения OAuth сохраняют собственные ограничения и при каждом запросе дополнительно проверяются по текущим правам владельца. Токен, ограниченный одним проектом, работает, пока у владельца есть группа, содержащая проект, и перестаёт работать, когда владелец теряет этот доступ.

Точный формат ограничений и запросы для выбора целей описаны в разделе «Ограничения интеграций Git».

Жизненный цикл привязки источника

Кто может запускать и просматривать сборки?

Обнаружение репозиториев и прямые операции с исходным кодом используют права соответствующей интеграции. GitLab, GitHub и обычный Git используют одинаковые действия: integrations:<provider>:view показывает подключения, :manage настраивает, проверяет и синхронизирует их, :use использует собственные учётные данные подключения, а :repo:read и :repo:write читают или изменяют содержимое репозитория. Для просмотра и чтения синхронизированных проектов GitLab нужен integrations:gitlab:view. repo:read для GitLab охватывает файлы репозитория, конвейеры CI и журналы заданий, а также ключи переменных CI/CD без значений; для изменения переменных нужен repo:write, а для чтения значений переменных GitHub Actions — integrations:github:repo:write. Встроенные группы viewer и operator получают только integrations:gitlab:view. См. справочник скоупов. Каждый из этих скоупов можно ограничить коннектором, группой или проектом GitLab либо владельцем или репозиторием GitHub; см. «Ограничение доступа к репозиториям».

Для привязки или изменения источника нужен integrations:<provider>:use на репозиторий вместе с собственными правами рабочей нагрузки. Достаточно use, ограниченного одним проектом или репозиторием; repo:read и личные учётные данные у поставщика не нужны, потому что сборки используют учётные данные коннектора. Поэтому встроенная группа operator видит проекты GitLab при выборе источника, но не может сохранить источник, пока не получит integrations:gitlab:use — лучше ограниченный проектами, которые она собирает. Интерактивные инструменты GitLab в AI Workspace запрашивают собственную авторизацию пользователя в GitLab, если use не охватывает проект.

Запуск сборки из уже сохранённого источника — действие над ресурсом: docker:containers:manage для контейнеров и развёртываний, docker:compose:manage для Compose и pages:deploy для Pages. Кроме того, Opfield заново проверяет integrations:<provider>:use вызывающего на сохранённый репозиторий, поэтому отзыв use останавливает ручные пересборки. repo:read по-прежнему не нужен. Opfield также проверяет сохранённый коннектор, разрешённый репозиторий и учётные данные источника.

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

• Источники, сохранённые до 2.11, продолжают собираться автоматически, как и раньше.
• Источники, созданные или сохранённые заново после этого, собираются автоматически, только пока учётная запись, сохранившая их последней, активна и сохраняет integrations:<provider>:use на репозиторий. Иначе сборка не запускается: в истории сборок появляется отменённая сборка с кодом SOURCE_OWNER_ACCESS_REVOKED и сообщением Build paused: <user> no longer has use on <repo> — по одной на коммит, — а источник показывает то же сообщение как ошибку опроса или вебхука. Доставки вебхуков по-прежнему принимаются. Автоматические сборки возобновляются, когда учётная запись снова получает use или когда источник заново сохраняет тот, у кого он есть.

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

История и логи сборок требуют права просмотра цели: docker:containers:view, docker:compose:view или pages:view. Ограничения конкретным ресурсом и наследуемой папкой сохраняются. Начиная с 2.11 любое право действия над той же целью, например docker:containers:manage, также даёт её просмотр. Не расширяйте доступ до всей ноды или всех репозиториев вместо выдачи нужного разрешения на цель. См. Права доступа.

Сохранённые привязки

Практические сценарии: сборки Docker, сборки Pages из Git и реестры образов. Другие типы коннекторов перечислены в обзоре интеграций.

Рабочие нагрузки Docker, Compose Project и Pages Projects создают собственные привязки источника. Привязка хранит интеграцию, репозиторий, выбор ревизии, конфигурацию сборки, политику автоматизации и Build Secrets с областью источника.

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

Диагностика

Разделяйте ошибку аутентификации, отказ списка разрешений, отсутствие репозитория, разрешение ревизии, доставку webhook, допуск Build Worker и отсутствие права по тарифу. На странице интеграции и в связанных Tasks сохраните идентификаторы запросов поставщика и историю операций Opfield, не записывая токены, закрытые ключи, переменные или Build Secrets. Исправьте именно найденный уровень и повторите ограниченную проверку.

Процесс исходного кода для рабочей среды

Связывайте исходный код рабочей среды с проверенной политикой веток и точным разрешённым коммитом. Имя ветки служит входом выбора, а дайджест коммита — неизменяемым доказательством собранного содержимого. До включения автоматических действий подтвердите корень приложения, менеджер пакетов, скрипт сборки, каталог артефакта, платформу среды выполнения и политику публикации или развёртывания. Храните Build Secrets отдельно от обычных Variables среды выполнения и выдавайте только значения, нужные на этапе сборки.

Для Pages и управляемых сборок Git проверяйте всю цепочку: доступ поставщика, обнаружение репозитория, разрешение коммита, допуск Build Worker, загрузку зависимостей, создание артефакта, политику уязвимостей, если она включена, неизменяемую идентичность артефакта, публикацию Tag или ревизию рабочей нагрузки и состояние клиентского пути. Успешный webhook поставщика или клонирование источника — только начало цепочки.

Срок действия и ротация токенов

Opfield записывает сроки действия токенов подключений GitLab и личных токенов GitLab пользователей и ежедневно их проверяет.

• Оповещения: Opfield поднимает оповещения за 30 и 7 дней до истечения токена подключения, личного токена GitLab или авторизации интеграции, подключённой через OAuth, если срок известен. GitLab сообщает сроки своих токенов; токены GitHub и обычного Git охватываются, если они подключены через OAuth.
• Самостоятельная ротация в GitLab: за 14 дней до истечения Opfield выполняет ротацию токенов подключений GitLab и личных токенов GitLab с областью api или self_rotate. Новый токен сохраняет прежний срок действия — от 30 дней до года — и заменяет сохранённый секрет; ротация записывается в аудит. Токены доступа проектов и групп не могут выполнить ротацию сами этим способом и получают только оповещения.
• Просроченные токены: Opfield перестаёт использовать токен после истечения его срока. Просроченный личный токен GitLab завершается ошибкой GIT_CREDENTIAL_EXPIRED (HTTP 428), и пользователю нужно авторизовать новый; просроченный токен подключения GitLab — ошибкой CONNECTOR_TOKEN_EXPIRED (HTTP 409). Для замены просроченного токена подключения старый токен не нужен.

Синхронизация, источники Docker и сборки Pages, зависящие от просроченного токена, перестают работать до его замены, поэтому для токенов, которые Opfield не может обновить сам, считайте оповещение за 30 дней крайним сроком ротации.

Ротация, миграция и удаление

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

Перед удалением коннектора перечислите все зависимости Docker, Compose Project, Pages, реестра, webhook и автоматизации. Сначала отключите триггеры. Уже работающие неизменяемые артефакты могут продолжить работу, но после исчезновения коннектора будущие сборки, обновления или восстановление из источника завершатся ошибкой. Сохраняйте последний одобренный артефакт и инструкцию отката, пока новый путь источника не пройдёт полный эксплуатационный цикл.

Проверка безопасности

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

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