Cloud Repo Model — Przewodnik

Phase 69. Każdy projekt Arc OS żyje w prywatnym repozytorium GitHub zarządzanym przez Arc OS w Twoim imieniu. Nie potrzebujesz konta GitHub, nigdy nie widzisz github.com — ale jeśli chcesz podłączyć też własne repozytoria, możesz.

TL;DR

• Każdy projekt Arc OS = jedno prywatne repo. Tworzone automatycznie w momencie utworzenia projektu.
• Każdy użytkownik dostaje też jedno repo "system" na notatki między projektami i Twój osobisty CLAUDE.md.
• Twój Cloud Workspace klonuje każde repo do /workspace/<project> przy prowizjonowaniu. Pracuj tam bezpośrednio, pushuj, gdy będziesz gotów.
• Trzy komendy pokrywają cały cykl życia: arc pull, arc push, arc cloud sync.
• Repozytoria zewnętrzne mile widziane. Wklej dowolny URL SSH lub (wkrótce) wybierz z własnego GitHuba przez OAuth.

Dlaczego zarządzana organizacja bota na GitHubie?

Arc OS posiada organizację GitHub (arc-os-platform), która przechowuje każde auto-zarządzane repo dla każdego użytkownika. Nie widzisz jej, nie logujesz się do niej, a Twoje konto nigdy nie pojawia się jako członek. Robotyczna aplikacja GitHub App z ściśle ograniczonymi uprawnieniami tworzy repozytoria, rejestruje poświadczenia i nigdy nie przechowuje tokena dłużej niż godzinę.

Dwie praktyczne konsekwencje:

1. Możesz zarejestrować się w Arc OS bez konta GitHub. Pierwsza rejestracja, pierwszy projekt, pierwszy Cloud Workspace — to wszystko działa bez żadnej wizyty na github.com.
2. Możesz odejść, kiedy tylko zechcesz. Każde repo to standardowe repozytorium git, w pełni klonowalne; trzymamy w naszym codebase skrypt eksportu na mało prawdopodobny scenariusz, że GitHub kiedykolwiek wyłączy naszą organizację bota.

Aby zagłębić się w architekturę, zobacz docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md.

Trzy typy repozytoriów

Gdy otworzysz Settings → Cloud Workspace → Repositories, zobaczysz trzy sekcje:

1. System

To Twoja pamięć "wszystko-wszędzie". Cokolwiek umieścisz tu w CLAUDE.md, dotyczy każdego workera Arc OS, niezależnie od projektu. CLAUDE.md na poziomie projektu nadpisuje systemowy dla tego konkretnego projektu.

2. Project

Jeden wiersz na projekt. Znacznik pokazuje synced_at, więc widzisz, kiedy nastąpił ostatni push. Kliknięcie ikony GitHub otwiera widok repo tylko do odczytu na github.com — przydatne do permalinków, blame lub pobrania zipa bez arc pull.

3. External

Repozytoria zewnętrzne są całkowicie pod Twoją kontrolą. Arc OS klonuje je przy prowizjonowaniu, ale nie commituje ani nie pushuje ich nigdzie automatycznie. Używaj ich dla codebase'ów należących do klienta, pracy etatowej lub konta osobistego, którym nie chcesz, aby Arc OS zarządzał.

Komendy codziennego użytku

Wszystkie trzy są częścią arc (binarki CLI, instrukcje instalacji w arc-cli-reference.md). Działają z dowolnego work tree gita na Twoim laptopie i wystarczy raz wykonać arc login.

arc pull [project]

Jeśli bieżący katalog nie jest drzewem git, to klonuje repo projektu do niego. Jeśli jest, to fast-forwarduje main do najnowszej wersji z Twojego repo w organizacji bota.

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

Odmawia nadpisania niezacommitowanych zmian — najpierw commituj lub stashuj.

arc push [project]

Pushuje to, co masz lokalnie pod HEAD, do repo organizacji bota. Odmawia na brudnych drzewach, więc nigdy nie wypchniesz na pół zedytowanych plików. Pod spodem na chwilę podmienia URL remote'a na jednogodzinny token, pushuje, a potem przywraca publiczną formę SSH — żaden poświadczenia nie zostają na dysku po zakończeniu komendy.

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]

Wypisuje macierz stanu bez mutowania niczego (poza wykonaniem 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

Jeśli Twój lokalny HEAD jest przed origin/main, następna linia to ahead/behind:, więc od razu widzisz, jak bardzo dwa drzewa się rozjechały.

Możesz pominąć [project] w którejkolwiek z trzech komend, jeśli jesteś wewnątrz sesji arc <project> dev (podchwytujemy ARC_PROJECT ze środowiska).

Jak wpisuje się w to Cloud Workspace

Gdy prowizjonujesz Cloud Workspace, master server:

1. Bootuje świeży kontener, montuje /workspace.
2. Zapisuje jednogodzinny token instalacji GitHub App do ~/.git-credentials wewnątrz kontenera (nigdy do argv, nigdy do docker inspect).
3. Ustawia credential.helper=store, plus nieszkodliwe user.email / user.name, żeby commity nie failowały z "tell me who you are".
4. Klonuje Twoje repo systemowe do /workspace/_system i każde repo projektu do /workspace/<project>.

Gdy kontener przechodzi w stan idle (brak aktywności przez 30 minut), pauzujemy go — ale przed pauzą auto-commitujemy wszystkie brudne drzewa jako [auto] pre-pause snapshot i pushujemy je, więc Twoja praca zawsze trafia do repo organizacji bota, zanim światła zgasną. Przy wybudzeniu odświeżamy token i wykonujemy git fetch dla każdego repo, żeby następna sesja terminalowa wylądowała na świeżych refach.

Token żyje maksymalnie godzinę; każde wybudzenie lub pause-push odświeża go. App ID + klucz prywatny po stronie bota nigdy nie trafiają do kontenera.

Konwencja nazewnicza

Repozytoria w organizacji bota są nazywane <arc-user-id>--<slug>:

• 1775855296184--_system — Twoje repo systemowe
• 1775855296184--myapp — Twój projekt myapp

W UI Arc OS widzisz tylko slug (_system, myapp). Prefiks user-id jest tym, co zapobiega kolizji dwóch użytkowników na tej samej nazwie projektu w jednej organizacji GitHub.

Dodawanie repozytoriów zewnętrznych

Dwie ścieżki, ten sam efekt końcowy (wiersz w sekcji External):

Wklej URL SSH

1. Otwórz Settings → Cloud Workspace → Repositories.
2. Kliknij + Add external.
3. Wklej dowolny URL [email protected]:owner/repo.git lub https://....
4. Kliknij Clone.

To jedyna ścieżka, która działa dziś. Jeśli repo jest prywatne, musisz mieć ustawiony własny klucz SSH GitHub wewnątrz kontenera (opisane w standard-cloud.md § "GitHub SSH Setup"). Publiczne repozytoria klonują się od razu.

Połącz GitHub (już wkrótce w Phase 69.5a — #347)

1. Kliknij + Add external → zakładka Connect GitHub.
2. Autoryzuj aplikację OAuth GitHub Arc OS (domyślnie scope public_repo; przełącz Include private dla scope'a repo).
3. Wybierz repozytoria z listy z checkboxami.
4. Kliknij Add selected.

Wyląduje to jako część #347 — śledź w roadmapie.

Co się stanie, gdy usunę projekt?

Repo projektu jest archiwizowane, nie usuwane. Zarchiwizowane repozytoria zostają w organizacji bota przez 30 dni, po czym codzienny job czyszczący je usuwa. Jeśli zmienisz zdanie w tym oknie, odbudowa to jednolinijkowe przywrócenie przez flow wsparcia Arc OS.

Twoje repo systemowe nigdy nie jest archiwizowane automatycznie — podąża za Twoim kontem, nie za projektami.

Co się stanie, gdy usunę konto Arc OS?

Wymazanie wg GDPR Art. 17 (Phase 64) kaskaduje na repozytoria organizacji bota: zarówno Twoje repo _system, jak i każde repo per-project są archiwizowane przy usunięciu konta, a potem permanentnie usuwane wg tego samego 30-dniowego timera. Cogodzinny mirror manifestu do S3 (zobacz ban-day insurance niżej) gwarantuje, że nawet zarchiwizowana lista jest audytowalna pod kątem compliance.

Ubezpieczenie na ban-day

Wybraliśmy pojedynczą organizację bota zamiast self-hostowania Gitea, bo analiza kosztów wychodzi ~5k € taniej w 24 miesiącach. Trade-offem jest to, że zależymy od warunków usługi GitHuba.

Dwa mitigacje, które dostarczamy od pierwszego dnia:

1. Cogodzinny mirror manifestu. Cron job robi snapshot pełnej listy repozytoriów naszej organizacji bota do S3 co godzinę, więc zawsze mamy aktualny inwentarz.
2. Runbook eksportu w repo. scripts/phase-69-export-to-gitea.ts dokumentuje 6-krokową migrację z organizacji bota do świeżej instancji Gitea, z bramkami rollback między każdym krokiem. Wykonujemy dry-run kwartalnie, żeby nie zgnił.

Szacowany czas wall clock, jeśli kiedykolwiek będziemy musieli przełączyć: ~2 dni end-to-end.

FAQ

Czy potrzebuję konta GitHub? Nie. Zarejestruj się przez email, utwórz projekt, sprowizjonuj Cloud Workspace — to wszystko działa bez github.com.

Czy mój kolega z zespołu może zobaczyć moje repo projektu? Nie (do czasu uruchomienia współpracy w Phase 68). Repozytoria projektów są prywatne dla właściciela.

Dlaczego URL-e klonowania HTTPS? Tokeny instalacji GitHub App uwierzytelniają się przez HTTPS, nie SSH. repo_url, które pokazujemy w UI, to forma SSH (przydatna do otwarć tylko do odczytu na github.com); clone_url, które przekazujemy do git clone, to forma HTTPS z krótkożyjącym wbudowanym tokenem.

Gdzie różnica względem Standard Cloud? Standard Cloud to flota kontenerów (Hetzner, pauzowana po idle, dostępna przez web terminal). Cloud Repo Model to warstwa git, która stoi za wolumenem /workspace. Oba są częścią planu Starter Cloud; nie płacisz osobno.

Czy mogę wyłączyć auto-create dla jednego projektu? Nie dziś. Jeśli chcesz projekt Arc OS bez kodu (tylko notatki), użyj repo systemowego do pisania i traktuj projekt jako kontener wiedzy.

Zobacz też

• standard-cloud.md — prowizjonowanie kontenerów, web terminal, cykl życia
• arc-cli-reference.md — pełna powierzchnia CLI
• github-integration.md — integracja z Twoim własnym kontem GitHub (inna sprawa: webhooki, OAuth sign-in)
• docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md — pełna specyfikacja architektoniczna