Cloud Repo Model — Гайд

Phase 69. Кожен проєкт Arc OS живе у приватному GitHub-репозиторії, яким керує Arc OS від твого імені. Тобі не потрібен GitHub-акаунт, ти ніколи не бачиш github.com — але якщо хочеш підключити й свої власні репозиторії, можеш.

TL;DR

Кожен проєкт Arc OS = один приватний репозиторій. Створюється автоматично в момент створення проєкту.
Кожен користувач також отримує один "system" репозиторій для крос-проєктних нотаток і твого персонального CLAUDE.md.
Твій Cloud Workspace клонує кожен репозиторій у /workspace/<project> при провіженінгу. Працюй там напряму, push коли готово.
Три команди покривають увесь життєвий цикл: arc pull, arc push, arc cloud sync.
Зовнішні репозиторії вітаються. Встав будь-який SSH URL або (скоро) вибери зі свого GitHub через OAuth.

Навіщо керована GitHub bot org?

Arc OS володіє GitHub-організацією (arc-os-platform), яка містить кожен авто-керований репозиторій для кожного користувача. Ти її не бачиш, не логінишся в неї, і твій акаунт ніколи не з'являється як учасник. Робот-GitHub App із жорстко обмеженими дозволами створює репозиторії, реєструє креденшали і ніколи не тримає токен довше за одну годину.

Два практичних наслідки:

Ти можеш зареєструватися в Arc OS без GitHub-акаунту. Перша реєстрація, перший проєкт, перший Cloud Workspace — усе працює без жодного звернення до github.com.
Ти можеш піти коли захочеш. Кожен репозиторій — це стандартний git-репозиторій, який повністю клонується; ми тримаємо експортний скрипт у нашому кодбейсі на малоймовірний випадок, якщо GitHub колись вимкне нашу bot org.

Для архітектурного занурення дивись docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md.

Три типи репозиторіїв

Коли ти відкриєш Settings → Cloud Workspace → Repositories, побачиш три секції:

1. System

Поле	Значення
Де	`/workspace/_system`
Призначення	Крос-проєктні нотатки, персональний `CLAUDE.md`, чернетки
Видимість	Тільки ти
Створено	Автоматично при першому проєкті
Можна видалити	Ні

Це твоя "усе-усюди" пам'ять. Будь-що, що ти кладеш у CLAUDE.md тут, застосовується до кожного воркера Arc OS, незалежно від проєкту. Per-project CLAUDE.md перекриває системний для цього проєкту.

2. Project

Поле	Значення
Де	`/workspace/<project>`
Призначення	Код, нотатки і конфіг для одного проєкту Arc OS
Видимість	Ти (колаборація з'явиться у Phase 68)
Створено	Автоматично при створенні проєкту
Можна видалити	Архівується при видаленні проєкту; відновлюється 30 днів

Один рядок на проєкт. Бейдж показує synced_at, щоб ти бачив, коли був останній push. Клік по іконці GitHub відкриває read-only перегляд репозиторію на github.com — корисно для permalinks, blame або завантаження zip без arc pull.

3. External

Поле	Значення
Де	`/workspace/<name>` (ти обираєш ім'я директорії)
Призначення	Клієнтські репозиторії, твої власні GitHub-репозиторії, усе, що не керується Arc
Видимість	Те, що дозволяє upstream
Створено	Ти додаєш через вставку SSH URL або GitHub OAuth (з'явиться у Phase 69.5a)
Можна видалити	Так — кнопка Trash на рядку

Зовнішні репозиторії повністю під твоїм контролем. Arc OS клонує їх при провіженінгу, але не робить авто-коміти і не push'ить нікуди. Використовуй їх для кодбейсів, що належать клієнту, основній роботі або персональному акаунту, який ти не хочеш доручати Arc OS.

Команди на щодень

Усі три — частина arc (CLI-бінарник, інструкції зі встановлення у arc-cli-reference.md). Вони працюють із будь-якого git work tree на твоєму ноуті й потребують arc login лише раз.

`arc pull [project]`

Якщо поточна директорія не є git-tree, ця команда клонує репозиторій проєкту в неї. Якщо є — fast-forward'ить main до найсвіжішого з твого bot-org репозиторію.

mkdir my-feature && cd my-feature
arc pull myapp
# → Cloning [email protected]:arc-os-platform/<uid>--myapp.git into <cwd>
# → ✓ cloned

Відмовляється перезаписувати незакомічені зміни — спочатку зроби commit або stash.

`arc push [project]`

Push'ить твій локальний HEAD у bot-org репозиторій. Відмовляється на брудних tree, тож ти ніколи не push'неш напівредаговані файли. Під капотом ненадовго підміняє URL remote на одногодинний токен, push'ить, потім відновлює публічну SSH-форму — тож після виходу з команди на диску не залишається креденшалів.

git commit -am "fix: handle empty body"
arc push myapp
# → → [email protected]:arc-os-platform/<uid>--myapp.git
# → To https://github.com/arc-os-platform/<uid>--myapp.git
# →    ac30671..914cc84  HEAD -> main
# → ✓ pushed

`arc cloud sync [project]`

Друкує матрицю стану нічого не змінюючи (окрім git fetch).

arc cloud sync myapp
# project:        myapp
# bot repo:       [email protected]:arc-os-platform/<uid>--myapp.git
# last_synced:    2026-06-04T11:07:53.695Z
# local HEAD:     914cc84
# origin/main:    914cc84
# dirty:          no

Якщо твій локальний HEAD попереду origin/main, наступний рядок — ahead/behind:, тож ти одразу бачиш, наскільки два дерева розійшлися.

Можеш опустити [project] у будь-якій з трьох команд, якщо ти всередині сесії arc <project> dev (ми підхоплюємо ARC_PROJECT зі змінних оточення).

Як сюди вписується Cloud Workspace

Коли ти провіженіш Cloud Workspace, master-сервер:

Піднімає свіжий контейнер, монтує /workspace.
Записує одногодинний installation token GitHub App у ~/.git-credentials усередині контейнера (ніколи в argv, ніколи в docker inspect).
Виставляє credential.helper=store плюс безпечні user.email / user.name, щоб коміти не падали з "tell me who you are".
Клонує твій system-репозиторій у /workspace/_system і кожен проєктний репозиторій у /workspace/<project>.

Коли контейнер ідлить (немає активності 30 хвилин), ми його паузимо — але перед паузою ми авто-комітимо будь-які брудні tree як [auto] pre-pause snapshot і push'имо їх, тож твоя робота завжди в bot-org репозиторії до того, як гасне світло. На прокид ми оновлюємо токен і робимо git fetch для кожного репозиторію, тож наступна сесія терміналу приземлиться на свіжі refs.

Токен живе максимум одну годину; кожне пробудження або pause-push його оновлює. App ID + private key bot-боку ніколи не потрапляють у контейнер.

Конвенція іменування

Репозиторії в bot org іменуються <arc-user-id>--<slug>:

1775855296184--_system — твій system-репозиторій
1775855296184--myapp — твій проєкт myapp

Ти бачиш лише slug в UI Arc OS (_system, myapp). Префікс user-id — це те, що не дає двом користувачам зіткнутися на однаковому імені проєкту в одній GitHub-організації.

Додавання зовнішніх репозиторіїв

Два шляхи, той самий результат (рядок у секції External):

Вставити SSH URL

Відкрий Settings → Cloud Workspace → Repositories.
Клікни + Add external.
Встав будь-який [email protected]:owner/repo.git або https://... URL.
Клікни Clone.

Це єдиний шлях, який працює сьогодні. Якщо репозиторій приватний, тобі потрібно мати налаштований власний GitHub SSH-ключ всередині контейнера (покрито у standard-cloud.md § "GitHub SSH Setup"). Публічні репозиторії клонуються одразу.

Підключити GitHub (з'явиться у Phase 69.5a — `#347`)

Клікни + Add external → вкладка Connect GitHub.
Авторизуй OAuth-додаток Arc OS GitHub (scope public_repo за замовчуванням; вмикни Include private для scope repo).
Обери репозиторії зі списку з чекбоксами.
Клікни Add selected.

Це з'явиться як частина #347 — відстежуй у roadmap.

Що станеться, якщо я видалю проєкт?

Репозиторій проєкту архівується, а не видаляється. Архівовані репозиторії залишаються в bot org 30 днів, після чого щоденний cleanup job їх прибирає. Якщо ти передумаєш у цьому вікні, відновлення — це однорядковий restore через support flow Arc OS.

Твій system-репозиторій ніколи не архівується автоматично — він прив'язаний до твого акаунту, а не до проєктів.

Що станеться, якщо я видалю свій акаунт Arc OS?

GDPR Art. 17 erasure (Phase 64) каскадить bot-org репозиторії: і твій _system, і кожен per-project репозиторій архівуються при видаленні акаунту, потім остаточно видаляються тим самим 30-денним таймером. Щогодинний manifest-мірор у S3 (див. ban-day insurance нижче) гарантує, що навіть архівований список можна аудитувати для compliance.

Ban-day insurance

Ми обрали єдину bot org замість self-hosted Gitea, бо аналіз вартості виходить приблизно на €5k дешевшим за 24 місяці. Компроміс — ми залежимо від terms of service GitHub.

Дві мітигації, які ми постачаємо з першого дня:

Щогодинний manifest-мірор. Cron-задача робить снапшот повного списку репозиторіїв нашої bot org у S3 щогодини, тож ми завжди маємо актуальну інвентаризацію.
Експортний runbook у репозиторії. scripts/phase-69-export-to-gitea.ts документує 6-крокову міграцію з bot org на свіжий Gitea-інстанс із rollback-гейтами між кожним кроком. Ми робимо dry-run цього щокварталу, щоб воно не протухало.

Орієнтовний wall clock, якщо колись доведеться перемикнутися: ~2 дні end-to-end.

FAQ

Чи потрібен мені GitHub-акаунт? Ні. Зареєструйся через email, створи проєкт, провіженінь Cloud Workspace — усе працює без github.com.

Чи побачить мій колега мій проєктний репозиторій? Ні (доки не з'явиться колаборація у Phase 68). Проєктні репозиторії приватні для власника.

Чому HTTPS clone URLs? Installation tokens GitHub App автентифікуються по HTTPS, не по SSH. repo_url, який ми показуємо в UI — це SSH-форма (корисна для read-only відкриття на github.com); clone_url, який ми передаємо в git clone — це HTTPS-форма з короткоживучим вбудованим токеном.

У чому різниця зі Standard Cloud? Standard Cloud — це флот контейнерів (Hetzner, паузиться після ідлу, доступний через web terminal). Cloud Repo Model — це git-шар, який бекапить том /workspace. Обидва — частина плану Starter Cloud; окремо ти за них не платиш.

Чи можу я вимкнути auto-create для одного проєкту? Сьогодні ні. Якщо ти хочеш проєкт Arc OS без коду (тільки нотатки), використовуй system-репозиторій для письма, а проєкт трактуй як контейнер для знань.

Дивись також

standard-cloud.md — провіженінг контейнерів, web terminal, життєвий цикл
arc-cli-reference.md — повна поверхня CLI
github-integration.md — інтеграція з твоїм власним GitHub-акаунтом (інша зона: webhooks, OAuth sign-in)
docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md — повна архітектурна специфікація