Alla fine di questa guida, una conversazione di Claude collegata a osFoundry potrà leggere un repository GitNest, cercare nel suo codice e preparare modifiche: un task, un commit di file, un change set, il retry di un check, una pull request. Niente di tutto questo succede quando Claude lo chiede. Ogni azione arriva come proposta in "Needs your approval" (in attesa della tua approvazione) dentro osFoundry, con i file, il branch e il commit esatto sulla card, e parte solo quando clicchi Approve. Claude non ha nessun tool che scriva direttamente nel repository.
Chi fa cosa
| Lato Claude | Lato osFoundry | |
|---|---|---|
| Login | Il tuo account Claude, invariato | Il tuo account osFoundry ha approvato la connessione una volta |
| Cosa può vedere | Quello che restituiscono i tool di lettura | I repository GitNest assegnati a un progetto di cui fa parte la connessione |
| Leggere il codice | search_gitnest_code: estratti di righe limitati | Niente file binari, niente file interi, niente credenziali né binding locali |
| Modificare il codice | Sette tool propose_gitnest_… | Una proposta per chiamata, in attesa di te |
| Chi approva | Nessuno lato Claude | Tu, proprietario della connessione, finché hai ancora il ruolo sul repository |
| Chi scrive | Nessuno | osFoundry esegue l'azione approvata, attribuita alla connessione |
| Token del provider | Mai inviati | Il tuo account GitHub/GitLab collegato viene usato solo quando approvi una PR sul provider |
Configurazione
1. Collega la chat una volta
Se la chat di Claude non è ancora collegata a osFoundry, questa parte è il normale flusso dei connettori personalizzati: crea una connessione dall'icona della chiave → Connected, aggiungi il suo indirizzo server in Claude come connettore personalizzato e approva un workspace. Anthropic descrive il lato Claude nella sua guida ai connettori personalizzati. Il resto della guida dà per scontato che la connessione indichi "Connected."
2. Metti il repository in un progetto
Una connessione non vede mai un repository GitNest da sola. Il repository deve appartenere a un progetto di cui fa parte la connessione.
Apri il repository in GitNest e trova la sezione Project. Il testo dice "Connected agents in this project can use approved GitNest read tools when their connection owner still has repository access." Solo il proprietario del repository ha il selettore; tutti gli altri vedono il nome del progetto come semplice testo. Scegli il progetto. osFoundry conferma con "Repository project updated."
3. Aggiungi la connessione a quel progetto
Torna in icona della chiave → Connected, seleziona la connessione e, sotto Projects, aggiungila allo stesso progetto. I repository GitNest del progetto arrivano insieme a lei, con le note, le knowledge base e gli altri contenuti sincronizzati.
Apri Tools. "All supported tools are on by default", e la lista mostra ogni tool con spazi al posto degli underscore. Quelli di GitNest sono:
read gitnest repository propose gitnest work search gitnest code propose gitnest change set list gitnest work propose gitnest server composition read gitnest work propose gitnest file import list gitnest saved results propose gitnest check rerun list gitnest checks propose gitnest native publication propose gitnest provider publication 
Esempio: La checklist Tools di una connessione di Claude, tutti attivi di default
Se vuoi che Claude si fermi ai commit e non prepari mai una pull request, togli la spunta ai due tool di publication e clicca Save tools. Le proposte richiedono comunque la tua approvazione. Togliere la spunta significa solo che Claude non può nemmeno chiederlo.
4. Chiedi nella chat
Nella conversazione di Claude, attiva il connettore osFoundry dal menu + → Connectors e chiedi in linguaggio normale. Se hai aggiunto lo stesso server a Claude Code con il nome osfoundry, lì i tool compaiono come mcp__osfoundry__propose_gitnest_file_import e così via.
Un'esecuzione reale
I nomi dei tool e degli argomenti qui sotto sono quelli che il server di osFoundry elenca in tools/list. Repository, prompt, ID e risposte sono contenuti di esempio.
Esempio Tu: In osFoundry, aggiungi a demo-api un CONTRIBUTING.md che spieghi come eseguire i test (usano pytest in tests/), e apri un task a bassa priorità per collegarlo dal README. Claude → list_granted_resources {} ← progetto "API" · repository GitNest "demo-api" Claude → read_gitnest_repository {"repository_id": "…"} ← repository nativo, branch predefinito main Claude → search_gitnest_code {"repository_id": "…", "query": "pytest", "branch": "main"} ← pyproject.toml: [tool.pytest.ini_options] · tests/test_limits.py: import pytest Claude → propose_gitnest_file_import {"repository_id": "…", "branch": "main", "message": "Add CONTRIBUTING.md with test instructions", "files": [{"path": "CONTRIBUTING.md", "content": "# Contributing\n…"}], "idempotency_key": "…"} ← proposta in attesa del proprietario Claude → propose_gitnest_work {"repository_id": "…", "title": "Link CONTRIBUTING.md from README", "priority": "low", "idempotency_key": "…"} ← proposta in attesa del proprietario Claude: Ho preparato due proposte in osFoundry: un commit che aggiunge CONTRIBUTING.md a main e un task per collegarlo dal README. Non è ancora stato committato nulla. Entrambe aspettano la tua approvazione. In osFoundry, l'header mostra "Claude research proposes GitNest file changes", e il pannello della connessione elenca entrambe sotto "Needs your approval". La card del commit riporta "Commit GitNest files in demo-api", poi "Commit to branch: main", il messaggio di commit e un "Review all proposed files (1)" chiuso che si espande mostrando il CONTRIBUTING.md completo. Sotto: "Expires …", Approve and create, Decline.
Esempio: Una proposta di publish GitNest sotto Needs your approval
Un secondo prompt, su un change set che esiste già:
Esempio Tu: Il change set rate-limit è verde? Se integration è fallito, rilancialo, e quando passa preparalo come pull request. Claude → list_gitnest_work {"repository_id": "…", "kind": "changes"} ← "Rate-limit fix" · versione 3 Claude → list_gitnest_checks {"repository_id": "…", "change_set_id": "…"} ← commit composto 9c1e47a…: unit superato · integration fallito (terminato) Claude → propose_gitnest_check_rerun {"repository_id": "…", "change_set_id": "…", "check_name": "integration", "expected_change_set_version": 3, "expected_composition_oid": "9c1e47a…", "idempotency_key": "…"} ← proposta in attesa del proprietario … approvi il retry, passa … Claude → propose_gitnest_native_publication {"repository_id": "…", "change_set_id": "…", "expected_change_set_version": 3, "expected_composition_oid": "9c1e47a…", "idempotency_key": "…"} ← proposta in attesa del proprietario Guarda cosa deve inviare Claude. Sia il retry sia la publication indicano la versione del change set e il commit composto che Claude ha visto. Se qualcuno ricompone il change set prima del tuo clic, la versione o il commit che approveresti non è più quello sulla card, e il nuovo controllo di osFoundry al momento dell'approvazione si rifiuta di eseguirlo.
Cosa ti chiede di approvare ogni card
| Tool | Titolo della card | Pulsante | Cosa fa l'approvazione |
|---|---|---|---|
propose_gitnest_work | Create GitNest work | Approve and create | Crea un Todo e un work item GitNest |
propose_gitnest_change_set | Create GitNest draft change set | Approve and create | Crea un change set in bozza da risultati di esecuzione salvati. Niente viene composto o pubblicato |
propose_gitnest_server_composition | Compose GitNest change set | Approve and create | Compone il change set sul server dopo averne ricontrollato la versione |
propose_gitnest_file_import | Commit GitNest files | Approve and create | Fa il commit di massimo 20 file UTF-8 (200 KB in totale) sul branch indicato nella card |
propose_gitnest_check_rerun | Retry GitNest check | Approve retry | Rimette in coda un check terminato per quella versione e quel commit |
propose_gitnest_native_publication | Publish GitNest pull request | Approve and publish | Crea un branch di publication e apre una pull request nel repository nativo |
propose_gitnest_provider_publication | Open a draft GitHub or GitLab pull request | Approve and publish | Fa il push solo del branch di quel change set con il tuo account provider collegato e apre una PR in bozza |
Le card che riguardano un change set riportano "Change set: … · expected version N", "Reviewed commit: …" e un link "Review change set before approving" che lo apre in GitNest. Le due card di publication aggiungono ciascuna una riga su cosa succederà, per esempio "Approval creates a publication branch and opens a pull request in this native repository."
Dove passa il confine
La connessione di Claude non può scrivere in GitNest. Le route di scrittura di GitNest rifiutano gli accessi con scope agente (denyAgentScope nelle route GitNest di osFoundry), e i tool di Connected non le chiamano. Una chat di Claude può solo depositare una proposta, ed è osFoundry a eseguire l'azione dopo la tua approvazione, registrata con la connessione come origine. Così ogni scrittura di un agente passa da un unico percorso, e puoi verificarlo.
L'approvazione viene ricontrollata nel momento del clic. osFoundry verifica di nuovo che la connessione sia ancora attiva, che il repository sia ancora in un progetto di cui la connessione fa parte, che tu abbia ancora il ruolo sul repository e che la proposta non sia scaduta. Per una composition, un retry o una publication controlla anche la versione del change set e il commit, e per la publication la policy di rischio del repository, i check obbligatori e il branch di destinazione. Una proposta rifiutata, scaduta o non più attuale non viene eseguita. Ogni tool propose accetta un idempotency_key, quindi una chiamata che Claude ripete dopo una risposta persa non diventa una seconda richiesta.
Qui non viene deployato niente. Il punto più lontano a cui arriva una proposta è una pull request: una PR nativa GitNest, oppure una PR in bozza su GitHub o GitLab. Il merge, e tutto ciò che un merge innesca, resta a te in GitNest o sul provider.
Il tuo token del provider Git non arriva mai a Claude. Una PR sul provider usa l'account che hai collegato in osFoundry, al momento dell'approvazione, e fa il push solo del branch dedicato del change set, mai degli altri tuoi ref.
Le letture sono limitate di proposito. search_gitnest_code restituisce estratti di righe con un tetto, mai file binari o file interi. Le letture di work, esecuzioni e risultati salvati escludono binding locali e credenziali. Per modificare un file esistente, incolla il suo contenuto attuale nella chat così che Claude possa proporre la nuova versione completa. Aggiungere file nuovi funziona direttamente a partire dagli estratti.
Prossimo passo
Prova prima la scrittura più piccola: chiedi a Claude di proporre un solo file nuovo, come un CONTRIBUTING.md, poi apri la card ed espandi "Review all proposed files" prima di approvare. Come GitNest gestisce clone, push e token di accesso è spiegato nella pagina di GitNest.
