# GitLab CI

> Встроенная в GitLab система CI/CD — конвейеры из стадий и заданий описываются в файле .gitlab-ci.yml и выполняются раннерами, в том числе на собственных серверах.

Источник: https://llmdocs.ru/wiki/gitlab-ci/ · обновлено 2026-11-09 · лицензия CC BY-SA 4.0

- **Тип**: система CI/CD
- **Разработчик**: GitLab Inc.
- **Встроена в GitLab**: с версии 8.0 (сентябрь 2015)
- **Описание конвейера**: файл .gitlab-ci.yml в корне репозитория
- **Исполнитель**: GitLab Runner (Go)
- **Executors**: shell, docker, kubernetes, docker-autoscaler, ssh и др.
- **Размещение**: GitLab.com или собственный сервер (self-managed)
**GitLab CI** (GitLab CI/CD) — система непрерывной интеграции и доставки, встроенная в платформу [GitLab](https://llmdocs.ru/wiki/gitlab.md). Конвейер (*pipeline*) описывается в файле `.gitlab-ci.yml` в корне репозитория: из каких **стадий** и **заданий** он состоит, какие команды выполнять и при каких условиях.[1] Задания исполняет **GitLab Runner** — агент, который можно установить на свой сервер, виртуальную машину или в кластер [Kubernetes](https://llmdocs.ru/wiki/kubernetes.md). Именно возможность держать всё — и Git-хостинг, и CI, и реестр образов — внутри собственной инфраструктуры сделала GitLab популярным в компаниях, в том числе российских.

## История

GitLab начал в 2011 году Дмитрий Запорожец как открытую альтернативу [GitHub](https://llmdocs.ru/wiki/github.md). Система CI сначала была отдельным приложением GitLab CI, а в версии 8.0 (сентябрь 2015) её встроили в основной продукт.[6] Раннер переписали на Go, и он стал отдельным открытым проектом. Со временем GitLab превратился в «DevOps-платформу» — с задачами, реестрами пакетов и образов, сканерами безопасности и средствами развёртывания в одном интерфейсе.

## Основные понятия

- **Pipeline** — один запуск конвейера для коммита, merge request, тега или по расписанию.
- **Stage** — стадия; задания одной стадии идут параллельно, стадии — последовательно (по умолчанию `build`, `test`, `deploy`).
- **Job** — задание: набор команд `script`, выполняемых раннером в чистом окружении.
- **Runner** — агент, забирающий задания из очереди. **Executor** определяет, где они выполняются: прямо в оболочке, в контейнере [Docker](https://llmdocs.ru/wiki/docker.md), в поде Kubernetes.[3]
- **Artifacts** — файлы, сохраняемые после задания и передаваемые следующим (сборки, отчёты тестов).
- **Cache** — файлы, переиспользуемые между запусками для ускорения (зависимости).

## Пример

```yaml
# .gitlab-ci.yml
stages: [test, build, deploy]

default:
  image: python:3.13-slim

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

test:
  stage: test
  cache:
    paths: [.cache/pip]
  script:
    - pip install -r requirements.txt
    - pytest --junitxml=report.xml
  artifacts:
    reports:
      junit: report.xml

build-image:
  stage: build
  image: docker:27
  services: [docker:27-dind]
  script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-prod:
  stage: deploy
  script: ./deploy.sh "$CI_COMMIT_SHORT_SHA"
  environment:
    name: production
    url: https://example.com
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual
```

Переменные вида `CI_COMMIT_SHA`, `CI_REGISTRY_IMAGE`, `CI_DEFAULT_BRANCH` GitLab подставляет сам — их больше сотни.[4]

## Управление запуском

- **`rules`** — условия, при которых задание попадает в конвейер: ветка, тип события, изменённые файлы (`changes:`), значения переменных. Пришли на смену устаревшим `only`/`except`.[2]
- **`needs`** — явные зависимости между заданиями: задание стартует, как только готовы его зависимости, не дожидаясь конца стадии. Конвейер превращается в граф (DAG) и идёт быстрее.
- **`when: manual`** — ручной запуск кнопкой, типично для выкладки в продакшен.
- **`include`** и **`extends`** — подключение общих шаблонов из других файлов и проектов; **CI/CD-компоненты** с параметрами — современный способ переиспользования.
- **Дочерние и многопроектные конвейеры** (`trigger:`) — для монорепозиториев и цепочек сервисов.

## Окружения и секреты

**Окружения** (`environment:`) связывают задания развёртывания с адресами стендов, показывают историю выкладок и позволяют откатиться повторным запуском прошлого задания.[5] Переменные проекта и группы могут быть **защищёнными** (доступны только в защищённых ветках и тегах) и **маскированными** (скрываются в логах). Для облаков поддерживается выдача временных учётных данных через ID-токены (OIDC) и интеграция с HashiCorp Vault (см. [Управление секретами](https://llmdocs.ru/wiki/secrets-management.md)).

## Сравнение с GitHub Actions

| | GitLab CI | [GitHub Actions](https://llmdocs.ru/wiki/github-actions.md) |
|---|---|---|
| Файл | один `.gitlab-ci.yml` (+ include) | много файлов в `.github/workflows/` |
| Модель | стадии + DAG через `needs` | задания + `needs` |
| Переиспользование | шаблоны, `extends`, компоненты | действия из Marketplace, reusable workflows |
| Свой сервер | полноценный self-managed GitLab | GitHub Enterprise Server |
| Сильная сторона | всё в одной платформе, свои раннеры | огромный каталог готовых действий |

## Отладка

Конвейер можно проверить в редакторе пайплайнов GitLab (валидация и просмотр итоговой конфигурации). Упавшее задание перезапускают из интерфейса, а для долгих проблем включают `CI_DEBUG_TRACE: "true"` — с осторожностью, поскольку в журнал попадут значения переменных.

## См. также

- [CI/CD](https://llmdocs.ru/wiki/ci-cd.md)
- [Pull request / Merge request](https://llmdocs.ru/wiki/pull-request.md)
- [Container registry](https://llmdocs.ru/wiki/container-registry.md)
- [Infrastructure as Code](https://llmdocs.ru/wiki/infrastructure-as-code.md)

## Источники

1. [GitLab Docs — Get started with GitLab CI/CD](https://docs.gitlab.com/ci/)
2. [GitLab Docs — CI/CD YAML syntax reference](https://docs.gitlab.com/ci/yaml/)
3. [GitLab Docs — GitLab Runner](https://docs.gitlab.com/runner/)
4. [GitLab Docs — Predefined CI/CD variables](https://docs.gitlab.com/ci/variables/predefined_variables/)
5. [GitLab Docs — Environments and deployments](https://docs.gitlab.com/ci/environments/)
6. [GitLab Blog — GitLab 8.0 released with integrated CI (2015)](https://about.gitlab.com/releases/2015/09/22/gitlab-8-0-released/)