CI/CD-пайплайн для Docker: сборка образа, кэш слоёв, теги и публикация в registry | AdminWiki

CI/CD-пайплайн для Docker: сборка образа, кэш слоёв, теги и публикация в registry

20 ноября 2026 13 мин. чтения
Содержание статьи

Что должно быть в пайплайне Docker: пять шагов и точка контроля

Пайплайн для Docker-образа решает пять задач в жёстком порядке: собрать образ из Dockerfile, переиспользовать слои прошлых сборок, присвоить теги, привязанные к коммиту, отправить образ в registry и подтвердить, что он там есть и запускается. Пятый шаг пропускают чаще всего, и именно он отличает зелёную джобу от рабочего артефакта: код возврата 0 сообщает только о том, что команда завершилась без ошибки.

Два ограничения задают рамки любого примера ниже. Синтаксис шагов определяет CI-инструмент: команда docker build в GitLab CI и GitHub Actions оформлена по-разному, поэтому даём фрагменты для обоих. Поведение кэша, поддерживаемые флаги и обработка тегов зависят от версии Docker и драйвера BuildKit, поэтому версии фиксируем в самом пайплайне и печатаем в лог.

Официальный маршрут обучения Docker выстраивает ту же последовательность: Dockerfile для реального приложения, быстрая сборка, компактный образ, публикация в Docker Hub (docs.docker.com/learn/paths). Разница в акцентах: в CI важна воспроизводимость, а не разовый успешный результат на рабочей машине.

Схема, к которой возвращаемся при настройке:

  1. Зафиксировать версии: образ docker:27-cli вместо плавающего docker:cli, вывод docker version и docker buildx version первой командой джобы.
  2. Авторизоваться в registry: docker login с токеном из переменных CI.
  3. Собрать образ с внешним кэшем и OCI-метками, где указан commit SHA.
  4. Проставить теги: неизменяемый тег по SHA, релизный semver, latest только на релизной сборке.
  5. Опубликовать и проверить: docker push, docker manifest inspect, smoke-запуск.

Чек-лист перед публикацией, по которому удобно проверять любую правку пайплайна:

  • тег образа содержит commit SHA, и метка revision совпадает с коммитом;
  • секретов нет ни в контексте сборки, ни в слоях образа;
  • базовый образ зафиксирован по тегу или digest, а не взят как latest;
  • пуш подтверждён не только кодом возврата, но и digest из registry.

Какие версии Docker и CI фиксируем в примерах

BuildKit работает как сборщик по умолчанию в Docker 23.0 и новее, а docker buildx поставляется отдельным плагином docker-buildx-plugin. Примеры ниже рассчитаны на Docker Engine 24 и новее. Если ваш CI-образ тянет docker:cli без тега, вы получаете плавающую версию: одна и та же джоба через месяц может вести себя иначе. Укажите конкретный тег вида docker:27-cli, подставив мажорную версию, которую используете в проде.

Версию печатаем в лог до сборки, чтобы при разборе ошибки не гадать об окружении:

docker version
docker buildx version
docker info

docker version показывает клиент и сервер отдельно, docker info добавляет драйвер сборщика и хранилище. Если версия Docker в CI отличается от локальной, поведение кэша и набор доступных флагов могут расходиться: проверяйте на своей версии, а не на версии из статьи.

Сборка образа в CI: Dockerfile, контекст и шаги для GitLab CI и GitHub Actions

Для CI важна структура Dockerfile, а не только его содержимое. Multi-stage отделяет установку зависимостей от рантайма: в финальный образ попадают рабочие файлы и прод-зависимости, без компилятора и dev-пакетов. Шаблон продакшн-сборки с порядком слоёв под кэш, non-root и HEALTHCHECK разбираем отдельно (Dockerfile для продакшна). Пример для приложения на Node.js:

# syntax=docker/dockerfile:1
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:22-alpine AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY package.json ./
COPY src ./src
USER node
EXPOSE 3000
CMD ["node", "src/server.js"]

Что даёт такая схема: слой npm ci пересобирается только при изменении package.json или package-lock.json, копирование исходников идёт после установки пакетов и не сбрасывает её. USER node переключает процесс на непривилегированного пользователя. Если у приложения есть шаг компиляции, добавьте стадию builder с полными зависимостями и копируйте в runtime только собранный артефакт.

GitLab CI: сборка в контейнере docker:27-cli, демон docker:dind как service, учётные данные из предопределённых переменных CI_REGISTRY, CI_REGISTRY_USER, CI_REGISTRY_PASSWORD, CI_REGISTRY_IMAGE, CI_COMMIT_SHA. Для dind нужен runner с privileged = true или смонтированный docker socket, иначе docker build внутри джобы не увидит демон.

build:
  stage: build
  image: docker:27-cli
  services:
    - docker:dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker version
    - docker buildx version
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
    - docker buildx create --driver docker-container --name ci --use
  script:
    - >
      docker buildx build
      --push
      --tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
      --label org.opencontainers.image.revision=$CI_COMMIT_SHA
      --cache-from type=registry,ref=$CI_REGISTRY_IMAGE:buildcache
      --cache-to type=registry,ref=$CI_REGISTRY_IMAGE:buildcache,mode=max
      .

Драйвер docker-container нужен для экспорта кэша в registry: встроенный драйвер docker не поддерживает --cache-to type=registry. На постоянном self-hosted раннере билдер создают один раз, иначе команда падает на существующем имени, поэтому либо убирайте docker buildx create из каждой джобы, либо добавляйте проверку существования билдера. Если внешний кэш не нужен, удалите строки с cache-from и cache-to.

GitHub Actions: docker/build-push-action@v6 принимает tags, labels и параметры кэша, а кэш типа gha хранится в инфраструктуре Actions и переживает запуски. Токен ghcr.io берём из secrets.GITHUB_TOKEN с правом packages: write.

name: build-and-push
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - run: docker version && docker buildx version
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          labels: org.opencontainers.image.revision=${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Проверка результата сборки до пуша: docker image ls с ожидаемым тегом и размером, отсутствие ошибок в логе сборки. Разбор флагов docker build, включая -t, -f, --build-arg и --no-cache, есть в материале про команду docker build.

Что исключить из контекста сборки через .dockerignore

Контекст передаётся демону целиком, поэтому лишние файлы замедляют передачу и могут оказаться в слое. Минимальный набор исключений:

.git
.env
.env.*
node_modules
dist
coverage
*.log
.idea

Отдельно про .env: файл с секретами не должен ни уезжать в контекст, ни попадать в образ через COPY . . . Проверка: в выводе BuildKit строка transferring context показывает размер контекста, а docker history --no-trunc по собранному образу показывает команды слоёв. Файлов с токенами в истории быть не должно.

Почему сборка падает в CI и как это диагностировать

Смотрите первый упавший шаг, а не последний: остальные ошибки обычно следствие. Категории причин, которые закрывают почти все случаи:

  • нет доступа к registry базового образа: docker login нужен до сборки, если базовый образ приватный;
  • у runner нет прав: dind требует privileged, альтернатива - смонтированный docker socket;
  • неверный путь к Dockerfile или контексту: флаг -f и последний аргумент команды должны указывать на существующие файлы;
  • базовый образ с тегом, которого нет в registry, или снятый тег.

Порядок диагностики: выполните ту же команду docker build локально с тем же тегом и тем же контекстом, затем docker info в джобе, чтобы увидеть версию демона и драйвер сборщика. Тексты ошибок зависят от версии, ориентируйтесь на категорию, а не на формулировку.

Кэширование слоёв Docker: как порядок инструкций и внешний кэш ускоряют сборку

BuildKit переиспользует слой, пока не изменилась инструкция и входные файлы этой инструкции. Отсюда правило: редко меняющиеся шаги идут в Dockerfile раньше, часто меняющиеся позже. Антипример:

COPY . .
RUN npm ci --omit=dev

Здесь любая правка в исходниках сбрасывает кэш установки зависимостей, и повторная сборка идёт столько же, сколько первая. Исправленный порядок:

COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .

Кэш инвалидируется по содержимому файлов из COPY и по строке инструкции: правка package-lock.json пересобирает слой npm ci, правка src/* оставляет его нетронутым.

Локальный кэш помогает только при повторных сборках на той же машине. Эфемерный раннер (облачный CI, контейнер на один запуск) кэш теряет, и каждая сборка начинается с нуля. Внешний кэш решает это: buildx экспортирует кэш в registry или в кэш CI и импортирует его в следующей джобе.

docker buildx build \
  --tag "$REGISTRY/$IMAGE:$TAG" \
  --cache-from type=registry,ref=$REGISTRY/$IMAGE:buildcache \
  --cache-to type=registry,ref=$REGISTRY/$IMAGE:buildcache,mode=max \
  --push .

mode=max кэширует все стадии, включая промежуточные, mode=min только финальный образ. Для GitHub Actions те же параметры передаются строками cache-from: type=gha и cache-to: type=gha,mode=max. Для GitLab CI вариант с registry-кэшем не требует внешнего хранилища, но занимает место в registry.

Кэш в registry против кэша на runner

КритерийКэш на runnerКэш в registry или gha
Где живётлокальный диск раннераregistry проекта или кэш CI
Переживает пересоздание раннеранетда
Работает при нескольких раннерахнетда
Стоимостьдиск раннераместо в registry, нужен retention
Когда выбиратьодин постоянный self-hosted раннероблачный CI, несколько раннеров

Кэш в registry растёт, если его не чистить: задайте retention или отдельный тег с ограниченным сроком хранения, иначе через полгода кэш займёт больше места, чем сами образы.

Когда кэш мешает: устаревшие зависимости и инвалидация

Кэш подставит старые пакеты, если lock-файл не скопирован отдельным слоем: установщик видит прежний манифест и ставит версии из него. Лечится порядком инструкций, а не флагом --no-cache. Флаг полезен как диагностика: он показывает, воспроизводится ли проблема без кэша.

Проверка инвалидации: измените одну строку в package-lock.json и запустите сборку. В выводе BuildKit напротив слоя установки зависимостей не должно быть отметки CACHED, а неизменные слои остаются CACHED. Сравните лог первой и второй джобы: время повторной сборки должно быть заметно меньше.

Не отключайте проверку подписи пакетов ради скорости и не переходите со lock-файла на свободные диапазоны версий: это ломает воспроизводимость сильнее, чем любой кэш.

Стратегия тегирования: semver, commit SHA и почему latest публикуют не вслепую

Тег это единственная связь между артефактом в registry и кодом в git. Три рабочие схемы и их роли:

СхемаЧто даётГде применятьОграничение
commit SHAуникальный тег, ставится автоматически, указывает на конкретный коммитдеплой, откат, трассировканечитаем для человека
semver (1.4.2)читаемый релиз, ставится на аннотированный git-тегрелизы, коммуникация с заказчикомтребует дисциплины в git-тегах
latestплавающий указатель на последнюю сборкулокальный запуск, быстрый стартне даёт отката и не говорит о версии

Рекомендация: в деплой уходит SHA или semver, latest обновляется только на релизной сборке. Один образ получает несколько тегов, сборка при этом одна:

docker tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" "$CI_REGISTRY_IMAGE:1.4.2"
docker tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" "$CI_REGISTRY_IMAGE:latest"

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

Как связать тег образа с коммитом

SHA берётся из предопределённой переменной CI: CI_COMMIT_SHA в GitLab CI, github.sha в GitHub Actions. Значение попадает и в имя тега, и в OCI-метки, которые видны в registry:

docker buildx build \
  --tag "$REGISTRY/$IMAGE:$CI_COMMIT_SHA" \
  --label org.opencontainers.image.revision="$CI_COMMIT_SHA" \
  --label org.opencontainers.image.source="$CI_PROJECT_URL" \
  --label org.opencontainers.image.version="$CI_COMMIT_TAG" \
  --push .

CI_COMMIT_TAG заполняется только в пайплайне по git-тегу, в обычной сборке метка version останется пустой. Это нормально, ключевая метка здесь revision. Проверка двусторонней связи: метка в образе должна совпадать с HEAD коммитом.

docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$REGISTRY/$IMAGE:$TAG"
git log -1 --format=%H

Обе команды возвращают один и тот же хеш. Пустая метка означает, что сборка шла без label или тег проставлен вручную после пуша.

Как откатиться на предыдущий образ

Порядок без пересборки: возьмите из истории деплоя предыдущий рабочий тег, задеплойте его тем же способом, что и текущий, сверьте метку revision и выполните smoke-запуск. Latest для отката не подходит: неизвестно, какой коммит за ним стоит, а после следующего пуша указатель сдвинется. Если latest должен снова указывать на откатанную версию, перетегируйте осознанно, отдельным действием и с записью в журнале изменений.

Проверка после отката: docker inspect по образу и сверка revision с ожидаемым коммитом, затем запуск контейнера с healthcheck. Для критичных сервисов держите историю «тег образа - коммит - дата деплоя», иначе откат превращается в поиск по логам CI.

Публикация образа в registry: docker login, docker push и проверка результата

Публикация начинается с логина. Токен передаём через stdin, чтобы он не осел в истории команд и в логе:

echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"

Дальше push по каждому тегу. Путь образа зависит от registry: Docker Hub использует docker.io/<namespace>/<image>, GitLab Container Registry - registry.gitlab.com/<group>/<project>, GitHub Container Registry - ghcr.io/<owner>/<repo>. Синтаксис шагов задаёт CI-инструмент, сами команды docker login и docker push одинаковы.

for tag in "$CI_COMMIT_SHA" "$VERSION" latest; do
  docker push "$CI_REGISTRY_IMAGE:$tag"
done

Зелёная джоба означает только код возврата 0. Проверять нужно registry: образ мог не дойти из-за прав, квоты или неверного имени тега. Пошаговая процедура загрузки в публичный и приватный реестр с разбором вывода docker push есть в отдельном руководстве (добавление образа в registry).

Проверка, что образ в registry и корректен

  • docker manifest inspect "$REGISTRY/$IMAGE:$TAG": выводит манифест, слои и digest; ошибка об отсутствии манифеста означает, что тега в registry нет. В старых версиях CLI команда требовала включённых экспериментальных возможностей, там используйте docker buildx imagetools inspect.
  • docker pull "$REGISTRY/$IMAGE:$TAG" на чистой машине: подтверждает доступность и права; для приватного registry нужен docker login.
  • docker run --rm "$REGISTRY/$IMAGE:$TAG": smoke-запуск, ожидаемый вывод зависит от приложения или healthcheck.
  • docker inspect --format '{{.RepoDigests}}' "$REGISTRY/$IMAGE:$TAG": сверка digest с тем, что показал манифест.

manifest inspect обращается к registry напрямую и не трогает локальный кэш образов, pull скачивает слои. Для ответа на вопрос «образ доступен другим» нужен первый вариант, желательно с машины, где локальной копии нет.

Секреты в CI: как не закоммитить токен registry

  • токен только в masked и protected переменных GitLab CI или в GitHub Secrets, в конфиге пайплайна его нет;
  • не передавайте секреты через ARG: значения ARG видны в docker history;
  • приватные пакеты ставьте через BuildKit secrets, файл монтируется на один шаг и не остаётся в слое;
  • не печатайте .npmrc, .env и конфиги целиком в лог: маскирование скрывает известные значения, а не весь файл.
# в Dockerfile
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci --omit=dev

# команда сборки
docker buildx build --secret id=npmrc,src="$HOME/.npmrc" --tag "$IMAGE:$TAG" --push .

Проверка: docker history --no-trunc по образу не должен содержать значений токенов. Если секрет уже попал в коммит или в слой, отзовите его в registry и выпустите новый: удаление строки из репозитория утечку не отменяет.

Безопасность цепочки поставки: доверенный базовый образ, сканирование и подпись

Отправная точка безопасности цепочки поставки - доверенный базовый образ. Дальше нужно находить и исправлять то, что реально эксплуатируется, подписывать собранное и допускать в production только проверяемое (docs.docker.com/learn/paths). На практике это означает фиксированный тег или digest базового образа, регулярное обновление базы и политику допуска образа в прод.

Порядок шагов: сканер в пайплайне с падением джобы по порогу severity, исправление находок высокого приоритета, подпись образа после успешного пуша и проверка подписи на стороне деплоя. Конкретные инструменты и их флаги зависят от вашей политики: для сканирования достаточно понимать, что порог задаётся в конфиге пайплайна, а «ноль находок» в реальном проекте недостижим, и погоня за ним останавливает релизы.

Уровни разделяем честно: сборка и пуш это обязательный минимум, сканирование и подпись - следующий слой, который включают по требованиям безопасности. Готовые конфигурации для Jenkins, GitLab CI и GitHub Actions с проверкой уязвимостей разбираем в материале про интеграцию реестра с CI/CD.

Минимальный чек-лист перед публикацией

  • базовый образ зафиксирован по тегу или digest;
  • .dockerignore исключает .env, .git и node_modules;
  • секреты только в переменных CI или BuildKit secrets;
  • тег содержит commit SHA, метка revision совпадает с коммитом;
  • latest обновляется только на релизной сборке;
  • внешний кэш настроен, в логе повторной сборки есть CACHED;
  • после пуша выполнен docker manifest inspect и smoke-запуск;
  • сканирование и подпись включены, если этого требует политика.

Итог: порядок шагов пайплайна и что проверять после каждого

  1. Зафиксировать версии: docker version, docker buildx version. Проверка: в логе видны клиент, сервер и драйвер сборщика.
  2. Авторизоваться: docker login с токеном из переменных CI. Проверка: шаг завершается без ошибки авторизации, токен в логе замаскирован.
  3. Собрать с кэшем и метками: docker buildx build с --cache-from, --cache-to и --label. Проверка: docker image ls показывает ожидаемый тег, в повторной сборке есть CACHED.
  4. Проставить теги: SHA, semver, latest по правилу. Проверка: docker inspect возвращает revision, равный git log -1 --format=%H.
  5. Опубликовать: docker push по каждому тегу. Проверка: docker manifest inspect показывает манифест и digest.
  6. Проверить запуск: docker pull и docker run с healthcheck или коротким smoke-тестом. Проверка: приложение отвечает, контейнер не падает.
  7. Подключить сканирование и подпись, если требуются политикой. Проверка: джоба падает на находке выше порога, подпись проверяется при деплое.

Два ограничения остаются в силе при любом копировании примеров: синтаксис шагов задаёт ваш CI-инструмент, а поведение кэша и обработка тегов зависят от версии Docker и драйвера. Прогоняйте изменённый пайплайн на тестовой ветке и сравнивайте логи первой и второй сборки, прежде чем включать его для продакшена.

Поделиться: