Arc OS Docs Open in app →

Cloud Repo Model — Guide

Phase 69. Chaque projet Arc OS vit dans un dépôt GitHub privé géré par Arc OS pour ton compte. Tu n'as pas besoin de compte GitHub, tu ne vois jamais github.com — mais si tu veux aussi connecter tes propres dépôts, c'est possible.

TL;DR

Pourquoi une org GitHub bot gérée ?

Arc OS possède une organisation GitHub (arc-os-platform) qui héberge tous les dépôts auto-gérés de tous les utilisateurs. Tu ne la vois pas, tu ne t'y connectes pas, et ton compte n'apparaît jamais comme membre. Une GitHub App robotique avec des permissions strictement délimitées crée les dépôts, enregistre les identifiants et ne conserve jamais un token plus d'une heure.

Deux conséquences pratiques :

  1. Tu peux t'inscrire à Arc OS sans compte GitHub. Première inscription, premier projet, premier Cloud Workspace — tout fonctionne sans aucun aller-retour avec github.com.
  2. Tu peux partir quand tu veux. Chaque dépôt est un dépôt git standard, entièrement clonable ; on garde un script d'export dans notre codebase au cas (très improbable) où GitHub mettrait notre org bot hors ligne.

Pour une plongée architecturale en profondeur, voir docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md.

Les trois types de dépôts

Quand tu ouvres Paramètres → Cloud Workspace → Repositories, tu verras trois sections :

1. System

Champ Valeur
Où /workspace/_system
Objectif Notes inter-projets, CLAUDE.md personnel, brouillons
Visibilité Toi uniquement
Créé Automatiquement lors de ton premier projet
Supprimable Non

C'est ta mémoire « tout-partout ». Tout ce que tu mets dans CLAUDE.md ici s'applique à chaque worker Arc OS, quel que soit le projet. Le CLAUDE.md par projet écrase le niveau système pour ce projet.

2. Project

Champ Valeur
Où /workspace/<project>
Objectif Le code, les notes et la config pour un projet Arc OS
Visibilité Toi (la collaboration arrive en Phase 68)
Créé Automatiquement quand tu crées le projet
Supprimable Archivé quand tu supprimes le projet ; récupérable 30 jours

Une ligne par projet. Le badge affiche synced_at pour que tu voies quand le dernier push a eu lieu. Cliquer sur l'icône GitHub ouvre la vue en lecture seule du dépôt sur github.com — utile pour des liens permanents, du blame, ou télécharger un zip sans arc pull.

3. External

Champ Valeur
Où /workspace/<name> (tu choisis le nom du dossier)
Objectif Dépôts clients, tes propres dépôts GitHub, tout ce qui n'est pas géré par Arc
Visibilité Ce que l'upstream autorise
Créé Tu l'ajoutes via collage d'URL SSH ou GitHub OAuth (arrive en Phase 69.5a)
Supprimable Oui — bouton Corbeille sur la ligne

Les dépôts externes sont entièrement sous ton contrôle. Arc OS les clone au moment du provisionnement, mais ne les commit ni ne les push automatiquement où que ce soit. Utilise-les pour des codebases qui appartiennent à un client, un job, ou un compte personnel que tu ne veux pas voir géré par Arc OS.

Commandes au quotidien

Les trois font partie d'arc (le binaire CLI, instructions d'installation dans arc-cli-reference.md). Elles fonctionnent depuis n'importe quel arbre de travail git sur ton laptop et ne demandent qu'un arc login une fois.

arc pull [project]

Si le répertoire courant n'est pas un arbre git, ceci clone le dépôt du projet dedans. Si c'en est un, ceci fait un fast-forward de main vers la dernière version depuis ton dépôt bot-org.

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

Refuse d'écraser des changements non commités — commit ou stash d'abord.

arc push [project]

Push ce que ton HEAD local contient vers le dépôt bot-org. Refuse sur les arbres sales pour que tu ne push jamais des fichiers à moitié édités. En coulisses, ça échange brièvement l'URL du remote contre un token d'une heure, push, puis restaure la forme SSH publique — donc aucun identifiant ne reste sur le disque après la fin de la commande.

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]

Affiche la matrice d'état sans rien muter (au-delà d'un 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

Si ton HEAD local est en avance sur origin/main, la ligne suivante est ahead/behind: pour que tu voies immédiatement à quel point les deux arbres ont divergé.

Tu peux omettre [project] dans les trois commandes si tu es dans une session arc <project> dev (on récupère ARC_PROJECT depuis l'environnement).

Comment Cloud Workspace s'intègre

Quand tu provisionnes un Cloud Workspace, le serveur master :

  1. Démarre un container neuf, monte /workspace.
  2. Écrit un token d'installation GitHub App d'une heure dans ~/.git-credentials à l'intérieur du container (jamais dans argv, jamais dans docker inspect).
  3. Définit credential.helper=store, plus un user.email / user.name bénin pour que les commits n'échouent pas avec « tell me who you are ».
  4. Clone ton dépôt système dans /workspace/_system et chaque dépôt de projet dans /workspace/<project>.

Quand le container devient inactif (pas d'activité pendant 30 minutes), on le met en pause — mais avant la pause, on auto-commit tout arbre sale comme [auto] pre-pause snapshot et on le push, pour que ton travail soit toujours dans le dépôt bot-org avant que les lumières s'éteignent. Au réveil, on rafraîchit le token et on fait git fetch sur chaque dépôt pour que la prochaine session de terminal atterrisse sur des refs fraîches.

Le token vit au maximum une heure ; chaque réveil ou push de pause le rafraîchit. L'App ID + la clé privée côté bot n'entrent jamais dans un container.

Convention de nommage

Les dépôts dans l'org bot sont nommés <arc-user-id>--<slug> :

Tu ne vois jamais que le slug dans l'UI Arc OS (_system, myapp). Le préfixe user-id est ce qui empêche deux utilisateurs d'entrer en collision sur le même nom de projet dans une seule org GitHub.

Ajouter des dépôts externes

Deux chemins, même résultat final (une ligne dans la section External) :

Coller une URL SSH

  1. Ouvre Paramètres → Cloud Workspace → Repositories.
  2. Clique sur + Add external.
  3. Colle n'importe quelle URL [email protected]:owner/repo.git ou https://....
  4. Clique sur Clone.

C'est le seul chemin qui fonctionne aujourd'hui. Si le dépôt est privé, tu dois avoir configuré ta propre clé SSH GitHub à l'intérieur du container (couvert dans standard-cloud.md § « GitHub SSH Setup »). Les dépôts publics se clonent immédiatement.

Connecter GitHub (arrive en Phase 69.5a — #347)

  1. Clique sur + Add external → onglet Connect GitHub.
  2. Autorise l'application OAuth GitHub Arc OS (scope public_repo par défaut ; active Include private pour le scope repo).
  3. Choisis les dépôts depuis la liste à cases à cocher.
  4. Clique sur Add selected.

Ceci atterrira dans #347 — suis-le dans la roadmap.

Que se passe-t-il si je supprime un projet ?

Le dépôt du projet est archivé, pas supprimé. Les dépôts archivés restent dans l'org bot pendant 30 jours, après quoi le job de nettoyage quotidien les retire. Si tu changes d'avis pendant cette fenêtre, la reconstruction est une restauration en une ligne via le flux de support Arc OS.

Ton dépôt système n'est jamais archivé automatiquement — il suit ton compte, pas tes projets.

Que se passe-t-il si je supprime mon compte Arc OS ?

L'effacement RGPD Art. 17 (Phase 64) cascade vers les dépôts bot-org : à la fois ton dépôt _system et chaque dépôt par projet sont archivés à la suppression du compte, puis définitivement détruits sur le même minuteur de 30 jours. Le miroir horaire du manifeste vers S3 (voir l'assurance jour-de-ban ci-dessous) garantit que même la liste archivée est auditable pour la conformité.

Assurance jour-de-ban

On a choisi une seule org bot plutôt que d'auto-héberger Gitea parce que l'analyse de coût ressort ~5k€ moins cher sur 24 mois. Le compromis, c'est qu'on dépend des conditions d'utilisation de GitHub.

Deux mitigations qu'on livre dès le premier jour :

  1. Miroir horaire du manifeste. Un job cron capture toutes les heures la liste complète des dépôts de notre org bot vers S3, donc on a toujours un inventaire à jour.
  2. Runbook d'export dans le dépôt. scripts/phase-69-export-to-gitea.ts documente la migration en 6 étapes depuis l'org bot vers une instance Gitea fraîche, avec des points de retour entre chaque étape. On le teste à blanc trimestriellement pour qu'il ne pourrisse pas.

Horloge murale estimée si on doit basculer un jour : ~2 jours bout-en-bout.

FAQ

Dois-je avoir un compte GitHub ? Non. Inscris-toi avec un email, crée un projet, provisionne un Cloud Workspace — tout fonctionne sans github.com.

Mon coéquipier peut-il voir mon dépôt de projet ? Non (jusqu'à ce que la collaboration de Phase 68 soit livrée). Les dépôts de projet sont privés au propriétaire.

Pourquoi des URLs de clone HTTPS ? Les tokens d'installation GitHub App s'authentifient en HTTPS, pas en SSH. Le repo_url qu'on affiche dans l'UI est la forme SSH (utile pour les ouvertures en lecture seule sur github.com) ; le clone_url qu'on passe à git clone est la forme HTTPS avec un token éphémère intégré.

Quelle est la différence avec Standard Cloud ? Standard Cloud, c'est la flotte de containers (Hetzner, mis en pause après inactivité, accessibles via terminal web). Cloud Repo Model, c'est la couche git qui supporte le volume /workspace. Les deux font partie du plan Starter Cloud ; tu ne payes pas séparément.

Puis-je désactiver l'auto-création pour un projet ? Pas aujourd'hui. Si tu veux un projet Arc OS sans code (notes uniquement), utilise le dépôt système pour l'écriture et traite le projet comme un conteneur de connaissances.

Voir aussi