---

### 📝 **Описание пайплайна: Сборка и ретегирование Docker-образов с помощью Buildah**

Этот пайплайна предназначен для **безопасной, rootless-совместимой сборки, тегирования и публикации Docker-образов** в приватный реестр с использованием **Buildah** — инструмента для работы с образами без необходимости запуска Docker-демона.

Пайплайн поддерживает:
- Сборку образов из `Dockerfile`.
- Автоматическое тегирование по ветке или тегу.
- Публикацию в GitLab Container Registry.
- Ретегирование существующих образов (например, `latest`, `stable`).
- Работу в CI/CD без привилегированных прав (поддержка rootless-режима).

---

### 🧱 **Основные возможности**

| Функция | Описание |
|--------|--------|
| ✅ `buildah bud` | Сборка образа из `Dockerfile` с поддержкой аргументов и кэширования |
| ✅ `buildah push` | Загрузка образа в приватный реестр |
| ✅ Авто-тегирование | Образы тегируются по имени ветки (`develop`, `feature/*`) или по тегу (`v1.2.3`) |
| ✅ `latest` для `main`/`master` | При коммите в `main` или `master` — образ дополнительно помечается как `:latest` |
| ✅ Ретегирование | Перенос тегов между образами (например, `app:v1.5` → `app:prod`) |
| 🔐 Безопасный login | Использование `--password-stdin` + base64-декодирование пароля |

---

### 🛠️ **Используемые Buildah-шаблоны**

```yaml
.buildah_info: &buildah-info
  - until buildah --version; do sleep 1; done
```
> Проверяет доступность Buildah (полезно при старте контейнера).

```yaml
.buildah_login_stdin_base64: &buildah-login-stdin-base64
  - echo "$REGISTRY_PASSWORD" | base64 -d | buildah login -u $REGISTRY_USER $REGISTRY --password-stdin
```
> Безопасный вход в реестр: пароль в base64-кодировке, не попадает в логи напрямую.

```yaml
.buildah_build: &buildah-build
  - buildah bud $BUILD_STORAGE_DRIVER $BUILD_CACHE $BUILD_ARGS --isolation=$BUILDAH_ISOLATION -f $DOCKERFILE_PATH -t $DOCKER_TAG $CONTEXT_PATH
```
> Сборка образа с поддержкой:
> - кастомных `--build-arg`
> - отключения кэша (`--no-cache`)
> - выбора драйвера хранения (по умолчанию `vfs` — совместим с rootless)

```yaml
.buildah_push: &buildah-push
  - buildah images
  - buildah push $DOCKER_TAG
  - if [[ "${CI_COMMIT_REF_SLUG}" == "main" || ... ]]; then buildah tag ... :latest; fi
  - if [[ ... ]]; then buildah push ... :latest; fi
```
> Отправка образа в реестр и автоматическое обновление тега `:latest` на `main`/`master`.

```yaml
.buildah_retag: &buildah-retag
  - buildah pull $SOURCE_IMAGE
  - buildah tag $SOURCE_IMAGE $TARGET_IMAGE
  - buildah push $TARGET_IMAGE
```
> Ретегирование: скачивает существующий образ и выставляет новый тег (например, для релизов или продакшена).

```yaml
.buildah_logout: &buildah-logout
  - buildah logout $REGISTRY
```
> Очистка сессии после работы.

---

### 🏗️ **Стадии пайплайна**

#### 1. `build` — Сборка и публикация образа
- **Образ CI**: `sed-docker.artifacts.tn.tngrp.ru/buildah:v1.39.3-ca`
- **Переменные по умолчанию**:
  - `CONTEXT_PATH`: корень проекта
  - `DOCKERFILE_PATH`: `Dockerfile` в корне
  - `DOCKER_TAG`: `$CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG` (например, `image:develop`)
- **Тегирование по тегу релиза**:
  ```bash
  Если CI_COMMIT_TAG = v1.2.3 → образ: image:v1.2.3
  Иначе → image:feature-login
  ```
- **Автоматическое обновление `:latest`** при коммите в `main`/`master`.

#### 2. `retag` — Ретегирование существующего образа
- Используется для:
  - Продвижения образа (например, `app:v1.5` → `app:prod`)
  - Установки `:stable`, `:canary`, `:rollback` и т.п.
- Требует ручного запуска и указания:
  - `SOURCE_IMAGE` — исходный образ (например, `registry/app:v1.5`)
  - `TARGET_IMAGE` — целевой тег (например, `registry/app:prod`)

---

### ⚙️ **Ключевые переменные**

| Переменная | Описание |
|----------|--------|
| `CI_REGISTRY` / `CI_REGISTRY_USER` / `CI_REGISTRY_PASSWORD` | Данные для доступа к GitLab Registry (автоматически заданы в CI) |
| `CI_REGISTRY_IMAGE` | Полный путь к образу (например, `registry.example.com/group/app`) |
| `CI_COMMIT_REF_SLUG` | Имя ветки в URL-безопасном формате |
| `CI_COMMIT_TAG` | Тег коммита (если запущено по тегу) |
| `BUILD_ARGS` | Дополнительные аргументы сборки (через `--build-arg`) |
| `BUILD_CACHE` | Кэширование слоёв (`--no-cache` по умолчанию) |
| `BUILDAH_ISOLATION` | Режим изоляции: `chroot` (подходит для rootless) |
| `BUILD_STORAGE_DRIVER` | Драйвер хранения: `vfs` — рекомендуется для rootless |

---

### 🔐 **Безопасность**
- Пароль реестра **не передаётся в открытом виде** — используется `echo "$REGISTRY_PASSWORD" | base64 -d | buildah login --password-stdin`.
- Поддержка **rootless-режима** через `vfs` и `chroot`.
- Все операции выполняются в изолированном CI-раннере.

---

### 🧪 **Примеры использования**

#### ✅ Сборка при пуше в ветку `develop`
```bash
# Образ: registry/app:develop
# Сборка с --no-cache
# Без тега latest
```

#### ✅ Сборка при теге `v2.1.0`
```bash
# Образ: registry/app:v2.1.0
# Не влияет на latest
```

#### ✅ Сборка в `main` → обновление `:latest`
```bash
# Образ: registry/app:main + registry/app:latest
```

#### ✅ Ретегирование (ручной запуск)
```yaml
variables:
  SOURCE_IMAGE: registry/app:v2.1.0
  TARGET_IMAGE: registry/app:prod
```
> Результат: `registry/app:prod` указывает на тот же слой, что и `v2.1.0`.

---

### 📌 **Требования**
- GitLab CI с доступом к `buildah`-образу.
- Настроенные права на запись в Container Registry.
- Для `retag` — образ должен уже существовать в реестре.
- Раннер должен поддерживать выполнение `buildah` (обычно на хосте с `fuse-overlayfs` или `vfs`).

---

### 📎 Рекомендации
- Используйте `BUILD_CACHE: ""` для включения кэширования в промышленных сборках.
- Храните кастомные `BUILD_ARGS` в переменных CI.
- Для продакшена используйте `retag` вместо пересборки.

---

✅ **Назначение**: Современная, безопасная и гибкая альтернатива Docker-in-Docker (DinD) для сборки образов в CI/CD.  
🔧 Подходит для GitLab CI, Kubernetes-раннеров, rootless-окружений и air-gapped систем.

---

Вы можете вставить это описание в начало `.gitlab-ci.yml`:

```yaml
# .gitlab-ci.yml
#
# === ПАЙПЛАЙН: Сборка образов через Buildah ===
#
# Описание:
#   Данный пайплайн использует Buildah для rootless-сборки и публикации...
#
# ...
```

Или сохранить как `docs/ci-buildah-pipeline.md`.