KsaiLabKsaiLab
10 Development Workflow

GitLab Instance And MCP

GitLab Instance And MCP

Назначение

Этот документ фиксирует канонический GitLab-инстанс для KSAILab и рабочую схему подключения агентов через Codex MCP.

Текущая каноническая интеграция для Codex не использует прямой native endpoint https://gitlab.fxserver.ru/api/v4/mcp. Вместо этого команда использует локальный stdio MCP server @zereight/mcp-gitlab, который работает с GitLab REST API https://gitlab.fxserver.ru/api/v4.

Канонические значения

  • GitLab web instance: https://gitlab.fxserver.ru/
  • Codex MCP alias: gitlab-fxserver
  • Codex GitLab MCP package: @zereight/mcp-gitlab
  • GitLab API base URL: https://gitlab.fxserver.ru/api/v4

Агенты не должны по умолчанию переключаться на другой GitLab-инстанс. Если в задаче не указано иное, рабочим контуром считается именно gitlab.fxserver.ru.

Базовая настройка Codex

В локальном Codex-конфиге должен быть включён RMCP client и прописан GitLab MCP server через npx:

[features]
rmcp_client = true

[mcp_servers."gitlab-fxserver"]
command = "npx"
args = ["-y", "@zereight/mcp-gitlab"]
env = {
  "GITLAB_PERSONAL_ACCESS_TOKEN" = "<local-secret>",
  "GITLAB_API_URL" = "https://gitlab.fxserver.ru/api/v4",
  "GITLAB_READ_ONLY_MODE" = "false",
  "USE_GITLAB_WIKI" = "false",
  "USE_MILESTONE" = "false",
  "USE_PIPELINE" = "false"
}
startup_timeout_sec = 45

Типовой способ регистрации сервера:

codex mcp add gitlab-fxserver --env GITLAB_PERSONAL_ACCESS_TOKEN=<local-secret> --env GITLAB_API_URL=https://gitlab.fxserver.ru/api/v4 --env GITLAB_READ_ONLY_MODE=false --env USE_GITLAB_WIKI=false --env USE_MILESTONE=false --env USE_PIPELINE=false -- npx -y @zereight/mcp-gitlab

Токен хранится только локально. Его нельзя коммитить в репозитории, документацию или .gitlab templates.

Ключевые переменные

  • GITLAB_PERSONAL_ACCESS_TOKEN — GitLab PAT для работы MCP server.
  • GITLAB_API_URL — для KSAILab фиксируется как https://gitlab.fxserver.ru/api/v4.
  • GITLAB_READ_ONLY_MODE — false для delivery agents, true для чисто аналитических и review-only сценариев.
  • GITLAB_ALLOWED_PROJECT_IDS — рекомендуемое ограничение по проектам, если нужно сузить поверхность доступа.
  • GITLAB_TOOLSETS — рекомендуемый способ ограничить набор доступных операций.
  • USE_GITLAB_WIKI, USE_MILESTONE, USE_PIPELINE — по умолчанию держим false, если задача прямо не требует этих возможностей.

Рекомендуемый профиль для KSAILab

Для текущей разработки рекомендуется такой operating profile:

  • alias: gitlab-fxserver
  • package: @zereight/mcp-gitlab
  • GitLab API URL: https://gitlab.fxserver.ru/api/v4
  • read-only mode: false для delivery-агентов, которые создают issue и MR
  • wiki: false
  • milestones: false
  • pipelines: false

Если нужно уменьшить поверхность доступа, дополнительно рекомендуется:

  • задать GITLAB_ALLOWED_PROJECT_IDS для ksailab-проектов;
  • использовать GITLAB_TOOLSETS=issues,merge_requests,projects,repositories,branches,labels,users вместо полного набора тулов.

Проверенный статус на 6 марта 2026 года

Во время проверки были получены такие факты:

  • codex mcp list показывает gitlab-fxserver как рабочий stdio MCP server;
  • сервер запускается через npx -y @zereight/mcp-gitlab;
  • используются GITLAB_API_URL=https://gitlab.fxserver.ru/api/v4 и GitLab PAT;
  • режимы USE_GITLAB_WIKI=false, USE_MILESTONE=false, USE_PIPELINE=false уже совместимы с текущим delivery flow.

Вывод: каноническая и рабочая интеграция GitLab в Codex для KSAILab сейчас построена на @zereight/mcp-gitlab, а не на native GitLab MCP endpoint.

Практика администрирования

Текущая модель администрирования должна быть такой:

  • alias gitlab-fxserver остаётся стабильным;
  • файлы в backend-ksailab, frontend-ksailab, keycloak-scripts-ksailab и docs-ksailab редактируются локально в самих репозиториях через обычный git workflow;
  • GitLab MCP используется прежде всего для issue, labels, boards, merge requests и других GitLab-операций, а не как замена локальному редактированию файлов;
  • обновляется локальная MCP-конфигурация, а не repo files;
  • токен выдаётся отдельно и живёт только на машине разработчика или агента;
  • документация описывает схему, но не содержит реальных секретов;
  • если меняется набор доступных операций, это отражается через GITLAB_TOOLSETS и feature flags, а не через устные договорённости.

Если локальная workspace-папка для scripts repo всё ещё называется keycloak-ksailab, это допустимо как локальное имя каталога. Канонический GitLab path при этом должен описываться как ksailab/keycloak-scripts-ksailab.

Legacy Note

Прежняя схема с прямым подключением Codex к https://gitlab.fxserver.ru/api/v4/mcp и OAuth login для текущего процесса больше не считается канонической.

Её можно рассматривать только как исторический эксперимент. Рабочей и документируемой моделью является @zereight/mcp-gitlab через локальный Codex stdio server.

Правила для агентов

  • Всегда использовать https://gitlab.fxserver.ru/ как канонический GitLab-инстанс KSAILab.
  • Всегда предпочитать MCP alias gitlab-fxserver, если он доступен в Codex.
  • Всегда исходить из того, что GitLab MCP реализован через @zereight/mcp-gitlab и GitLab REST API https://gitlab.fxserver.ru/api/v4.
  • Не предполагать доступность wiki, milestone и pipeline tools, если эти флаги явно не включены.
  • Никогда не утверждать, что issue или MR были созданы, если фактический вызов GitLab не завершился успешно.
  • Для всех ручных fallback-сценариев сохранять трассируемость: issue id, branch name, MR link, changelog/devlog entry.

Что ещё важно улучшить

Следующий шаг зрелости для этой интеграции:

  • вынести PAT из локального inline-config в более безопасную схему хранения секретов;
  • зафиксировать рекомендуемый GITLAB_ALLOWED_PROJECT_IDS список для KSAILab;
  • согласовать GITLAB_TOOLSETS для разных классов агентов: delivery, review, docs-only.

Development Workflow

Темы для обсуждения и принятия решений