Сборка и публикация Docker-образов через GitHub Actions

Короткий ответ

Рабочий пайплайн для Docker-образа в GitHub Actions состоит из четырёх готовых шагов:

1. docker/setup-buildx-action — включает BuildKit и buildx.
2. docker/login-action — вход в реестр (GHCR или Docker Hub).
3. docker/metadata-action — автоматически генерирует теги и labels.
4. docker/build-push-action — собирает и публикует образ, с кешем слоёв.

Писать shell-скрипты с docker build и docker push вручную не нужно: эти actions уже решают теги, кеш и мультиплатформенность.

Готовый workflow

name: docker

on:
  push:
    branches: [main]
    tags: ["v*"]

permissions:
  contents: read
  packages: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-qemu-action@v3
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=sha
            type=ref,event=branch
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
      - uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Что здесь важно

Реестр. Для GHCR достаточно встроенного GITHUB_TOKEN и права packages: write. Для Docker Hub создайте access token в настройках аккаунта, сохраните его в секретах репозитория и уберите registry из шага логина.

Теги. Metadata-action превращает события Git в теги образа:

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

Кеш слоёв. type=gha хранит кеш в GitHub Actions cache. mode=max кеширует и промежуточные слои multi-stage сборки, а не только финальные. Альтернатива — type=registry, когда кеш лежит отдельным тегом в реестре; это удобно, если кеш нужен и другим системам.

Мультиплатформенность. QEMU позволяет собрать образ для arm64 на обычном amd64-раннере. Это медленно: эмуляция тормозит компиляцию. Если сборка под ARM занимает слишком долго, используйте ARM-раннеры и объединяйте образы в manifest, либо кросс-компиляцию внутри Dockerfile.

Dockerfile, который хорошо кешируется

Кеш работает только тогда, когда слои стабильны:

• Сначала копируйте файлы зависимостей (package.json, go.mod, requirements.txt), устанавливайте зависимости, и только потом копируйте исходники.
• Используйте multi-stage build: сборка в одном stage, в финальный образ — только артефакты.
• Добавьте .dockerignore, чтобы node_modules, .git и локальные файлы не попадали в контекст и не ломали кеш.

Частые ошибки

• Публикация из pull request. PR из форков не имеют доступа к секретам. Для PR ставьте push: ${{ github.event_name != 'pull_request' }} — образ соберётся для проверки, но не отправится.
• Только тег latest. По нему невозможно понять, какая версия сейчас в проде, и сложно откатиться.
• Секреты в build args. Они остаются в истории образа. Для секретов на этапе сборки используйте secrets в build-push-action и RUN --mount=type=secret.
• Нет прав packages: write. Пуш в GHCR упадёт с ошибкой авторизации.

Подробности по параметрам — в документации Docker по GitHub Actions.