flowforge

---

NOTICE Репозиторий архивирован из-за переноса основной разработки в cloud/flowforge

---

Сборщик OCI-образов, который использует altflow/altflow как backend, а repoteka в качестве инструмента проверки обновлений бинарных пакетов. Концепция работы altflow описана в документации altflow.

Проект во многом вдохновлён cloud/image-forge. Цели:

• автоматизировать процесс сборки OCI-образов для целевого Registry;
• дать широкому кругу контрибьютеров понятный алгоритм, чтобы они могли участвовать в добавлении новых восстребованных образов в автоматизированный пайплайн flowforge.

Полная документация проекта flowforge

Периодическая пересборка образов

Flowforge CI с заданной периодичностью сравнивает зафиксированные в репозитории версии бинарных пакетов с актуальной информацией от repoteka.mskdc.altlinux.org. Образы, бинарные пакеты которых обнововились, отправляются на пересборку. Образы, чьи source-образы обновились, также отправляются на пересборку.

Состояние последних успешно обработанных сборок хранится в ветках *-artefacts. Там же хранится служебное состояние пересборок, вызванных обновлением source-образов. Подробнее об этом написано в org/README.md.

Участие в добавлении новых образов в flowforge

Вы имеете право предложить новые образы в автоматизированный пайплайн flowforge. В первую очередь заведите новую задачу в Issues (Задачах) репозитория с обоснованием необходимости добавления новых образов. После появления задачи либо один из контрибьютеров flowforge может согласиться её выполнить, либо вы можете выполнить задачу самостоятельно. В последнем случае следуйте инструкции:

1. Сделайте форк текущего репозитория.
2. Дополните одну или несколько организаций каталога org/ спецификациями новых образов, которые вы предлагаете добавить. Спецификация образа содержит:

• Dockerfile.template
• altflow-test
• info.yaml *
• README.md (желательно)

3. Сделайте Pull Request (PR) в ветку main данного основного репозитория.
4. Дождитесь выполнения тестов. На этом этапе flowforge запустит тестовую сборку образов по вашим спецификациям. Если тестовая сборка завершится красными индикаторами, изучите логи сборки в PR и поправьте ошибки в файлах спецификации.
5. Когда PR успешно прошёл полный prepare-deploy цикл подключаются администраторы репозитория. Поправьте ваши коммиты по их замечаниям.
6. При выполнении всех условий администратор отправляет ваши коммиты в ветку main.
7. CI flowforge автоматически запустит сборку образов и отправит их в целевой Registry.

Примечание: Рекомендуем изучить корректное заполнении info.yaml и правила создания distroless-образов на базе flowforge в полной документации проекта.

Поддержка архитектур

В настоящее время поддерживаются следующие архитектуры: x86_64, aarch64, i586, loongarch64, riscv64

Данное ограничение связано с возможностями сборочницы OCI-образов altflow.

Локальная разработка

Основные положения

PR с функциональными изменениями скорее всего не будут приняты. Исключения возможны.

• Если есть предложение по улучшению, создайте Issue и опишите его.
• Если есть багрепорт, создайте Issue с описанием проблемы. Будет полезно, если вы опишете способ воспроизведения.
• [В БУДУЩЕМ] Если PR не выглядит poorly vibecoded, изменения с использованием AI могут быть приняты. AI можно использовать для PR, но будьте готовы обсуждать и защищать каждое предложенное изменение.

Ожидаемые рабочие конфигурации

Организации: alt, base, k8s-core, k8s-extra, kubevirt
Архитектуры: amd64, arm64
Ветки: sisyphus

Зависимости

• python3-module-aiohttp
• python3-module-pydantic
• python3-module-pydantic-settings
• python3-module-loguru
• python3-module-jinja2
• python3-module-yaml

Использование

Переменные среды, которые использует скрипт:

• DRY -> включает dry-run режим
• TEST -> отправляет задания в altflow без тегов. Финальный push в registry становится фиктивным
• EMAIL_NOTIFICATION -> включает email-уведомления об ошибках сборки
• EMAIL_TO -> список получателей email-уведомлений. Можно перечислять через запятую или пробел
• LOG_LEVEL -> уровень логирования
• ALTFLOW_URL -> URL экземпляра altflow
• ALTFLOW_AUTH -> токен авторизации для altflow
• SOT_REPO -> Source Of Truth репозиторий. Из этого репозитория altflow забирает спецификацию образа
• SOT_BRANCH -> Source Of Truth ветка. В неё рендерятся Dockerfile перед тем, как altflow их прочитает
• SOT_FORCE_PUSH -> разрешает force push в SOT_BRANCH
• REGISTRY_URL -> адрес целевого registry
• REGISTRY_AUTH -> авторизация для REGISTRY_URL
• SOURCE_REGISTRY -> registry, из которого берутся базовые образы
• REPOTEKA_URL -> URL экземпляра repoteka
• REPOTEKA_COMPONENT -> компонент repoteka
• REPOTEKA_SSL_VERIFY -> включает SSL verify для запросов в repoteka
• REPOTEKA_CONCURRENCY -> максимальное количество одновременных запросов к repoteka
• SMTP_SERVER -> SMTP-сервер для email-уведомлений
• SMTP_PORT -> SMTP-порт для email-уведомлений
• SMTP_FROM -> адрес отправителя email-уведомлений
• SMTP_USERNAME -> SMTP-пользователь для email-уведомлений
• SMTP_PASSWORD -> SMTP-пароль для email-уведомлений
• SMTP_SSL -> включает implicit TLS для SMTP. Для порта 465 включается автоматически

Подробнее в config.py

Доступные CLI-аргументы:

$ ./flowforge.py --help

Или можно посмотреть их в flowforge.py

Собрать один образ:

$ ./flowforge.py -i alt/redis

Собрать группу образов организации:

$ ./flowforge.py -o alt

Принудительно пересобрать образ, даже если сохранённые артефакты показывают, что он актуален:

$ ./flowforge.py -f -i alt/redis

Флаг -f не делает reset ветки *-artefacts, но весь выбранный набор образов проходит обычный цикл сборки с учётом уровней source_images. Dockerfile.<branch> заново рендерится и пушится в SOT_BRANCH, а после успешной сборки обновляется соответствующий info.*.yaml. Если в выбранном наборе есть source-образы и зависимые от них образы, artefacts-состояние обновится для обеих групп.

Отправить тестовую сборку без публикации тегов в registry:

$ TEST=1 ./flowforge.py -i alt/redis

Все примеры предполагают, что нужные переменные среды уже экспортированы.

Source Of Truth ветка

flowforge не отправляет локальное содержимое Dockerfile напрямую в altflow. Он рендерит Dockerfile.<branch> в SOT_BRANCH, пушит эту ветку, а затем отправляет в altflow SOT_REPO, SOT_BRANCH и путь к Dockerfile.

Если SOT_BRANCH не задана, она вычисляется как <current-branch>-artefacts.

Подробнее о роли *-artefacts, info.*.yaml и PR-веток ci/pr-<number>-artefacts написано в org/README.md.

CI secrets

CI jobs используют secret FLOWFORGE_CI_TOKEN, чтобы пушить PR artefacts-ветки в altlinux.space. Токену нужны права repository read/write. Для cron rebuild используется FORGEJO_AUTH. Доступ к registry передаётся отдельно через REGISTRY_AUTH.

Если включены email-уведомления, SMTP может работать в трёх режимах:

• plain SMTP без STARTTLS;
• SMTP с STARTTLS, если сервер объявляет такую возможность;
• implicit TLS через SMTP_SSL=1 или порт 465.

Если EMAIL_TO не задан, уведомления никому не отправляются. Если SMTP_FROM не задан, используется SMTP_USERNAME; если не задано и оно, email-уведомления отключаются.