Як push і pull images на Docker Hub?

docs.questions.sections.docker~4 хв читання

Push і pull image на Docker Hub це базовий workflow для sharing'у image: тегуєш image зі своїм namespace, логінишся один раз, пушиш, потім тягнеш звідки завгодно.

Теорія

TL;DR

Чотири команди покривають 99 відсотків кейсів: docker login, docker tag, docker push, docker pull.
Формат імені image: <namespace>/<repo>:<tag>, де <namespace> це твій Docker Hub username або організація. Без префіксу означає «офіційний library namespace», туди ти запушити не можеш.
Автентифікація через personal access token (PAT), не пароль акаунту. PAT обмежують scope (read-only / read-write / read-write-delete) і чисто revoke'аються.
Credentials лежать у ~/.docker/config.json після docker login. На macOS / Windows за credential helper.
Публічні репо: необмежена кількість, безкоштовно. Приватні поза free tier потребують платний план. Анонімні pull rate-лімітовані (100 на 6 годин на IP); автентифіковані вищі.

Швидкий приклад

bash

# 1. Збираємо локальний image
$ docker build -t myapp:1.0 .

# 2. Тегуємо зі своїм Docker Hub namespace
$ docker tag myapp:1.0 youruser/myapp:1.0

# 3. Автентифікуємось (один раз, до logout)
$ docker login -u youruser
Password: ****            # сюди paste PAT, не пароль акаунту
Login Succeeded

# 4. Push
$ docker push youruser/myapp:1.0
The push refers to repository [docker.io/youruser/myapp]
adc4d6e8f1c2: Pushed
8a3f2d1c9b8e: Pushed
1.0: digest: sha256:9f8e7d6c... size: 1247

# З іншої машини
$ docker pull youruser/myapp:1.0

Ось повний цикл. Build, tag, login, push, потім pull з будь-якого хоста, де встановлений Docker.

Іменування і тегування image

Повна форма для Docker Hub: [docker.io/]<namespace>/<repo>:<tag>.

docker.io/ це неявний дефолтний registry. Майже ніколи не пишеш.
<namespace> = твій Docker Hub username або організація, до якої ти належиш.
<repo> = ім'я репозиторію. Створюється автоматично при першому push.
<tag> = мітка цього білду (v1.0, 2026-04-30, pr-1247, latest). Дефолт latest, якщо не вказати.

Приклади:

bash

youruser/myapp:1.0          # особистий namespace, version tag
mycompany/api:2026-04-30    # org namespace, date tag
mycompany/api               # неявно :latest, уникай для проду
nginx:1.27                  # офіційний library/nginx, library/ неявний

Команда docker tag не рухає байти; вона лише додає ім'я, що вказує на той самий image ID. Один image може мати багато tag.

Автентифікація: PAT, не пароль

Docker Hub підтримує два способи логіну:

bash

# Старий спосіб, пароль акаунту (працює, але погана практика)
$ docker login -u youruser
Password: <пароль акаунту>

# Сучасний спосіб, personal access token
$ docker login -u youruser
Password: <paste PAT з https://hub.docker.com/settings/security>

PAT дають тобі:

Scope токена (read-only / read-write / read-write-delete-public-repo).
Revoke без зміни паролю акаунту.
Використовувати кілька токенів на машину (CI runner, лептоп, сервер) і ротувати незалежно.

У CI токени тримають як repository secrets. Ніколи не комітимо токен у git, ніколи не вставляємо в Dockerfile.

Де лежать credentials

Після docker login credentials лягають у ~/.docker/config.json:

json

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "base64(username:PAT)"
    }
  }
}

На macOS і Windows Docker використовує OS keychain (credsStore: osxkeychain, desktop), файл лише вказує на keychain, не на сирий токен. Linux без credential helper зберігає base64-токен прямо у файлі. chmod 600 ~/.docker/config.json, якщо так робиш.

Типові помилки

Push без префіксу namespace

bash

# НЕПРАВИЛЬНО: намагається запушити в офіційний library/
$ docker push myapp:1.0
requested access to the resource is denied

# ПРАВИЛЬНО: включай свій namespace
$ docker tag myapp:1.0 youruser/myapp:1.0
$ docker push youruser/myapp:1.0

Повідомлення про помилку безкорисне; причина завжди відсутній namespace.

Логін під паролем акаунту замість PAT

bash

$ docker login -u youruser
Password: <пароль акаунту>
Login Succeeded

Працює, але якщо твій пароль зливається, зловмисник отримує повний доступ до акаунту. PAT лімітує радіус ураження і revoke'ається окремо.

Запушити :latest і забути запушити версійний tag

bash

# НЕПРАВИЛЬНО: тільки :latest нагорі
$ docker tag myapp:1.0 youruser/myapp:latest
$ docker push youruser/myapp:latest

# ПРАВИЛЬНО: push обидва, щоб люди могли пінитися на конкретну версію
$ docker tag myapp:1.0 youruser/myapp:1.0
$ docker tag myapp:1.0 youruser/myapp:latest
$ docker push youruser/myapp:1.0
$ docker push youruser/myapp:latest
# Або одним махом: docker push --all-tags youruser/myapp

Якщо споживачі можуть тягти тільки :latest, вони не можуть пінитися на конкретну версію, і одного дня твій :latest їх здивує.

Натрапити на rate limit анонімного pull у CI

ERROR: toomanyrequests: You have reached your pull rate limit.

Docker Hub rate-лімітує анонімні IP до 100 pull на 6 годин, а спільний CI IP може спалити це швидко. Автентифікуй CI runner (docker login з токеном) або тягни через registry mirror (Google Artifact Registry, AWS ECR pull-through cache).

Реальне застосування

GitHub Actions: docker/login-action@v3 читає username + PAT з secrets, потім docker/build-push-action@v5 будує і пушить в одному кроці. Стандартний патерн у тисячах репо.
Локальний лептоп → спільне dev-середовище: запушив свій бранч-image у приватне репо Docker Hub, твій колега робить docker pull і запускає без rebuild.
Open-source дистрибуція: інструменти типу tini, dive і багато CLI публікують свої офіційні image на Docker Hub під verified-publisher namespace.
CI/CD пайплайни у менших командах: PR-білди, тегнуті як myapp:pr-1247, пушаться у приватне Docker Hub репо, staging-середовище їх тягне, інтеграційні тести бігають.

Питання для поглиблення

Q: Яка різниця між docker push і docker push --all-tags?

A: Звичайний docker push youruser/myapp:1.0 пушить один tag. docker push --all-tags youruser/myapp пушить кожен локальний tag того репозиторію. Корисно, коли ти позначив той самий image і версією, і latest.

Q: Як запушити приватний image?

A: Ті самі команди. Repo створюється при першому push; його visibility ставиш як private з web UI Docker Hub (або через API). Free акаунти Docker Hub включають одне приватне репо; більше потребує платного плану.

Q: Чи можна запушити image для кількох архітектур (amd64 + arm64)?

A: Так, через docker buildx. docker buildx build --platform linux/amd64,linux/arm64 -t youruser/myapp:1.0 --push . будує обидві архітектури і заливає їх як manifest list під одним tag. Споживачі автоматично тягнуть правильну для свого CPU.

Q: Як видалити image з Docker Hub?

A: Видалення tag з web UI або через curl проти Docker Hub API з PAT, що має delete scope. Немає docker delete-tag CLI. Видалення репозиторію теж тільки через web UI.

Q: (Senior) Як уникнути вшивання push-credentials у CI-логи і історію?

A: Використовуй офіційний login action (docker/login-action), що читає з masked secrets і ніколи їх не echo'їть. Для self-hosted CI передавай токен через --password-stdin: echo $DOCKER_TOKEN | docker login -u $DOCKER_USER --password-stdin. Ніколи не використовуй docker login -u user -p $TOKEN, це кладе токен у shell history і process listing (ps aux показав би його під час виклику).

Приклади

Push з GitHub Actions workflow

yaml

name: build-and-push
on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      - uses: docker/build-push-action@v5
        with:
          push: true
          tags: |
            youruser/myapp:latest
            youruser/myapp:${{ github.sha }}

Кожен push у main дає image, тегнутий latest і commit SHA. Прод-деплої пінься на SHA-tag для відтворюваності.

Rate limit'и pull у CI, фікс

bash

# Симптом: build job падає
ERROR: toomanyrequests: You have reached your pull rate limit.

# Фікс у твоєму CI: логінься перед будь-яким pull
- name: Docker login
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

- name: Build
  run: docker build -t myapp .

Автентифіковані pull мають значно вищий ліміт. Сам login-крок безкоштовний.

Push того самого image у два registry

bash

# Тегуємо раз, пушимо двічі, корисно для надлишковості або міграції
$ docker build -t myapp:1.0 .
$ docker tag myapp:1.0 youruser/myapp:1.0
$ docker tag myapp:1.0 ghcr.io/youruser/myapp:1.0

$ docker login docker.io
$ docker push youruser/myapp:1.0

$ docker login ghcr.io
$ docker push ghcr.io/youruser/myapp:1.0

Ті самі байти image, два registry, два namespaces. Споживачі тягнуть звідки хочуть.

Коротка відповідь

Для співбесіди

Premium

Коротка відповідь допоможе вам впевнено відповідати на цю тему під час співбесіди.

Коментарі

Ще немає коментарів