Prezentare generală
După ce aplicația ta este construită și testată local, ai două căi pentru distribuire:- Implementează un tarball — încarcă aplicația direct pe un server Twenty anume pentru uz intern sau privat.
- Publică pe npm — publică-ți pachetul, revendică-l în Twenty și finalizează configurarea acestuia, astfel încât alte spații de lucru să îl poată descoperi și instala.
Proprietatea înregistrării
Publicarea unei aplicații creează o înregistrare a aplicației: identitatea aplicației în instanță, partajată de fiecare spațiu de lucru care o instalează. Aceasta conține intrarea aplicației în marketplace, clientul său OAuth și starea sa de pe server —serverVariables pe care le configurează un operator și intrările cu domeniul de aplicare server din magazinul de chei-valori.
Un universalIdentifier este unic în întreaga instanță, iar o înregistrare aparține cel mult unui spațiu de lucru (proprietarul său) — sau niciunuia până când este revendicată — astfel încât instalarea unei aplicații și dezvoltarea uneia sunt două drepturi diferite:
Sincronizarea codului și a unui manifest sub un identificator reprezintă o revendicare a calității de autor, astfel că posibilitatea de a instala o aplicație nu acordă niciodată dreptul de a publica cod sub identitatea acesteia. Un spațiu de lucru care nu este proprietarul este refuzat, indiferent dacă aplicația este listată, preinstalată sau privată.
Două situații conduc la acest refuz:
- Identificatorul aparține altui spațiu de lucru. Modificați
universalIdentifierîn configurația aplicației dvs., ceea ce este soluția obișnuită atunci când ați creat un fork al aplicației altcuiva. Dacă trebuie să păstrați identificatorul, spațiul de lucru proprietar trebuie să transfere înregistrarea către al dvs. - Identificatorul nu aparține niciunui spațiu de lucru. Aplicațiile importate prin sincronizarea catalogului marketplace încep fără proprietar. Revendică-l pe al tău cu GitHub înainte de a-l dezvolta. Publicarea cu proveniență oferă dovada paternității; nu atribuie automat un spațiu de lucru proprietar în Twenty.
Construirea aplicației
Rulează comanda de compilare pentru a verifica tipurile și a împacheta aplicația:--json pentru a inspecta manifestul și metadatele artefactului. twenty app publish creează pachetul propriu-zis; nu este necesară o compilare separată a arhivei tarball.
Implementare pe un server (tarball)
Pentru aplicațiile pe care nu le dorești disponibile public — instrumente proprietare, integrări doar pentru enterprise sau build-uri experimentale — poți implementa un tarball direct pe un server Twenty.Cerințe
Înainte de implementare, ai nevoie de un remote configurat care să indice serverul țintă. Remote-urile stochează local URL-ul serverului și credențialele de autentificare în~/.twenty/config.json.
Adaugă un remote:
Implementare
Construiește și încarcă aplicația ta pe server într-un singur pas:--remote production explicit selectează conexiunea salvată mai sus, chiar dacă o altă conexiune la distanță este implicită. Salvarea unei conexiuni la distanță cu nume nu schimbă o conexiune implicită existentă.
Partajarea unei aplicații implementate
Aplicațiile tarball nu sunt listate în marketplace-ul public, astfel încât alte spații de lucru de pe același server nu le vor descoperi prin navigare. Pentru a partaja o aplicație implementată:- Accesează Settings > Developers > Apps și deschide aplicația ta din My apps
- În fila Distribuție, fă clic pe Copiază linkul de partajare
- Partajează acest link cu utilizatori din alte spații de lucru — îi duce direct la pagina de instalare a aplicației
Gestionarea versiunilor
Când actualizezi o aplicație tarball deja implementată, serverul solicită caversion din package.json să fie strict mai mare (conform ordonării semver) decât versiunea implementată în prezent. Redeploierea aceleiași versiuni sau încărcarea uneia inferioare este respinsă atunci când serverul înregistrează arhiva tarball încărcată, care este apoi eliminată din nou. Veți vedea o eroare VERSION_ALREADY_EXISTS din CLI.
Pentru a lansa o actualizare:
- Incrementează câmpul
versiondinpackage.json(de ex.1.2.3→1.2.4,1.3.0sau2.0.0) - Rulează
twenty app publish --private --remote production - Spațiile de lucru care au aplicația instalată și au activat actualizarea automată pentru aceasta (în fila General a aplicației) sunt actualizate automat în fundal; celelalte vor vedea actualizarea disponibilă în setările lor
Etichetele de pre-lansare funcționează conform așteptărilor: incrementarea de la
1.0.0-rc.1 → 1.0.0-rc.2 este
permisă, iar o lansare finală precum 1.0.0 este recunoscută corect ca fiind mai mare
decât 1.0.0-rc.5. Versiunea din package.json trebuie să fie ea însăși un șir semver
valid.Compatibilitatea versiunii serverului
Dacă aplicația ta folosește o funcționalitate introdusă într-o anumită versiune de server Twenty (de exemplu, furnizori OAuth adăugați în v2.3.0), ar trebui să declari versiunea minimă de server necesară aplicației folosind câmpulengines.twenty din package.json:
Ce se întâmplă în timpul implementării și instalării:
- Dacă
engines.twentyeste setat și versiunea serverului țintă nu respectă intervalul, implementarea (încărcarea arhivei tarball) sau instalarea este respinsă cu eroareaSERVER_VERSION_INCOMPATIBLEși cu un mesaj care indică atât intervalul necesar, cât și versiunea efectivă a serverului. - Dacă
engines.twentynu este setat, nu se efectuează nicio verificare a versiunii, iar aplicația este acceptată pe orice versiune de server (retrocompatibilă cu aplicațiile existente). O valoare goală este respinsă ca interval nevalid. - Marketplace-ul nu listează o aplicație a cărei cea mai recentă versiune declară un interval
engines.twentype care serverul nu îl satisface sau un interval nevalid. Aplicația rămâne înregistrată și vizibilă în panoul de administrare. - Dacă serverul nu are nicio
APP_VERSIONconfigurată, verificarea este omisă.
Serverul este verificarea autoritativă — validează
engines.twenty atât la
încărcarea arhivei tarball, cât și la instalarea în spațiul de lucru. Dacă implementezi o arhivă tarball în afara fluxului standard sau
instalezi din marketplace, serverul impune în continuare compatibilitatea.CI/CD automatizat (fluxuri de lucru preconfigurate)
Aplicațiile generate cutwenty app init vin, gata de utilizare, cu trei fluxuri de lucru GitHub Actions, în .github/workflows/. CI rulează fără nicio configurare, CD necesită un singur secret, iar publicarea pe npm necesită o configurare unică pentru npm trusted publisher.
CI — ci.yml
Rulează testele de integrare la fiecare push pe main și la fiecare pull request.
Ce face:
- Preia codul sursă al aplicației.
- Pornește o instanță de test Twenty izolată folosind acțiunea compozită
twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main. - Activează Corepack și configurează Node.js din
.nvmrc-ul tău. - Instalează CLI-ul independent fixat în pasul Install Twenty CLI.
- Instalează dependențele cu
yarn install --immutable, apoi rulează lint, verificarea tipurilor și testele unitare. - Rulează
yarn test, transmitândTWENTY_API_URLșiTWENTY_API_KEYdin instanța pornită, astfel încât testele să poată comunica cu un server real.
TWENTY_VERSION(variabilă de mediu, implicitlatest) — fixează versiunea serverului Twenty folosită în CI editând acest parametru înci.yml.- Concurența este grupată după
github.refși anulează execuțiile în desfășurare la noile push-uri.
CD — cd.yml
Implementează aplicația pe un server Twenty configurat la fiecare push pe main și, opțional, dintr-un pull request când se aplică eticheta deploy.
Ce face:
- Preia head-ul PR-ului (pentru PR-urile etichetate) sau commitul împins.
- Rulează
twentyhq/twenty/.github/actions/deploy-twenty-app@main— echivalentul din CI altwenty app publish --private. - Rulează
twentyhq/twenty/.github/actions/install-twenty-app@mainastfel încât versiunea nou implementată să fie instalată în spațiul de lucru țintă.
Valoarea implicită a
TWENTY_DEPLOY_URL, http://localhost:2020, este un substituent —
nu va putea accesa nimic dintr-un runner găzduit de GitHub. Actualizează-l la URL-ul public al
serverului tău (sau folosește un runner self-hosted cu acces la rețea) înainte
de a activa CD.deploy la un pull request. Condiția if: din cd.yml va rula jobul pentru acel PR folosind commitul head al PR-ului, permițându-ți să validezi o modificare pe serverul țintă înainte de a face merge.
Publicare — publish.yml
Publică aplicația pe npm, cu proveniență, când împingi un tag de versiune (de ex. v1.0.0) sau când rulezi manual fluxul de lucru din fila Actions.
Ce face:
- Face checkout al aplicației tale, configurează Node.js și actualizează npm (publicarea de încredere necesită npm 11.5.1 sau o versiune ulterioară).
- Instalează CLI-ul independent fixat în pasul Install Twenty CLI, apoi instalează dependențele aplicației cu
yarn install --immutable. - Rulează
twenty app publish, care compilează și împachetează un snapshot izolat al aplicației, apoi îl publică în npm. În CI adaugă automat--provenanceși--access public, astfel încât nu sunt necesare flaguri în fluxul de lucru.
publish.yml (vezi documentația npm trusted publishing). Publicarea cu proveniență certifică ce depozit GitHub a construit pachetul. După publicare, revendică proprietatea în Twenty.
npm acceptă doar proveniență din depozite sursă publice. Dacă publici dintr-un depozit privat, npm respinge pachetul de proveniență OIDC cu un Fără proveniență GitHub, pachetul nu poate fi revendicat prin Revendică cu GitHub. Folosește un depozit public cu proveniență dacă ai nevoie de acest flux de proprietate.
E422 ... Eroare „Unsupported GitHub Actions source repository visibility: "private".”. Pentru a publica dintr-un depozit privat, renunță la proveniență setând TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true' în env al etapei de publicare (un indiciu comentat este inclus în fișierul generat publish.yml):Fixarea versiunii CLI-ului
Toate cele trei fluxuri de lucru generate fixează CLI-ul independent la versiunea detwenty care a rulat twenty app init. Pașii Install Twenty CLI din ci.yml și publish.yml folosesc npm install -g twenty@\<version>. În cd.yml, atât acțiunile de implementare, cât și cele de instalare primesc aceeași versiune prin intrarea lor cli-version.
Pentru actualizare, actualizează împreună cele două comenzi de instalare și ambele intrări cli-version. Aceste fixări sunt separate de versiunea de server TWENTY_VERSION utilizată în CI și de referințele la acțiuni reutilizabile de mai jos.
Fixarea acțiunilor reutilizabile
Fluxurile de lucruci.yml și cd.yml fac referire la acțiuni reutilizabile la @main, astfel încât actualizările acțiunilor din repo-ul twentyhq/twenty sunt preluate automat. Dacă dorești builduri deterministe, înlocuiește @main cu un SHA de commit sau cu un tag de release pe fiecare linie uses:.
Publicarea pe npm
Publicarea pe npm face ca aplicația ta să fie eligibilă pentru marketplace-ul Twenty. După sincronizarea catalogului și orice setare necesară a rutelor de server, spațiile de lucru o pot răsfoi, instala și actualiza din interfață după ce trece de evaluarea Marketplace.Cerințe
- Un cont npm
- Cuvântul cheie
twenty-appdin array-ulkeywordsal fișieruluipackage.json(adaugă-l manual — nu este inclus în mod implicit în șablonultwenty app init)
Metadate pentru marketplace
ConfigurațiadefineApplication() acceptă câmpuri opționale care controlează modul în care aplicația ta apare în marketplace. Folosește logo și galleryImages pentru a face referire la imaginile din folderul public/:
src/application-config.ts
author, category, aboutDescription, websiteUrl, termsUrl, etc.).
Dimensiuni recomandate pentru imaginile din galerie
Marketplace-ul redăgalleryImages într-un container fix cu raport 8:5 (de exemplu, 1600×1000 px).
Imaginile din galerie cu orice raport de aspect sunt afișate integral și nu sunt niciodată
decupate, însă orice imagine semnificativ mai înaltă sau mai îngustă decât
8:5 va afișa
benzi goale pe laterale.Limită de dimensiune pentru imagini
Fișierullogo și fiecare fișier din galleryImages nu trebuie să depășească 10 MB. Fișierele mai mari sunt omise atunci când marketplace-ul re-găzduiește resursele tale publicate, astfel că nu vor fi afișate.
Publicare
beta sau next):
Cum funcționează descoperirea în marketplace
Serverul Twenty sincronizează catalogul marketplace-ului din registrul npm la fiecare oră. CLI-ul independent nu are nicio comandă de sincronizare a catalogului. Așteaptă sincronizarea catalogului de pe server sau folosește instrumentele de administrare ale serverului. Metadatele afișate în marketplace provin din configurațiadefineApplication() — vezi secțiunea Metadate pentru marketplace de mai sus.
Dacă aplicația ta nu definește un
aboutDescription în defineApplication(), piața va folosi automat fișierul README.md al pachetului tău de pe npm drept conținut pentru pagina Despre. Acest lucru înseamnă că poți menține un singur README atât pentru npm, cât și pentru piața Twenty. Dacă vrei o descriere diferită în piață, setează explicit aboutDescription.Fila Despre afișează numai text Markdown. Imaginile nu se afișează, indiferent dacă folosesc sintaxa Markdown sau etichete <img>, iar HTML-ul brut, cum ar fi insignele sau blocurile \<div align="center">, apare ca text simplu.Publicare CI
Fluxul de lucru generatpublish.yml descris mai sus publică automat pe npm la etichetele de versiune, cu provenance. Deoarece twenty app publish adaugă --provenance și --access public pentru tine când rulează în CI, fluxul de lucru nu are nevoie de flaguri npm — doar de configurarea unică a editorului de încredere.
Pentru alte sisteme CI (GitLab CI, CircleCI etc.), rulează yarn install, apoi twenty app publish. Provenance este emisă atunci când mediul poate genera un token OIDC și este omisă automat în caz contrar.
npm provenance adaugă o insignă de încredere la listarea ta în npm, permițând utilizatorilor
să verifice că pachetul a fost construit dintr-un commit specific într-un pipeline CI public.
Este, de asemenea, ceea ce îți permite să revendici proprietatea asupra aplicației tale într-un marketplace Twenty.
Vezi documentația npm provenance
pentru detalii.
Revendicarea aplicației tale
Revendicarea atribuie înregistrarea aplicației tale spațiului de lucru Twenty care o va gestiona. Revendicarea aplicațiilor este disponibilă pentru toate spațiile de lucru. Rolul dvs. are nevoie de permisiunile Aplicații spațiu de lucru și Dezvoltatori pentru a revendica prin fila Aplicații din Setări > Dezvoltatori. Proprietatea este per instanță Twenty: revendicarea pe Twenty Cloud nu revendică aplicația pe un server separat auto-găzduit. Alte spații de lucru din aceeași instanță instalează aplicația ta fără să o revendice ele însele.Înainte de revendicare
- Publică-ți pachetul dintr-un depozit GitHub public folosind GitHub Actions și publicarea de încredere npm cu proveniență. Versiunea importată în catalogul Twenty trebuie să conțină atestarea de proveniență.
- Include cuvântul-cheie
twenty-appînpackage.jsonși așteaptă sincronizarea catalogului. - Alege spațiul de lucru care va deține aplicația. Pentru aplicațiile cu rute de server, acest spațiu de lucru rulează și plătește, de asemenea, pentru rezolvatorul partajat.
- Conectează-te la GitHub ca contul personal care deține depozitul sursă sau ca proprietar al organizației care îl deține. Accesul de colaborator la depozit sau accesul de responsabil de întreținere al pachetului npm, luate separat, nu sunt suficiente.
Revendicați cu GitHub
- În spațiul de lucru al proprietarului dorit, accesează Settings > Developers > Apps (
/settings/developers#apps). - În Revendică o aplicație, introdu numele exact al pachetului npm, inclusiv domeniul său (de exemplu,
@your-org/twenty-app), sauuniversalIdentifieral aplicației. - Fă clic pe Caută și verifică dacă rezultatul este aplicația ta. Dacă nu este găsită, fă clic pe Sincronizează catalogul, dacă este disponibil, așteaptă finalizarea sincronizării, apoi caut-o din nou.
- Fă clic pe Revendică cu GitHub și autorizează Twenty. Pentru un depozit deținut de o organizație, acordă acces organizației respective în secțiunea Acces la organizație din GitHub. Depozitele personale nu necesită acordarea accesului unei organizații.
- Când revii în Twenty, confirmă că aplicația apare în Aplicațiile mele cu tipul NPM. Deschide-o și verifică Distribuire > Proprietate pentru Revendicată de acest spațiu de lucru.
Configurarea rutelor de server
O rută de server primește evenimente pentru mai multe spații de lucru la o singură adresă URL. Rezolvatorul său rulează în spațiul de lucru proprietar al înregistrării, apoi distribuie activitatea către spațiul de lucru instalat corespunzător.- Deschide aplicația în Aplicațiile mele și completează toate Variabilele de server necesare în fila Configurare.
- În Distribuire, fă clic pe Vezi în marketplace pentru a deschide pagina aplicației și a o instala în spațiul de lucru proprietar. Poți deschide această pagină chiar înainte ca aplicația să apară în căutarea din marketplace.
- Înregistrează adresa URL a webhookului de server la furnizorul tău și testează un eveniment dintr-un al doilea spațiu de lucru în care aplicația este instalată. Verifică jurnalele atât ale rezolvatorului, cât și ale funcției-țintă.
Costurile și disponibilitatea spațiului de lucru proprietar
Consultă modul în care sunt contorizate rulările funcțiilor logice pentru consumul de credite, prețuri și spațiul de lucru facturat. Dezinstalarea aplicației din spațiul de lucru proprietar sau ștergerea acelui spațiu de lucru elimină rezolvatorul partajat și întrerupe webhookurile de server pentru fiecare instalare din acea instanță.Proprietatea după mutarea unui depozit
Mutarea depozitului GitHub în alt cont personal sau organizație nu transferă și nu elimină o revendicare Twenty existentă. Înregistrarea rămâne atașată spațiului său de lucru proprietar. Păstrează același pachet npm și acelașiuniversalIdentifier al aplicației; schimbarea spațiului de lucru proprietar Twenty necesită un transfer separat de proprietate.
Depanarea unei revendicări
Dacă întâmpini probleme la revendicarea aplicației tale, contactează-ne pe Discord sau deschide o problemă GitHub.Configurarea revendicării GitHub auto-găzduite
Configurarea revendicării GitHub auto-găzduite
Administratorul serverului configurează
APP_CLAIM_GITHUB_CLIENT_ID și
APP_CLAIM_GITHUB_CLIENT_SECRET cu o aplicație GitHub OAuth. Setează URL-ul de callback pentru
autorizare la SERVER_URL urmat de
/application-registration-claim/github/callback, de exemplu
https://twenty.example.com/application-registration-claim/github/callback.
Această configurare este deja gestionată pentru tine pe Twenty Cloud.Vizibilitate și evaluare în Marketplace
Fiecare aplicație listată în Marketplace a trecut de evaluarea Twenty privind securitatea și calitatea. O aplicație publicată recent rămâne nelistată până trece de evaluarea Marketplace; revendicarea stabilește proprietatea, dar nu o listează. O aplicație nelistată poate fi totuși instalată. În Setări > Aplicații > Marketplace, deschideți filtrul și activați Afișează aplicațiile nelistate sau partajați pagina de instalare directă a aplicației folosind Aplicațiile mele > aplicația dvs. > Distribuire > Copiere link de partajare. Spațiile de lucru văd un avertisment că aplicația nu a fost evaluată de Twenty. Dacă aplicația dvs. este listată, dar încă lipsește din Marketplace, confirmați că sincronizarea catalogului s-a finalizat, că toate variabilele de server necesare sunt completate și că orice setare a rutelor de server este finalizată.Instalarea aplicațiilor
După ce o aplicație este publicată (npm) sau implementată (tarball), spațiile de lucru o pot instala prin interfața utilizatorului (UI). Mergi la pagina Setări > Aplicații din Twenty, unde pot fi parcurse și instalate atât aplicațiile din marketplace, cât și cele implementate prin tarball. Din directorul aplicației, instalează versiunea sa publicată în spațiul de lucru țintă:--universal-identifier \<id>.
Serverul impune versionarea semver la instalare, reflectând regulile de la deploy:
- Instalarea aceleiași versiuni care este deja instalată în spațiul tău de lucru este respinsă cu o eroare
APP_ALREADY_INSTALLED. - Instalarea unei versiuni mai mici decât cea instalată în prezent este respinsă cu o eroare
CANNOT_DOWNGRADE_APPLICATION.
twenty app install --remote production.