From b21a7aa8405e69a676cb48760c53036b097673e2 Mon Sep 17 00:00:00 2001
From: Ha1zyy <yarcool2000@gmail.com>
Date: Sun, 7 Jun 2026 12:18:22 +0500
Subject: [PATCH] docs(ci): document docker build timeout

---
 docs/operations/README.md           |  1 +
 docs/operations/ci-docker-builds.md | 38 +++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 docs/operations/ci-docker-builds.md

diff --git a/docs/operations/README.md b/docs/operations/README.md
index 4c82c99..496b583 100644
--- a/docs/operations/README.md
+++ b/docs/operations/README.md
@@ -10,6 +10,7 @@ Runbook — это инструкция на плохой день.
 - redis-outage.md — Redis недоступен.
 - db-restore.md — восстановление базы.
 - dlq-replay.md — replay сообщения из DLQ.
+- ci-docker-builds.md — сбои Docker builds в CI.
 - failed-deploy-rollback.md — откат сломанного deploy.
 - failure-scenarios.md — список типовых отказов.
 - SLO.md — цели надежности.
diff --git a/docs/operations/ci-docker-builds.md b/docs/operations/ci-docker-builds.md
new file mode 100644
index 0000000..cbb08e7
--- /dev/null
+++ b/docs/operations/ci-docker-builds.md
@@ -0,0 +1,38 @@
+CI Docker builds
+
+Этот runbook нужен, когда падает job `Docker builds` в GitHub Actions.
+
+## Сбой payment-service, run 27071836521
+
+Root cause: `payment-service` не дошел до сборки сервиса. Docker упал на шаге
+`load metadata for docker.io/library/node:22-alpine` из-за timeout до Docker Hub:
+
+```text
+failed to resolve source metadata for docker.io/library/node:22-alpine
+dial tcp registry-1.docker.io:443: i/o timeout
+```
+
+Это не payment-service-specific ошибка в коде, Dockerfile или build context.
+Все сервисы используют общий `apps/bot/Dockerfile.service`, но matrix jobs
+резолвят base image независимо. В этом run один runner поймал transient
+network/registry timeout, а остальные сервисные сборки прошли.
+
+## Проверка
+
+1. Открыть failing job log и найти первое `ERROR`.
+2. Если ошибка на `node:22-alpine` или `registry-1.docker.io`, считать это
+   registry/network failure до анализа кода сервиса.
+3. Сравнить соседние matrix jobs. Если другие сервисы с тем же Dockerfile
+   проходят, проблема не в `SERVICE_NAME`.
+4. Проверить локальную сборку:
+
+```sh
+docker build apps/bot --file apps/bot/Dockerfile.service --build-arg SERVICE_NAME=payment-service
+```
+
+## Mitigation
+
+- Re-run failed job, если это разовый timeout Docker Hub.
+- CI должен повторять `docker build` несколько раз перед hard failure.
+- Если timeout повторяется часто, добавить authenticated Docker Hub pull или
+  registry mirror/cache для base image.