Panoramica
Una volta che la tua app è stata compilata e testata localmente, hai due modalità per distribuirla:- Distribuisci un tarball — carica la tua app direttamente su un server Twenty specifico per uso interno o privato.
- Pubblica su npm — pubblica il tuo pacchetto, rivendicalo in Twenty e completa la configurazione affinché altri spazi di lavoro possano scoprirlo e installarlo.
Proprietà della registrazione
La pubblicazione di un’app crea una registrazione dell’applicazione: l’identità dell’app sull’istanza, condivisa da ogni area di lavoro che la installa. Contiene la voce dell’app nel marketplace, il relativo client OAuth e il relativo stato lato server: leserverVariables configurate da un operatore e le voci con ambito server dell’archivio chiave-valore.
Un universalIdentifier è univoco nell’intera istanza e una registrazione appartiene al massimo a un’area di lavoro (il relativo proprietario) oppure a nessuna finché non viene rivendicata, quindi installare un’app e svilupparne una sono due diritti diversi:
Sincronizzare il codice e un manifest con un identificatore equivale a rivendicarne la paternità, quindi poter installare un’app non concede mai il diritto di pubblicare codice con la sua identità. A un workspace che non è il proprietario viene negato l’accesso, sia che l’app sia elencata, preinstallata o privata.
Due situazioni portano a questo rifiuto:
- L’identificatore appartiene a un altro workspace. Modifica
universalIdentifiernella configurazione della tua app: è la soluzione usuale quando hai effettuato il fork dell’app di qualcun altro. Se devi mantenere l’identificatore, il workspace proprietario deve trasferire la registrazione al tuo. - L’identificatore non appartiene ad alcun workspace. Le app importate dalla sincronizzazione del catalogo del marketplace inizialmente non hanno un proprietario. Rivendica il tuo con GitHub prima di svilupparci sopra. La pubblicazione con provenienza fornisce una prova della paternità; non assegna automaticamente uno spazio di lavoro proprietario in Twenty.
Compilazione della tua app
Esegui il comando di build per controllare i tipi e raggruppare la tua app:--json per esaminare il manifest e i metadati dell’artefatto. twenty app publish crea il pacchetto stesso; non è necessaria una build separata del tarball.
Distribuzione su un server (tarball)
Per le app che non vuoi rendere pubbliche — strumenti proprietari, integrazioni solo aziendali o build sperimentali — puoi distribuire un tarball direttamente su un server Twenty.Prerequisiti
Prima della distribuzione, ti serve un remote configurato che punti al server di destinazione. I remote memorizzano localmente l’URL del server e le credenziali di autenticazione in~/.twenty/config.json.
Aggiungi un remote:
Distribuzione
Compila e carica la tua app sul server in un solo passaggio:--remote production seleziona la connessione salvata sopra, anche se un altro remote è quello predefinito. Il salvataggio di un remote denominato non modifica quello predefinito esistente.
Condivisione di un’app distribuita
Le app in formato tarball non sono elencate nel marketplace pubblico, quindi altri spazi di lavoro sullo stesso server non le troveranno navigando. Per condividere un’app distribuita:- Vai a Impostazioni > Sviluppatori > App e apri la tua app in Le mie app
- Nella scheda Distribuzione, fai clic su Copia link di condivisione
- Condividi questo link con utenti su altri spazi di lavoro — li porterà direttamente alla pagina di installazione dell’app
Gestione delle versioni
Quando si aggiorna un’app in formato tarball già distribuita, il server richiede che laversion in package.json sia strettamente superiore (per l’ordinamento semver) rispetto alla versione attualmente distribuita. La ridistribuzione della stessa versione, o il caricamento di una versione precedente, viene rifiutata quando il server registra il tarball caricato, che viene quindi nuovamente eliminato. Vedrai un errore VERSION_ALREADY_EXISTS dalla CLI.
Per rilasciare un aggiornamento:
- Incrementa il campo
versionnel tuopackage.json(ad es.1.2.3→1.2.4,1.3.0o2.0.0). - Esegui
twenty app publish --private --remote production - Gli spazi di lavoro che hanno installato l’app e abilitato l’aggiornamento automatico (nella scheda Generale dell’app) vengono aggiornati automaticamente in secondo piano; gli altri vedranno l’aggiornamento disponibile nelle loro impostazioni
I tag di pre-release funzionano come previsto: incrementare
1.0.0-rc.1 → 1.0.0-rc.2 è
consentito e una release finale come 1.0.0 viene correttamente riconosciuta come superiore
a 1.0.0-rc.5. La versione in package.json deve essere essa stessa una stringa semver
valida.Compatibilità della versione del server
Se la tua app utilizza una funzionalità introdotta in una specifica versione del server Twenty (ad esempio, i provider OAuth aggiunti nella v2.3.0), dovresti dichiarare la versione minima del server richiesta dalla tua app utilizzando il campoengines.twenty in package.json:
Cosa succede durante il deploy e l’installazione:
- Se
engines.twentyè impostato e la versione del server di destinazione non soddisfa l’intervallo, il deploy (caricamento del tarball) o l’installazione vengono rifiutati con un erroreSERVER_VERSION_INCOMPATIBLEe un messaggio che indica sia l’intervallo richiesto sia la versione effettiva del server. - Se
engines.twentynon è impostato, non viene eseguito alcun controllo della versione e l’app è accettata su qualsiasi versione del server (retrocompatibile con le app esistenti). Un valore vuoto viene rifiutato come intervallo non valido. - Il marketplace non elenca un’app la cui versione più recente dichiara un intervallo
engines.twentyche il server non soddisfa, oppure un intervallo non valido. L’app rimane registrata e visibile nel pannello di amministrazione. - Se sul server non è configurata
APP_VERSION, il controllo viene ignorato.
Il server è l’autorità di controllo — convalida
engines.twenty sia durante il
caricamento del tarball sia durante l’installazione nello spazio di lavoro. Se distribuisci un tarball out-of-band o
installi dal marketplace, il server continua comunque a imporre la compatibilità.CI/CD automatizzati (workflow preconfigurati)
Le app generate contwenty app init includono tre workflow di GitHub Actions pronti all’uso, nella cartella .github/workflows/. L’esecuzione della CI non richiede alcuna configurazione, la CD richiede un solo secret e la pubblicazione su npm richiede una configurazione una tantum di npm trusted-publisher.
CI — ci.yml
Esegue automaticamente i test di integrazione a ogni push su main e sulle pull request.
Cosa fa:
- Esegue il checkout del codice sorgente della tua app.
- Avvia un’istanza di test isolata di Twenty utilizzando l’azione composita
twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main. - Abilita Corepack e configura Node.js in base al tuo
.nvmrc. - Installa la CLI standalone con versione fissata nel passaggio Install Twenty CLI.
- Installa le dipendenze con
yarn install --immutable, quindi esegue lint, controllo dei tipi e test unitari. - Esegue
yarn test, passandoTWENTY_API_URLeTWENTY_API_KEYdall’istanza avviata affinché i tuoi test possano comunicare con un server reale.
TWENTY_VERSION(variabile di ambiente, predefinitolatest) — fissa la versione del server Twenty usata nella CI modificando questo valore inci.yml.- La concorrenza è raggruppata per
github.refe annulla le esecuzioni in corso in caso di nuovi push.
CD — cd.yml
Esegue il deploy della tua app su un server Twenty configurato a ogni push su main e, facoltativamente, da una pull request quando viene applicata l’etichetta deploy.
Cosa fa:
- Esegue il checkout della testa della PR (per le PR etichettate) oppure del commit inviato.
- Esegue
twentyhq/twenty/.github/actions/deploy-twenty-app@main— l’equivalente per la CI ditwenty app publish --private. - Esegue
twentyhq/twenty/.github/actions/install-twenty-app@mainin modo che la versione appena distribuita venga installata nello spazio di lavoro di destinazione.
Il valore predefinito di
TWENTY_DEPLOY_URL, http://localhost:2020, è un segnaposto —
non raggiungerà alcuna risorsa da un runner ospitato su GitHub. Aggiornalo all’URL pubblico del tuo
server (oppure usa un runner self-hosted con accesso di rete) prima di
abilitare il CD.deploy a una pull request. La condizione if: in cd.yml eseguirà il job per quella PR utilizzando il commit di testa della PR, permettendoti di convalidare una modifica sul server di destinazione prima del merge.
Pubblica — publish.yml
Pubblica la tua app su npm con attestazione di provenienza quando esegui il push di un tag di versione (ad es. v1.0.0), oppure quando esegui manualmente il workflow dalla scheda Actions.
Cosa fa:
- Clona la tua app, configura Node.js e aggiorna npm (la pubblicazione attendibile richiede npm 11.5.1 o versioni successive).
- Installa la CLI standalone con versione fissata nel passaggio Install Twenty CLI, quindi installa le dipendenze dell’app con
yarn install --immutable. - Esegue
twenty app publish, che compila e crea un pacchetto di uno snapshot isolato dell’app, quindi lo pubblica su npm. In CI aggiunge automaticamente--provenancee--access public, quindi non sono necessari flag nel workflow.
publish.yml (consulta la documentazione su npm trusted publishing). La pubblicazione con provenienza certifica quale repository GitHub ha compilato il pacchetto. Dopo la pubblicazione, rivendica la proprietà in Twenty.
npm accetta la provenienza solo da repository di origine pubblici. Se esegui la pubblicazione da un repository privato, npm rifiuta il bundle di provenienza OIDC con un Senza la provenienza GitHub, il pacchetto non può essere rivendicato tramite Rivendica con GitHub. Usa un repository pubblico con provenienza se hai bisogno di questo flusso di proprietà.
E422 ... Errore "Unsupported GitHub Actions source repository visibility: \"private\".” Per pubblicare da un repository privato, escludi la provenienza impostando TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true' nella env dello step di pubblicazione (nel publish.yml generato è incluso un suggerimento commentato):Fissare la versione della CLI
Tutti e tre i workflow generati fissano la CLI standalone alla versione ditwenty che ha eseguito twenty app init. I passaggi Install Twenty CLI in ci.yml e publish.yml usano npm install -g twenty@\<version>. In cd.yml, sia l’azione di deploy sia quella di installazione ricevono la stessa versione tramite il loro input cli-version.
Per aggiornare, aggiorna insieme i due comandi di installazione ed entrambi gli input cli-version. Questi vincoli sono separati dalla versione del server TWENTY_VERSION usata nella CI e dai riferimenti alle azioni riutilizzabili riportati di seguito.
Bloccare le azioni riutilizzabili
I workflowci.yml e cd.yml fanno riferimento ad azioni riutilizzabili a @main, quindi gli aggiornamenti delle azioni nel repository twentyhq/twenty vengono recepiti automaticamente. Se desideri build deterministiche, sostituisci @main con uno SHA di commit o un tag di release in ciascuna riga uses:.
Pubblicazione su npm
La pubblicazione su npm rende la tua app idonea per il marketplace di Twenty. Dopo la sincronizzazione del catalogo e qualsiasi configurazione delle route del server richiesta, gli spazi di lavoro possono visualizzarla, installarla e aggiornarla dall’interfaccia utente una volta superata la revisione del marketplace.Requisiti
- Un account npm
- La parola chiave
twenty-appnell’arraykeywordsdel tuopackage.json(aggiungila manualmente — non è inclusa per impostazione predefinita nel templatetwenty app init)
Metadati del marketplace
La configurazionedefineApplication() supporta campi opzionali che controllano come la tua app appare nel marketplace. Usa logo e galleryImages per fare riferimento alle immagini nella cartella public/:
src/application-config.ts
author, category, aboutDescription, websiteUrl, termsUrl, ecc.).
Dimensioni consigliate delle immagini della galleria
Il marketplace visualizza legalleryImages in un contenitore 8:5 fisso (ad esempio, 1600×1000 px).
Le immagini della galleria di qualsiasi rapporto d’aspetto vengono visualizzate per intero e non vengono mai
ritagliate, ma quelle significativamente più alte o più strette di
8:5 mostreranno
bande vuote ai lati.Limite dimensione immagine
Il filelogo e ciascun file di galleryImages non devono superare 10 MB. I file più grandi vengono ignorati quando il marketplace ripubblica le tue risorse pubblicate, quindi non verranno visualizzati.
Pubblica
beta o next):
Come funziona l’individuazione nel marketplace
Il server Twenty sincronizza il proprio catalogo del marketplace dal registro npm ogni ora. La CLI standalone non dispone di un comando di sincronizzazione del catalogo. Attendi la sincronizzazione del catalogo del server oppure usa gli strumenti di amministrazione del server. I metadati mostrati nel marketplace provengono dalla configurazione didefineApplication() — vedi Metadati del marketplace sopra.
Se la tua app non definisce un
aboutDescription in defineApplication(), il marketplace userà automaticamente il README.md del tuo pacchetto su npm come contenuto della pagina Informazioni. Questo significa che puoi mantenere un unico README sia per npm sia per il marketplace di Twenty. Se desideri una descrizione diversa nel marketplace, imposta esplicitamente aboutDescription.La scheda Informazioni visualizza solo testo Markdown. Le immagini non vengono visualizzate, sia che utilizzino la sintassi Markdown sia i tag <img>, e l’HTML non elaborato, come badge o blocchi \<div align="center">, viene mostrato come testo semplice.Pubblicazione con CI
Il workflowpublish.yml generato dallo scaffold descritto sopra pubblica automaticamente su npm sui tag di versione, con provenance. Poiché twenty app publish aggiunge --provenance e --access public per te quando viene eseguito in CI, il workflow non richiede flag npm — serve solo la configurazione una tantum del trusted publisher.
Per altri sistemi CI (GitLab CI, CircleCI, ecc.), esegui yarn install e poi twenty app publish. La provenance viene emessa quando l’ambiente può generare un token OIDC e, in caso contrario, viene saltata automaticamente.
npm provenance aggiunge un badge di attendibilità alla tua scheda npm, consentendo agli utenti
di verificare che il pacchetto sia stato creato a partire da uno specifico commit in una pipeline CI pubblica.
È anche ciò che ti permette di dichiarare la proprietà della tua app in un marketplace Twenty.
Consulta la documentazione su npm provenance
per maggiori dettagli.
Rivendicare la tua app
La rivendicazione assegna la registrazione della tua app allo spazio di lavoro Twenty che la gestirà. La rivendicazione dell’app è disponibile per tutti gli spazi di lavoro. Il tuo ruolo richiede le autorizzazioni App dello spazio di lavoro e Sviluppatori per rivendicare tramite la scheda App di Impostazioni > Sviluppatori. La proprietà è per istanza di Twenty: la rivendicazione su Twenty Cloud non rivendica l’app su un server self-hosted separato. Gli altri spazi di lavoro sulla stessa istanza installano la tua app senza doverla rivendicare personalmente.Prima di rivendicare
- Pubblica il tuo pacchetto da un repository GitHub pubblico usando GitHub Actions e la pubblicazione attendibile npm con provenienza. La versione importata nel catalogo di Twenty deve includere l’attestazione di provenienza.
- Includi la parola chiave
twenty-appinpackage.jsone attendi la sincronizzazione del catalogo. - Scegli lo spazio di lavoro che sarà proprietario dell’app. Per le app con route del server, questo spazio di lavoro esegue e paga anche il resolver condiviso.
- Accedi a GitHub come account personale proprietario del repository di origine oppure come proprietario dell’organizzazione che ne è proprietaria. Il solo accesso come collaboratore al repository o come manutentore del pacchetto npm non è sufficiente.
Rivendica con GitHub
- Nello spazio di lavoro del proprietario previsto, vai a Impostazioni > Sviluppatori > App (
/settings/developers#apps). - In Rivendica un’applicazione, inserisci il nome esatto del pacchetto npm, incluso il relativo ambito (ad esempio,
@your-org/twenty-app), oppure l’universalIdentifierdell’app. - Fai clic su Cerca e verifica che il risultato sia la tua app. Se non viene trovata, fai clic su Sincronizza catalogo se disponibile, attendi il completamento della sincronizzazione, quindi cercala di nuovo.
- Fai clic su Rivendica con GitHub e autorizza Twenty. Per un repository di proprietà di un’organizzazione, concedi l’accesso a tale organizzazione nella sezione Accesso all’organizzazione di GitHub. I repository personali non richiedono un’autorizzazione dell’organizzazione.
- Quando torni in Twenty, verifica che l’app appaia in Le mie app con tipo NPM. Aprila e verifica Distribuzione > Proprietà per Rivendicata da questo spazio di lavoro.
Configurazione delle route del server
Una route del server riceve eventi per più spazi di lavoro a un unico URL. Il relativo resolver viene eseguito nello spazio di lavoro proprietario della registrazione, quindi distribuisce il lavoro allo spazio di lavoro installato appropriato.- Apri la tua app in Le mie app e compila tutte le Variabili del server richieste nella scheda Configurazione.
- In Distribuzione, fai clic su Visualizza nel marketplace per aprire la pagina dell’app e installarla nello spazio di lavoro proprietario. Puoi aprire questa pagina anche prima che l’app appaia nella ricerca del marketplace.
- Registra l’URL del webhook del server presso il tuo provider e testa un evento da un secondo spazio di lavoro in cui l’app è installata. Controlla i log sia del resolver sia della funzione di destinazione.
Costi e disponibilità dello spazio di lavoro proprietario
Consulta come vengono misurate le esecuzioni delle funzioni logiche per informazioni sul consumo di crediti, sui prezzi e su quale spazio di lavoro viene fatturato. La disinstallazione dell’app dallo spazio di lavoro proprietario o l’eliminazione di tale spazio di lavoro rimuove il resolver condiviso e interrompe i webhook del server per ogni installazione su quell’istanza.Proprietà dopo lo spostamento di un repository
Lo spostamento del repository GitHub a un altro account personale o a un’altra organizzazione non trasferisce né rimuove una rivendicazione Twenty esistente. La registrazione rimane associata al proprio spazio di lavoro proprietario. Mantieni lo stesso pacchetto npm e l’universalIdentifier dell’app; per modificare lo spazio di lavoro proprietario di Twenty è necessario un trasferimento di proprietà separato.
Risoluzione dei problemi relativi a una rivendicazione
Se riscontri problemi nel rivendicare la tua app, contattaci su Discord oppure apri una segnalazione su GitHub.Configurazione della rivendicazione GitHub self-hosted
Configurazione della rivendicazione GitHub self-hosted
L’amministratore del server configura
APP_CLAIM_GITHUB_CLIENT_ID e
APP_CLAIM_GITHUB_CLIENT_SECRET con un’app OAuth di GitHub. Imposta il relativo
URL di callback per l’autorizzazione sul tuo SERVER_URL seguito da
/application-registration-claim/github/callback, ad esempio
https://twenty.example.com/application-registration-claim/github/callback.
Questa configurazione è già gestita per te su Twenty Cloud.Visibilità e revisione del Marketplace
Ogni app elencata nel marketplace ha superato la revisione di sicurezza e qualità di Twenty. Un’app appena pubblicata resta non elencata finché non supera la revisione del marketplace; rivendicarla ne stabilisce la proprietà, ma non la inserisce nell’elenco. Un’app non elencata può comunque essere installata. In Impostazioni > Applicazioni > Marketplace, apri il filtro e attiva Mostra app non elencate, oppure condividi la pagina di installazione diretta dell’app usando Le mie app > la tua app > Distribuzione > Copia link di condivisione. Gli spazi di lavoro visualizzano un avviso che indica che l’app non è stata revisionata da Twenty. Se la tua app è elencata ma non è ancora presente nel marketplace, verifica che la sincronizzazione del catalogo sia stata completata, che tutte le variabili del server richieste siano compilate e che qualsiasi configurazione delle route del server sia completata.Installazione delle app
Una volta che un’app è stata pubblicata (npm) o distribuita (tarball), gli spazi di lavoro possono installarla tramite l’interfaccia utente. Vai alla pagina Impostazioni > Applicazioni in Twenty, dove è possibile sfogliare e installare sia le app del marketplace sia quelle distribuite tramite tarball. Dalla directory dell’app, installa la versione pubblicata nell’area di lavoro di destinazione:--universal-identifier \<id>.
Il server applica il versioning semver durante l’installazione, rispecchiando le regole del deploy:
- L’installazione della stessa versione già installata nel tuo spazio di lavoro viene rifiutata con un errore
APP_ALREADY_INSTALLED. - L’installazione di una versione inferiore rispetto a quella attualmente installata viene rifiutata con un errore
CANNOT_DOWNGRADE_APPLICATION.
twenty app install --remote production.