DndGamePlayer/docs/MANUAL_MAC_UPDATE_UPLOAD.md

Ручная выкладка macOS-обновлений в публичный feed

Инструкция для случая, когда сборка делается на вашем Mac вручную, а файлы для electron-updater нужно вручную положить в публичный репозиторий обновлений.

Общая схема проекта: приватный репозиторий с кодом, публичный DndGamePlayerUpdates, ветка updates, URL feed как в package.json:

https://git.mailib.ru/ifontosh/DndGamePlayerUpdates/raw/branch/updates/

---

1. Что собрать на Mac

В каталоге проекта dnd_player:

cd /путь/к/dnd_player
npm ci
npm run build

Сборка установщиков только под macOS (без публикации в сеть, только файлы в release/):

npx electron-builder --mac --publish never \
  --config.publish.provider=generic \
  --config.publish.url="https://git.mailib.ru/ifontosh/DndGamePlayerUpdates/raw/branch/updates/"

Важно: значение --config.publish.url=... должно совпадать с package.json → build.publish.url (со слэшем в конце). Так внутри приложения и в latest-mac.yml будет корректный базовый URL для скачивания.

После сборки откройте папку release/ в корне проекта. Там должны быть, среди прочего:

• latest-mac.yml — обязателен для electron-updater на Mac;
• .dmg и/или .zip — то, на что ссылается latest-mac.yml;
• при необходимости .blockmap (если electron-builder их создал) — заливайте с теми же именами, что указаны в latest-mac.yml.

Имена файлов зависят от версии и архитектур (в конфиге dmg и zip для x64 и arm64). На Apple Silicon без дополнительных шагов часто получается только arm64; для отдельного Intel-сборщика нужна своя машина или параметры arch — ориентируйтесь на фактический список файлов в release/.

---

2. Куда заливать

Файлы должны оказаться в публичном репозитории:

Параметр	Значение
Репозиторий	ifontosh/DndGamePlayerUpdates (подставьте свой owner/repo, если другой)
Ветка	updates
Расположение	корень ветки (не подпапка)

Проверка: в браузере должен открываться, например:

https://git.mailib.ru/ifontosh/DndGamePlayerUpdates/raw/branch/updates/latest-mac.yml

Файлы Windows (latest.yml, .exe, …), которые кладёт CI, должны остаться в том же корне. Вы добавляете или обновляете только macOS-артефакты и latest-mac.yml, не удаляя артефакты Windows (если не делаете осознанную зачистку старых версий).

---

3. Способ A — через git (удобно для больших dmg)

3.1. Клон и ветка updates

cd ~/где-удобно
git clone https://git.mailib.ru/ifontosh/DndGamePlayerUpdates.git
cd DndGamePlayerUpdates
git fetch origin
git checkout updates

Если ветки updates ещё нет:

git checkout main
git pull
git checkout -b updates
git push -u origin updates

Дальше для каждой выкладки работайте в ветке updates.

3.2. Актуализировать локальную копию

git checkout updates
git pull origin updates

3.3. Скопировать файлы из release/ в корень клона

cp /путь/к/dnd_player/release/latest-mac.yml .
cp /путь/к/dnd_player/release/*.dmg .
cp /путь/к/dnd_player/release/*.zip .
# blockmap, если есть:
cp /путь/к/dnd_player/release/*.blockmap . 2>/dev/null || true

Проверка, что Windows-файлы на месте:

ls -la

3.4. Коммит и push

git add latest-mac.yml *.dmg *.zip
git add *.blockmap 2>/dev/null || true
git status
git commit -m "mac: DNDGamePlayer vX.Y.Z (ручная выкладка)"
git push origin updates

Для HTTPS обычно используют персональный токен (PAT) Gitea вместо пароля, либо настроенный SSH (git@git.mailib.ru:ifontosh/DndGamePlayerUpdates.git).

3.5. Проверка

• Откройте latest-mac.yml по raw-URL (см. выше).
• Откройте в браузере прямую ссылку на один из .dmg из этого YAML — не должно быть 404.

---

4. Способ B — через веб-интерфейс Gitea

Подходит для редких правок; для больших dmg удобнее git.

1. Репозиторий DndGamePlayerUpdates → ветка updates.
2. Загрузить или изменить latest-mac.yml и бинарники (имена как в release/).
3. Не удалять при этом файлы Windows в корне, если они нужны для PC-обновлений.

---

5. Версии и Windows

• В latest-mac.yml и в именах файлов должна быть та версия приложения, которую вы отдаёте пользователям Mac (как в package.json на момент сборки).
• latest.yml (Windows) и latest-mac.yml (Mac) — разные файлы; версии на платформах могут совпадать или нет. Каждая ОС читает свой YAML.

---

6. Подпись кода (кратко)

Без Developer ID и при необходимости нотаризации macOS может ограничивать запуск после скачивания. На процедуру «залить файлы в репо» это не влияет, но влияет на UX после автообновления. Для продакшена имеет смысл позже настроить CSC_LINK, CSC_KEY_PASSWORD и нотаризацию по документации electron-builder.

---

7. Чеклист

1. Локально собрали Mac с --publish never и верным publish.url.
2. В release/ есть latest-mac.yml и все объекты, на которые он ссылается.
3. В ветке updates в корне репозитория обновили/добавили эти файлы, не снеся Windows-артефакты без необходимости.
4. Проверили raw-URL latest-mac.yml и ссылку на dmg.
5. В упакованном приложении с активной лицензией сработает существующий electron-updater (задержка первой проверки и cooldown — см. app/main/update/installAutoUpdater.ts).

---

Связанные документы

• Общая схема Gitea, секреты, раннер: GITEA_AUTO_UPDATE.md.