GitLab — репозитории, CI/CD и агентные функции в одной платформе

Практический справочник по GitLab: как устроена платформа, чем различаются тарифы, как собрать первый пайплайн и в каких случаях GitLab заменяет связку из отдельных сервисов.

Что такое GitLab

GitLab закрывает весь путь кода в одном веб-приложении: хранение репозиториев, проверку кода через merge request, автоматические сборки и деплой, реестры пакетов и контейнеров, сканирование уязвимостей, задачи и планирование. Для этого используются единая учётная запись, общий интерфейс и одна система прав доступа.

Платформа работает в трёх вариантах поставки: облако GitLab.com, установка на своих серверах (Self-Managed) и изолированное облако для одного клиента (GitLab Dedicated). Доступные функции зависят от тарифа и варианта поставки.

Основные возможности

Тарифы и лимиты GitLab.com

Цифры проверены 7 сентября 2026 года и относятся к облачному сервису GitLab.com.

Полезные детали для расчёта бюджета:

• Дополнительные compute-минуты стоят 10 $ за 1 000 минут единоразово. Собственные раннеры не расходуют квоту GitLab.com.
• Дополнительное хранилище на странице тарифов указано как доступное для Premium и Ultimate: 5 $ в месяц за 10 GiB при годовой оплате. В FAQ той же страницы отдельно сказано, что пользователи Free могут купить дополнительное хранилище, поэтому перед расчётом бюджета проверьте доступность покупки для конкретной группы. Покупка увеличивает общий объём пространства, но не поднимает фиксированный предел 500 GiB для отдельного проекта на Premium и Ultimate.
• Купленное хранилище относится к Git-репозиториям и Git LFS. Container Registry учитывается отдельно.
• Включённые кредиты Premium и Ultimate являются ограниченным по времени промопредложением. GitLab может изменить его условия.
• Дополнительные GitLab Credits можно покупать отдельно. Стандартная ставка использования по требованию — 1 $ за кредит. Фактическое списание зависит от функции и выбранной модели, а условия биллинга — от тарифа и обязательств.
• Подходящие открытые проекты, образовательные учреждения и стартапы могут получить Ultimate и квоту 50 000 compute-минут через программы GitLab for Open Source, Education и Startups.

Создание проекта и подключение локального репозитория

1. Зарегистрируйтесь на gitlab.com. Если подпиской, минутами и хранилищем будет управлять команда, разместите проект в группе. Если вы отправляете уже существующий локальный репозиторий, не инициализируйте в GitLab стартовый README или другой начальный коммит.
2. Выберите New project → Create blank project.
3. Подключите локальный репозиторий и отправьте первый коммит.

   # Инициализация репозитория с веткой main
   git init
   git branch -M main
   git remote add origin https://gitlab.com/<группа>/<проект>.git
   git add .
   git commit -m "Первый коммит"
   git push -u origin main

Для git push заранее настройте аутентификацию в GitLab через SSH или HTTP. Не помещайте токены в URL удалённого репозитория.

1. Выдайте участникам подходящие роли через Manage → Members.
2. Секреты передавайте через переменные CI/CD: Settings → CI/CD → Variables. Для чувствительных значений используйте доступные флаги Masked и Protected. Не сохраняйте токены в репозитории.

Первый пайплайн в .gitlab-ci.yml

Пайплайн описывается файлом .gitlab-ci.yml в корне репозитория. Следующая конфигурация запускает сборку и тесты для merge request и основной ветки. Пример рассчитан на Node.js-проект с package-lock.json и скриптами build и test в package.json.

stages:
  - build
  - test

build-job:
  stage: build
  image: node:22-alpine   # Окружение задания
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/             # Результат сборки
    expire_in: 1 week
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

test-job:
  stage: test
  image: node:22-alpine
  script:
    - npm ci
    - npm test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

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

Раннеры GitLab

Раннер — приложение, которое получает задание CI/CD, выполняет его на вычислительной инфраструктуре и возвращает результат в GitLab.

• GitLab-hosted runners управляются GitLab и доступны в GitLab.com. Их использование расходует compute-минуты тарифа.
• Self-managed runners устанавливаются и обслуживаются на вашей инфраструктуре. Они доступны на всех тарифах и не расходуют квоту compute-минут GitLab.com.

Собственный раннер подходит для длинных пайплайнов, особого окружения, GPU или доступа к внутренней сети. GitLab Runner поддерживает Docker, Shell, Kubernetes, SSH и другие исполнители. Версию GitLab Runner желательно синхронизировать с мажорной и минорной версиями GitLab, чтобы новые функции работали корректно.

GitLab Duo Agent Platform

GitLab Duo объединяет AI-функции для работы с кодом и объектами проекта. В зависимости от тарифа и доступной функции платформа может предлагать подсказки кода, агентный чат, автоматизированное ревью, преобразование issue в merge request и исправление упавших пайплайнов.

GitLab Duo Agent Platform стала общедоступной в GitLab 18.8. Для Self-Managed поддержка платформы и GitLab Credits начинается с версии 18.8; для триала Ultimate с кредитами требуется версия 18.9 или новее.

Для Self-Managed одной версии недостаточно: включите Agent Platform и настройте экземпляр. Для Duo Self-Hosted установите AI Gateway с сервисом Agent Platform.

Доступность зависит от конкретной функции:

• часть функций можно использовать на Free после покупки GitLab Credits;
• Premium и Ultimate включают разные наборы возможностей;
• некоторые агенты и процессы доступны только в Ultimate;
• общедоступные агентные функции расходуют GitLab Credits при использовании.

GitLab.com, Self-Managed или Dedicated

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

Эталонный .gitlab-ci.yml

Пример для веб-проекта: сборка, тесты, публикация контейнерного образа и ручной деплой из основной ветки. Для заданий build и test нужен Node.js-проект с package-lock.json и соответствующими скриптами в package.json.

stages:
  - build
  - test
  - release
  - deploy

variables:
  IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

default:
  image: node:22-alpine
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/

build:
  stage: build
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run build
  artifacts:
    paths:
      - dist/
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

test:
  stage: test
  script:
    - npm ci --cache .npm --prefer-offline
    - npm test -- --ci
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

release-image:
  stage: release
  image: docker:27
  services:
    - docker:27-dind
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: ""   # Используется небезопасное соединение внутри job-сети
  script:
    # Переменные реестра выдаются заданию автоматически
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
    - docker build -t "$IMAGE" .
    - docker push "$IMAGE"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-production:
  stage: deploy
  environment:
    name: production
    url: https://example.com
  script:
    # Команда зависит от выбранной схемы безопасного деплоя
    - ./scripts/deploy.sh "$IMAGE"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual

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

Полезные сценарии

Статичный сайт или документация на GitLab Pages

Задача: собирать и публиковать сайт из того же репозитория. Исходное условие — команда сборки должна создавать папку dist.

Для GitLab Pages используйте задание с именем pages; опубликованный артефакт должен находиться в папке public/.

pages:
  stage: deploy
  script:
    - npm ci
    - npm run build
    - mv dist public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

После успешного завершения задания pages и связанного процесса pages:deploy результат проверяется в разделе Deploy → Pages. Сценарий не подходит, если приложению нужен постоянно работающий серверный процесс.

Запрет слияния без зелёного пайплайна

Задача: не допускать непроверенный код в основную ветку.

1. В Settings → Repository → Protected branches защитите main и ограничьте прямую отправку изменений.
2. В настройках merge request включите требование успешного пайплайна и разрешения обсуждений, если эти параметры доступны для вашего проекта и тарифа.
3. Запускайте тесты для merge_request_event.
4. Настройте правила утверждения, соответствующие тарифу и процессу команды.

Наблюдаемый результат: merge request с упавшим обязательным пайплайном нельзя слить штатным способом.

Код остаётся во внешнем репозитории

GitLab умеет импортировать проекты из GitHub и Bitbucket. Для постоянной синхронизации направление зеркала и доступность функции зависят от тарифа, поэтому перед настройкой проверьте актуальный раздел Settings → Repository → Mirroring repositories и документацию по repository mirroring.

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

Ночные проверки по расписанию

Задача: выполнять тяжёлые e2e-тесты и периодические проверки отдельно от обычных пушей.

nightly-e2e:
  stage: test
  script:
    - npm run test:e2e
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

Создайте расписание в Build → Pipeline schedules. Результат — отдельный пайплайн с источником schedule; задание не должно появляться в обычном пайплайне пуша.

Монорепозиторий: запуск только затронутых сервисов

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

test-api:
  stage: test
  script:
    - pytest services/api
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - services/api/**/*
        - requirements.txt

Проверка: изменение файлов API добавляет test-api в пайплайн merge request, а изменение только фронтенда — нет.

Пакеты и образы без внешнего реестра

Внутренние библиотеки можно публиковать в Package Registry, а контейнерные образы — в Container Registry. Для авторизации в заданиях CI/CD часто можно использовать $CI_JOB_TOKEN, но его область доступа и разрешения нужно проверить для конкретных проектов.

Результат проверяется появлением версии пакета или тега образа в разделе Deploy. При расчёте бюджета отдельно проверяйте использование Git-репозитория, LFS, артефактов и Container Registry: правила хранения для этих типов различаются.

Проверка результата

Минимальный сценарий проверки первого пайплайна:

1. Добавьте .gitlab-ci.yml из раздела «Первый пайплайн» и отправьте изменения в основную ветку или создайте merge request.
2. Откройте Build → Pipelines и убедитесь, что появился новый пайплайн.
3. Откройте задания build-job и test-job. После успешного выполнения они получат статус passed; откройте журнал и убедитесь, что команды завершились без ошибок.
4. В build-job проверьте наличие артефакта с папкой dist/.
5. Если использовался размещённый раннер GitLab.com, проверьте расход compute-минут в разделе квот. При выполнении на собственном раннере эта квота не расходуется.

Если пайплайн не запускается, проверьте:

• файл .gitlab-ci.yml находится в корне нужной ветки;
• условия rules подходят источнику текущего пайплайна;
• для проекта доступен раннер;
• теги задания совпадают с тегами раннера;
• у пользователя достаточно прав для выбранного действия;
• синтаксис конфигурации проходит встроенную проверку.

Ограничения и когда GitLab не подходит

• Приватная верхняя группа больше пяти человек на Free. Для такой команды потребуется платный тариф или другой вариант размещения.
• Регулярные сборки на размещённых раннерах. Квота Free в 400 compute-минут может быстро закончиться. Рассмотрите платный тариф или собственный раннер.
• Нет ресурсов на администрирование. Self-Managed требует обновлений, резервных копий, мониторинга и защиты инфраструктуры.
• Нужно только хранение одного репозитория. Значительная часть пользы GitLab появляется при совместном использовании репозитория, CI/CD, безопасности и управления работой.
• Нужна функция определённого тарифа. Перед миграцией проверьте тариф для правил merge request, средств безопасности и отдельных возможностей Duo Agent Platform.

Ссылки

• Тарифы: about.gitlab.com/pricing
• Документация: docs.gitlab.com
• Руководство по первому пайплайну: docs.gitlab.com/ci/quick_start/tutorial
• GitLab Runner: docs.gitlab.com/runner
• GitLab Duo Agent Platform: docs.gitlab.com/user/duo_agent_platform
• Новые версии GitLab: about.gitlab.com/whats-new

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

Если вы сравниваете GitLab с GitHub и хотите сначала разобраться с базовым workflow работы с репозиторием, продолжите с GitHub для новичков — полное руководство: от регистрации до работы с Codex.

Связанные материалы

• Статья: Мой первый публичный репозиторий на GitHub — и это Codex-скилл для GPT Pro review
• Блог: GitHub предлагает забрать свой репозиторий на CD-ROM
• База знаний: Mise, SOPS и age в проектах команды

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov