859 Aggiornamenti automatici in background859 Aggiornamenti automatici in background
860</h4>860</h4>
861 861
862Per impostazione predefinita, l'aggiornamento in background disabilita gli helper di credenziali git quando controlla il remote del marketplace per i nuovi commit, quindi il controllo non può autenticarsi ai repository privati su HTTPS anche quando un helper è configurato. I remote SSH non sono interessati: una chiave caricata in `ssh-agent` autentica il controllo in background allo stesso modo dei comandi che esegui.862Il controllo di aggiornamento in background verifica il remote del marketplace per i nuovi commit con i tuoi helper di credenziali git configurati, allo stesso modo dei comandi che esegui. Per i remote SSH, una chiave caricata in `ssh-agent` autentica il controllo. Claude Code esegue il controllo in modo non interattivo: disattiva i prompt del terminale di git e i programmi askpass, e dice agli helper di credenziali di non richiedere. Se il controllo può autenticarsi a un repository privato su HTTPS dipende dal tuo helper:
863 863
864Quando il controllo trova nuovi commit, o fallisce perché non riesce a raggiungere o autenticarsi al remote, Claude Code clona di nuovo il marketplace e scambia il nuovo clone. Se quel clone fallisce, il checkout esistente rimane al suo posto. La re-clonazione utilizza le tue credenziali git memorizzate, ma può [scadere su repository di grandi dimensioni](#git-operations-time-out), quindi gli aggiornamenti automatici del marketplace privato possono fallire intermittentemente.864* Un helper che può fornire una credenziale memorizzata senza richiedere autentica il controllo. Git Credential Manager, l'helper Keychain di macOS e `git-credential-store` funzionano in questo modo una volta che contengono una credenziale per l'host.
865* Un helper che ha bisogno di richiedere non può rispondere in background. L'aggiornamento fallisce silenziosamente e il checkout esistente rimane al suo posto, quindi i tuoi plugin continuano a funzionare dallo stato dell'ultima sincronizzazione. Esegui `/plugin marketplace update <name>` per aggiornare il marketplace con le tue credenziali.
866
867Quando il controllo trova il checkout aggiornato, Claude Code lo lascia così com'è. Quando il controllo trova nuovi commit, o fallisce perché non riesce a raggiungere o autenticarsi al remote, Claude Code clona di nuovo il marketplace e scambia il nuovo clone. Se quel clone fallisce, il checkout esistente rimane al suo posto. La re-clonazione può [scadere su repository di grandi dimensioni](#git-operations-time-out).
865 868
866Due impostazioni rendono i marketplace privati comportarsi in modo prevedibile:869Due impostazioni rendono i marketplace privati comportarsi in modo prevedibile:
867 870
868* Imposta `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il checkout esistente senza tentare la re-clonazione quando il controllo in background non riesce a raggiungere o autenticarsi al remote. I tuoi plugin continuano a funzionare dallo stato dell'ultima sincronizzazione, e gli aggiornamenti manuali con `/plugin marketplace update` continuano a autenticarsi con le tue credenziali.871* Imposta `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il checkout esistente senza tentare la re-clonazione quando il controllo in background non riesce a raggiungere o autenticarsi al remote. I tuoi plugin continuano a funzionare dallo stato dell'ultima sincronizzazione, e gli aggiornamenti manuali con `/plugin marketplace update` continuano a autenticarsi con le tue credenziali.
869* Configura un helper di credenziali git, ad esempio con `gh auth setup-git` per GitHub, in modo che la re-clonazione possa autenticarsi senza richiedere.872* Configura un helper di credenziali git, ad esempio con `gh auth setup-git` per GitHub, in modo che il controllo in background e la re-clonazione possano autenticarsi senza richiedere.
870 873
871L'impostazione di un token del provider come `GITHUB_TOKEN` nel tuo ambiente non abilita di per sé l'autenticazione in background. I token hanno effetto solo attraverso un helper di credenziali configurato, ad esempio l'helper della CLI `gh`, che legge `GH_TOKEN` e `GITHUB_TOKEN`.874L'impostazione di un token del provider come `GITHUB_TOKEN` nel tuo ambiente non abilita di per sé l'autenticazione in background. I token hanno effetto solo attraverso un helper di credenziali configurato, ad esempio l'helper della CLI `gh`, che legge `GH_TOKEN` e `GITHUB_TOKEN`.
872 875
873Per fare in modo che il controllo in background stesso si autentichi su HTTPS, configura una riscrittura URL git globale. La riscrittura incorpora un token nell'URL remoto, quindi ha effetto anche se il controllo in background disabilita gli helper di credenziali. Quando il controllo trova il checkout aggiornato, Claude Code salta la re-clonazione. L'esempio seguente riscrive l'URL del repository del marketplace per includere un token di accesso:
874
875```bash theme={null}
876git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"
877```
878
879Limita la riscrittura al repository del marketplace o al percorso dell'organizzazione. Una riscrittura la cui base è solo l'host si applica a ogni fetch e push a quell'host sulla macchina e sostituisce le tue credenziali normali, inclusi i push ai tuoi repository.
880
881Ogni provider si aspetta un nome utente diverso nell'URL riscritto, e la stessa limitazione del percorso si applica a ogni provider. Per server self-hosted, sostituisci il nome host con il nome host del tuo server:
882
883| Provider | Forma URL riscritto |
884| :-------- | :---------------------------------------------------------------- |
885| GitHub | `https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins` |
886| GitLab | `https://oauth2:YOUR_TOKEN@gitlab.com/acme-corp/plugins` |
887| Bitbucket | `https://x-token-auth:YOUR_TOKEN@bitbucket.org/acme-corp/plugins` |
888
889La riscrittura memorizza il token in testo semplice nel tuo gitconfig, quindi utilizza un token con accesso in sola lettura al repository del marketplace.
890
891<Note>876<Note>
892 Negli ambienti CI/CD, configura un helper di credenziali git prima di installare plugin da repository privati. Su GitHub Actions, esporta un token con accesso in lettura al repository del marketplace come `GH_TOKEN`, quindi esegui `gh auth setup-git`. Il token del workflow predefinito può accedere solo al repository del workflow stesso, quindi un marketplace privato in un altro repository ha bisogno di un token di accesso personale o di un token dell'app.877 Negli ambienti CI/CD, configura un helper di credenziali git prima di installare plugin da repository privati. Su GitHub Actions, esporta un token con accesso in lettura al repository del marketplace come `GH_TOKEN`, quindi esegui `gh auth setup-git`. Il token del workflow predefinito può accedere solo al repository del workflow stesso, quindi un marketplace privato in un altro repository ha bisogno di un token di accesso personale o di un token dell'app.
893
894 Se configuri una riscrittura URL globale nella pipeline, la riscrittura autentica anche il controllo in background direttamente.
895</Note>878</Note>
896 879
897<h3 id="distribute-through-organization-settings">880<h3 id="distribute-through-organization-settings">
1620 1603
1621Per gli aggiornamenti automatici in background:1604Per gli aggiornamenti automatici in background:
1622 1605
1623* Per impostazione predefinita, gli aggiornamenti in background disabilitano gli helper delle credenziali git quando controllano il remote per nuovi commit, quindi il controllo non può autenticarsi su HTTPS. I remote SSH con una chiave caricata in `ssh-agent` si autenticano ancora1606* Il controllo in background utilizza gli helper delle credenziali git configurati ma non richiede mai, quindi l'helper deve essere in grado di rispondere con una credenziale archiviata. I remote SSH con una chiave caricata in `ssh-agent` si autenticano anche
1624* Quando il controllo non può autenticarsi, Claude Code ri-clona il marketplace con le credenziali archiviate, ma il ri-clone potrebbe scadere su repository di grandi dimensioni1607* Se l'helper deve richiedervi, l'aggiornamento in background non riesce silenziosamente e il checkout esistente rimane in place. Accedere all'helper prima in modo che contenga una credenziale per l'host. Per GitHub, eseguire `gh auth login`, quindi `gh auth setup-git`
1625* Impostare `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il clone esistente senza tentare il ri-clone quando il controllo in background non riesce a raggiungere o autenticarsi al remote1608* Quando il controllo trova nuovi commit, o non riesce a raggiungere o autenticarsi al remote, Claude Code ri-clona il marketplace con le stesse credenziali. Il ri-clone potrebbe scadere su repository di grandi dimensioni
1626* Configurare un helper delle credenziali git, ad esempio `gh auth setup-git`, in modo che il ri-clone possa autenticarsi1609* Impostare `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per mantenere il checkout esistente senza tentare il ri-clone quando il controllo in background non riesce a raggiungere o autenticarsi al remote
1627* Se il re-clone scade su un repository di grandi dimensioni, aumentare il limite con [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out)1610* Se il ri-clone scade su un repository di grandi dimensioni, aumentare il limite con [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out)
1628* Configurare una [riscrittura dell'URL git](#private-repositories) limitata al repository del marketplace in modo che il controllo in background si autentichi direttamente
1629* Oppure aggiornare i marketplace privati manualmente con `/plugin marketplace update <name>`, che utilizza le credenziali1611* Oppure aggiornare i marketplace privati manualmente con `/plugin marketplace update <name>`, che utilizza le credenziali
1630 1612
1613Prima della v2.1.280, il controllo in background veniva eseguito senza gli helper delle credenziali e non poteva autenticarsi ai repository privati su HTTPS.
1614
1631<h3 id="marketplace-updates-fail-in-offline-environments">1615<h3 id="marketplace-updates-fail-in-offline-environments">
1632 Gli aggiornamenti del marketplace non riescono in ambienti offline1616 Gli aggiornamenti del marketplace non riescono in ambienti offline
1633</h3>1617</h3>
1634 1618
1635**Sintomi**: In un ambiente offline o airgapped, l'aggiornamento in background del marketplace non riesce a raggiungere il remote e Claude Code tenta ripetutamente un ri-clone che non può avere successo.1619**Sintomi**: In un ambiente offline o airgapped, l'aggiornamento in background del marketplace non riesce a raggiungere il remote e Claude Code tenta ripetutamente un ri-clone che non può avere successo.
1636 1620
1637**Causa**: L'aggiornamento in background controlla il remote del marketplace per nuovi commit, e quando il controllo non riesce a raggiungere il remote, Claude Code tenta di clonare di nuovo il marketplace. Offline, il clone non riesce allo stesso modo e il clone esistente rimane in place. Prima della v2.1.274, l'aggiornamento eseguiva `git pull` nel clone esistente, spostava il clone da parte per ri-clonare quando il pull non riusciva, e lo ripristinava in seguito su base best-effort.1621**Causa**: L'aggiornamento in background controlla il remote del marketplace per nuovi commit, e quando il controllo non riesce a raggiungere il remote, Claude Code tenta di clonare il marketplace di nuovo. Offline, il clone non riesce allo stesso modo e il checkout esistente rimane in place. Prima della v2.1.274, l'aggiornamento eseguiva `git pull` nel checkout esistente, spostava il checkout da parte per ri-clonare quando il pull non riusciva, e lo ripristinava in seguito su base best-effort.
1638 1622
1639L'aggiornamento viene eseguito in background dopo l'avvio, quindi non ritarda l'avvio. Ogni sessione ripete comunque il tentativo non riuscito, e ogni operazione git può attendere il [timeout di 120 secondi](#git-operations-time-out).1623L'aggiornamento viene eseguito in background dopo l'avvio, quindi non ritarda l'avvio. Ogni sessione ripete comunque il tentativo non riuscito, e ogni operazione git può attendere il [timeout di 120 secondi](#git-operations-time-out).
1640 1624
1641**Soluzione**: Impostare `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per saltare il tentativo di ri-clone e continuare a utilizzare il clone esistente quando il controllo non riesce a raggiungere il remote:1625**Soluzione**: Impostare `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` per saltare il tentativo di ri-clone e continuare a utilizzare il checkout esistente quando il controllo non riesce a raggiungere il remote:
1642 1626
1643```bash theme={null}1627```bash theme={null}
1644export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=11628export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
