Автоматическая сборка и публикация Docker‑образов в GitHub Container Registry

Быстрые ссылки

• GitHub Container Registry

• Как настроить автоматическую сборку в GitHub Packages

GitHub Actions позволяет автоматически запускать сборки, тесты и скрипты при изменениях в репозитории. Одно из практичных применений — автоматически собирать Docker‑контейнеры и публиковать их в реестр образов.

GitHub Container Registry

GitHub Container Registry (GHCR) — это расширение GitHub Packages с совместимостью для Docker‑команд. По сути, GHCR делает GitHub Packages пригодным для операций с контейнерами, таких как:

docker pull

и другие CLI‑команды Docker.

Важно: вам не обязательно публиковать образы в GHCR — вы по‑прежнему можете пушить их в Docker Hub из workflow. Однако предустановленные действия GitHub (actions) обычно работают сразу с GHCR, поэтому настройка проще.

Как настроить автоматическую сборку и публикацию в GitHub Packages

Чтобы начать, нужен репозиторий. Даже если вы публикуете только пакеты, GHCR привязывает пакеты к репозиторию, поэтому репозиторий обязателен. Формат имени образа в GHCR выглядит так:

ghcr.io/username/repository/image:version

1. Создайте репозиторий.
2. Откройте вкладку Actions и выберите создание нового workflow. В разделе More Continuous Integration Workflows нажмите Publish Docker Container.

Шаблон создаёт стартовый файл workflow, который требует небольших правок:

• Измените переменную IMAGE_NAME на имя вашего образа.

• На строке, где происходит логин в GHCR, вы увидите:

run: echo "${{ secrets.CR_PAT }}" | docker login https://ghcr.io -u ${{ github.actor }} --password-stdin

В настоящий момент поддерживаемая схема аутентификации — Personal Access Token (PAT). PAT выдаёт права на уровне аккаунта, поэтому хранить его в открытом виде нельзя. Рекомендуемый подход — создать PAT с нужными правами и сохранить его в секретах репозитория.

Пошагово:

1. Откройте Settings > Developer Settings > Personal Access Tokens и создайте новый токен.
2. Выберите scope write:packages и delete:packages. Обратите внимание: при выборе write:packages GitHub может автоматически отметить Full Control Of Repositories — снимите эту галочку, если она не нужна.

3. Перейдите в настройки репозитория (Settings > Secrets) и создайте секрет с именем CR_PAT, содержащий значение созданного PAT.

4. Вернитесь к workflow и сохраните изменения. Нажмите Start Commit, чтобы добавить файл в репозиторий.

После коммита workflow запустится автоматически. Статус всех workflow можно отслеживать на вкладке Actions. Если workflow упал, откройте лог выполнения — обычно видно, какая команда вернула ошибку.

Типичная причина падения в шаблоне — ожидание запуска тестов, которых нет в образе. В этом случае можно удалить или изменить соответствующий шаг в workflow.

После успешной сборки образ будет виден в реестре пакетов: на странице репозитория в разделе Packages или на странице пакетов вашего профиля.

Критерии приёмки

• Workflow выполняется успешно (статус success).
• Образ доступен по имени ghcr.io/username/repository/image:version.
• При pull образ воспроизводится локально без ошибок.
• Права доступа пакета соответствуют требованиям (частный/публичный).

Чек‑лист для быстрой настройки (DevOps / Разработчик)

• Создан репозиторий и Dockerfile в корне или в нужной директории.
• Создан workflow с шагами build, tag, push.
• Указано корректное IMAGE_NAME и версия (tag).
• Создан PAT с write:packages и delete:packages.
• PAT сохранён в Settings > Secrets как CR_PAT.
• Запущен commit и проверен статус workflow на вкладке Actions.
• Образ проверен командой docker pull.

Короткая методология настройки

1. Описать образ: Dockerfile, теги, зависимости.
2. Создать workflow: сборка, тесты, тегирование, логин, push.
3. Настроить секреты: CR_PAT в репозитории.
4. Автоматизировать версионирование образов (например, по тегу git или семантическому versioning).
5. Внедрить проверки безопасности образов и сканирование уязвимостей.

Когда этот подход не подходит

• Вам нужны тонкие политики доступа на уровне образов, которые проще реализовать в отдельном регистре (в зависимости от требований организации).
• Требуется централизованное управление образами нескольких провайдеров через CI/CD: возможно лучше использовать отдельно Docker Hub или частный реестр с интеграциями.
• Запрещено хранение PAT в GitHub Secrets по политике безопасности организации.

Альтернативы

• Docker Hub: простая публикация через docker push и Docker Hub Actions.
• GitLab Container Registry: если вы используете GitLab CI/CD.
• Частный реестр (Harbor, Artifactory): если нужны гибкие политики и аудит.

Рекомендации по безопасности

• Минимизируйте scope PAT — выдавайте только write:packages и delete:packages, если достаточно.
• Ротация токенов: периодически пересоздавайте PAT и обновляйте секреты.
• Используйте organisation‑level или repository‑scoped tokens, если доступен более ограниченный способ.
• В workflow избегайте вывода секретов в логи.

Важно: храните секреты только в GitHub Secrets и не добавляйте токены в код или CI‑логи.

Отладка и типичные ошибки

• Ошибка авторизации при docker login: проверьте, верно ли сохранён CR_PAT и не истёк ли PAT.
• Ошибка отсутствия образа после успешной сборки: проверьте тег и имя (ghcr.io/username/repository/image:tag).
• Падение из‑за тестов: либо добавьте тесты, либо удалите/измени́те соответствующий шаг из шаблона workflow.

Плейбук: быстрый рабочий план для команды

1. Создать/обновить Dockerfile и локально проверить сборку.
2. Добавить workflow Publish Docker Container, изменить IMAGE_NAME.
3. Создать PAT с write:packages и delete:packages.
4. Добавить секрет CR_PAT в настройки репозитория.
5. Сделать commit — дождаться выполнения workflow.
6. Проверить pull‑операцию и пометить релиз.
7. Настроить мониторинг и уведомления на случай неудачных сборок.

Decision tree (выбор реестра)

flowchart TD
  A[Нужно связать образы с репозиторием?] -->|Да| B[Использовать GHCR]
  A -->|Нет| C[Нужны централизованные политики?]
  C -->|Да| D[Выбрать частный реестр 'Harbor/Artifactory']
  C -->|Нет| E[Docker Hub или другой публичный реестр]

Краткий глоссарий

• GHCR: GitHub Container Registry — реестр для контейнеров, интегрированный с GitHub Packages.
• PAT: Personal Access Token — персональный токен доступа для API и CLI.
• CR_PAT: рекомендованное имя секрета в репозитории, содержащего PAT для GHCR.

Резюме

• GHCR интегрирован с GitHub Actions и облегчает автоматическую публикацию Docker‑образов.
• Обязательно создайте PAT и сохраните его в секрете CR_PAT в настройках репозитория.
• Проверяйте логи Actions при ошибках и используйте чек‑листы для стандартной настройки.

Важное замечание: если у вашей организации есть ограничения по PAT, согласуйте процедуру с командой безопасности перед публикацией.