Veröffentlichen

Veröffentlichen Sie Ihre Twenty-App auf dem Twenty-Marktplatz oder stellen Sie sie intern bereit.

​

Übersicht

Sobald Ihre App lokal gebaut und getestet wurde, haben Sie zwei Möglichkeiten, sie zu verteilen:

• Einen Tarball bereitstellen — Laden Sie Ihre App direkt auf einen bestimmten Twenty-Server für die interne oder private Nutzung hoch.
• Auf npm veröffentlichen — führen Sie Ihre App im Twenty-Marktplatz auf, damit jeder Arbeitsbereich sie entdecken und installieren kann.

Beide Pfade beginnen mit demselben Build-Schritt.

​

Erstellen Ihrer App

Führen Sie den Build-Befehl aus, um Ihre App zu kompilieren und eine distributionsfertige manifest.json zu erzeugen:

yarn twenty dev:build

Dabei werden TypeScript-Quelltexte kompiliert, Logikfunktionen und Frontend-Komponenten transpiliert und alles in .twenty/output/ geschrieben. Fügen Sie --tarball hinzu, um zusätzlich ein .tgz-Paket für die manuelle Verteilung oder den Publish-Befehl zu erzeugen.

​

Bereitstellung auf einem Server (Tarball)

Für Apps, die Sie nicht öffentlich verfügbar machen möchten — proprietäre Tools, ausschließlich für Unternehmen bestimmte Integrationen oder experimentelle Builds — können Sie einen Tarball direkt auf einem Twenty-Server bereitstellen.

​

Voraussetzungen

Bevor Sie bereitstellen, benötigen Sie ein konfiguriertes Remote, das auf den Zielserver zeigt. Remotes speichern die Server-URL und Anmeldeinformationen lokal in ~/.twenty/config.json.

Ein Remote hinzufügen:

yarn twenty remote:add --url https://your-twenty-server.com --as production

​

Bereitstellen

Bauen und laden Sie Ihre App in einem Schritt auf den Server hoch:

yarn twenty app:publish --private
# To deploy to a specific remote:
# yarn twenty app:publish --private --remote production

​

Eine bereitgestellte App freigeben

Das Teilen privater (Tarball-)Apps über Arbeitsbereiche hinweg ist eine Enterprise-Funktion. Die Registerkarte Distribution zeigt anstelle der Freigabeoptionen eine Aufforderung zum Upgrade an, bis Ihr Arbeitsbereich über einen gültigen Enterprise-Schlüssel verfügt. Gehen Sie zu Einstellungen > Admin-Panel > Enterprise, um es zu aktivieren.

Tarball-Apps werden nicht im öffentlichen Marktplatz gelistet, daher entdecken andere Arbeitsbereiche auf demselben Server sie nicht durch Stöbern. Sobald sich Ihr Arbeitsbereich im Enterprise-Plan befindet, können Sie eine bereitgestellte App wie folgt freigeben:

1. Gehen Sie zu Einstellungen > Anwendungen > Registrierungen und öffnen Sie Ihre App
2. Klicken Sie in der Registerkarte Distribution auf Freigabelink kopieren
3. Teilen Sie diesen Link mit Nutzern in anderen Arbeitsbereichen — er führt sie direkt zur Installationsseite der App

Der Freigabelink verwendet die Basis-URL des Servers (ohne Workspace-Subdomain), sodass er für jeden Arbeitsbereich auf dem Server funktioniert.

​

Versionsverwaltung

Beim Aktualisieren einer bereits bereitgestellten Tarball-App verlangt der Server, dass die version in package.json strikt höher (gemäß der semver-Reihenfolge) ist als die derzeit bereitgestellte Version. Das erneute Bereitstellen derselben Version oder das Pushen einer niedrigeren Version wird abgelehnt, bevor das Tarball gespeichert wird — in der CLI wird ein VERSION_ALREADY_EXISTS-Fehler angezeigt.

So veröffentlichen Sie ein Update:

1. Erhöhen Sie das Feld version in Ihrer package.json (z. B. 1.2.3 → 1.2.4, 1.3.0 oder 2.0.0).
2. Führen Sie yarn twenty app:publish --private aus (oder yarn twenty app:publish --private --remote production)
3. Arbeitsbereiche, in denen die App installiert ist und bei denen die automatische Aktualisierung (im Tab „Einstellungen“ der App) aktiviert wurde, werden im Hintergrund automatisch aktualisiert; bei den anderen wird die Aktualisierung in deren Einstellungen als verfügbar angezeigt

Pre-Release-Tags funktionieren wie erwartet: Das Erhöhen von 1.0.0-rc.1 → 1.0.0-rc.2 ist zulässig, und eine finale Version wie 1.0.0 wird korrekt als höher als 1.0.0-rc.5 erkannt. Die Version in package.json muss selbst eine gültige semver-Zeichenfolge sein.

​

Kompatibilität der Serverversionen

Wenn Ihre App eine Funktion verwendet, die in einer bestimmten Twenty-Serverversion eingeführt wurde (z. B. OAuth-Anbieter, die in v2.3.0 hinzugefügt wurden), sollten Sie die minimale Serverversion, die Ihre App benötigt, mithilfe des Felds engines.twenty in package.json angeben:

{
  "name": "twenty-my-app",
  "version": "1.0.0",
  "engines": {
    "node": "^24.5.0",
    "twenty": ">=2.3.0"
  }
}

Der Wert ist ein standardmäßiger semver-Bereich. Häufige Muster:

Bereich	Bedeutung
>=2.3.0	Jeder Server ab 2.3.0
>=2.3.0 \<3.0.0	2.3.0 oder höher, aber unter der nächsten Hauptversion
^2.3.0	Entspricht >=2.3.0 \<3.0.0

Was bei Bereitstellung und Installation passiert:

• Wenn engines.twenty gesetzt ist und die Version des Zielservers den Bereich nicht erfüllt, wird die Bereitstellung (Tarball-Upload) oder Installation mit dem Fehler SERVER_VERSION_INCOMPATIBLE abgelehnt, zusammen mit einer Meldung, die sowohl den erforderlichen Bereich als auch die tatsächliche Serverversion angibt.
• Wenn engines.twenty nicht gesetzt ist, wird die App auf jeder Serverversion akzeptiert (abwärtskompatibel mit bestehenden Apps).
• Wenn auf dem Server keine APP_VERSION konfiguriert ist, wird die Prüfung übersprungen.

Der Server ist die maßgebliche Prüfinstanz — er validiert engines.twenty sowohl beim Tarball-Upload als auch bei der Workspace-Installation. Auch wenn Sie einen Tarball außerhalb des regulären Prozesses bereitstellen oder aus dem Marktplatz installieren, erzwingt der Server weiterhin die Kompatibilität.

​

Automatisiertes CI/CD (vorgefertigte Workflows)

Apps, die mit create-twenty-app erzeugt wurden, enthalten von Haus aus drei GitHub-Actions-Workflows unter .github/workflows/. CI läuft ohne Einrichtung, CD erfordert ein einziges Secret, und das Veröffentlichen auf npm erfordert eine einmalige Einrichtung als npm Trusted Publisher.

​

CI — ci.yml

Führt Ihre Integrationstests bei jedem Push auf main und bei Pull Requests aus.

Was sie macht:

1. Checkt den Quellcode Ihrer App aus.
2. Startet eine isolierte Twenty-Testinstanz mithilfe der Composite-Action twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main (das CI-Äquivalent zu yarn twenty docker:start --test).
3. Aktiviert Corepack, richtet Node.js anhand Ihrer .nvmrc ein und installiert Abhängigkeiten mit yarn install --immutable.
4. Führt yarn test aus und übergibt TWENTY_API_URL und TWENTY_API_KEY aus der gestarteten Instanz, damit Ihre Tests mit einem echten Server kommunizieren können.

Konfigurationsoptionen:

• TWENTY_VERSION (env, standardmäßig latest) — fixieren Sie die in CI verwendete Twenty-Server-Version, indem Sie dies in ci.yml anpassen.
• Die Parallelität wird nach github.ref gruppiert und bricht laufende Ausführungen bei neuen Pushes ab.

Es sind keine Secrets erforderlich — die Testinstanz ist flüchtig und existiert nur für die Dauer des Jobs.

​

CD — cd.yml

Stellt Ihre App bei jedem Push auf main auf einem konfigurierten Twenty-Server bereit und optional aus einem Pull Request, wenn das Label deploy gesetzt ist.

Was sie macht:

1. Checkt den PR-Head (bei PRs mit Label) oder den gepushten Commit aus.
2. Führt twentyhq/twenty/.github/actions/deploy-twenty-app@main aus — das CI-Äquivalent zu yarn twenty app:publish --private.
3. Führt twentyhq/twenty/.github/actions/install-twenty-app@main aus, damit die neu bereitgestellte Version in den Ziel-Workspace installiert wird.

Erforderliche Konfiguration:

Einstellung	Wo	Zweck
TWENTY_DEPLOY_URL	env in cd.yml (standardmäßig http://localhost:3000)	Der Twenty-Server, auf den bereitgestellt werden soll. Ändern Sie dies vor der ersten Verwendung auf die echte Server-URL.
TWENTY_DEPLOY_API_KEY	GitHub-Repository Settings → Secrets and variables → Actions	API-Schlüssel mit Berechtigung zum Bereitstellen auf dem Zielserver.

Der Standardwert von TWENTY_DEPLOY_URL (http://localhost:3000) ist ein Platzhalter — von einem GitHub-gehosteten Runner ist er nicht erreichbar. Aktualisieren Sie sie auf die öffentliche URL Ihres Servers (oder verwenden Sie einen selbstgehosteten Runner mit Netzwerkzugriff), bevor Sie CD aktivieren.

Eine Vorschau-Bereitstellung aus einem PR auslösen:

Fügen Sie einem Pull Request das Label deploy hinzu. Die if:-Bedingung in cd.yml führt den Job für diesen PR mit dem Head-Commit des PR aus, sodass Sie eine Änderung auf dem Zielserver vor dem Mergen validieren können.

​

Veröffentlichen — publish.yml

Veröffentlicht Ihre App mit Herkunftsnachweis auf npm, wenn Sie ein Versions-Tag pushen (z. B. v1.0.0), oder wenn Sie den Workflow manuell über den Actions-Tab ausführen.

Was sie macht:

1. Checken Sie Ihre App aus, richten Sie Node.js ein und aktualisieren Sie npm (Trusted Publishing erfordert npm 11.5.1 oder neuer).
2. Führt yarn twenty app:publish aus, wodurch die App gebaut und .twenty/output auf npm veröffentlicht wird. In CI werden automatisch --provenance und --access public hinzugefügt, sodass im Workflow keine Flags benötigt werden.

Einmalige Einrichtung:

Öffnen Sie auf npmjs.com Ihr Paket > Settings → Trusted Publisher und registrieren Sie dieses Repository mit dem publish.yml-Workflow (siehe die npm trusted publishing docs). Das Veröffentlichen mit Provenance bestätigt, welches GitHub-Repository das Paket gebaut hat; zugleich beanspruchen Sie damit die Inhaberschaft Ihrer App in einem Twenty-Marktplatz.

npm akzeptiert Herkunftsnachweise nur aus öffentlichen Quellcode-Repositories. Wenn du aus einem privaten Repository veröffentlichst, weist npm das OIDC-Provenance-Bundle mit einem E422 Unsupported GitHub Actions source repository visibility: "private"-Fehler. Um aus einem privaten Repository zu veröffentlichen, deaktiviere Herkunftsnachweise, indem du TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true' im env-Block des Veröffentlichungs-Schritts setzt (ein auskommentierter Hinweis ist in der generierten publish.yml enthalten):

      - name: Publish to npm
        env:
          TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
        run: yarn twenty app:publish

​

Fixieren der wiederverwendbaren Actions

Die Workflows ci.yml und cd.yml verweisen auf wiederverwendbare Actions mit @main, sodass Aktualisierungen der Actions im Repository twentyhq/twenty automatisch übernommen werden. Wenn Sie deterministische Builds möchten, ersetzen Sie @main in jeder uses:-Zeile durch eine Commit-SHA oder einen Release-Tag.

​

Auf npm veröffentlichen

Die Veröffentlichung auf npm macht Ihre App im Twenty-Marktplatz auffindbar. Jeder Twenty-Arbeitsbereich kann Marktplatz-Apps direkt über die Benutzeroberfläche durchsuchen, installieren und aktualisieren.

​

Anforderungen

• Ein npm-Konto
• Das Schlüsselwort twenty-app in Ihrem package.json-Array keywords (manuell hinzufügen — es ist in der create-twenty-app-Vorlage standardmäßig nicht enthalten)

{
  "name": "twenty-app-postcard-sender",
  "version": "1.0.0",
  "keywords": ["twenty-app"]
}

​

Marktplatz-Metadaten

Die defineApplication()-Konfiguration unterstützt optionale Felder, die steuern, wie Ihre App im Marktplatz erscheint. Verwende logo und galleryImages um Bilder aus dem public/ Ordner zu referenzieren:

src/application-config.ts

export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  logo: 'public/logo.png',
  galleryImages: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
});

Siehe das defineApplication-Akkordeon auf der Seite Building Apps für die vollständige Liste der Marktplatzfelder (author, category, aboutDescription, websiteUrl, termsUrl usw.).

​

Empfohlene Galerieabmessungen

Der Marktplatz zeigt galleryImages in einem fixen 8:5 Container an (z.B. 1600×1000 px).

Galeriebilder mit beliebigem Seitenverhältnis werden vollständig angezeigt und werden nie zugeschnitten, aber irgendetwas wesentlich höher oder enger als 8:5 wird leere Bands auf den Seiten zeigen.

​

Maximale Bildgröße

Die Datei logo und jede Datei in galleryImages dürfen jeweils 10 MB nicht überschreiten. Größere Dateien werden übersprungen, wenn der Marktplatz deine veröffentlichten Assets erneut hostet, sodass sie nicht angezeigt werden.

​

Veröffentlichen

yarn twenty app:publish

Um unter einem bestimmten dist-tag zu veröffentlichen (z. B. beta oder next):

yarn twenty app:publish --tag beta

​

So funktioniert die Marktplatz-Erkennung

Der Twenty-Server synchronisiert seinen Marktplatzkatalog stündlich aus der npm-Registry.

Sie können die Synchronisierung sofort auslösen, anstatt zu warten:

yarn twenty dev:catalog-sync
# To target a specific remote:
# yarn twenty dev:catalog-sync --remote production

Die im Marketplace angezeigten Metadaten stammen aus deiner defineApplication()-Konfiguration – siehe oben unter Marketplace-Metadaten.

Wenn Ihre App keine aboutDescription in defineApplication() definiert, verwendet der Marktplatz automatisch die README.md Ihres Pakets von npm als Inhalt der Über-uns-Seite. Das bedeutet, dass Sie eine einzige README sowohl für npm als auch für den Twenty-Marktplatz pflegen können. Wenn Sie im Marktplatz eine andere Beschreibung möchten, setzen Sie aboutDescription explizit.

​

CI-Veröffentlichung

Der oben beschriebene, erzeugte publish.yml-Workflow veröffentlicht mit Provenance bei Versions-Tags automatisch auf npm. Da yarn twenty app:publish beim Ausführen in CI --provenance und --access public für Sie hinzufügt, benötigt der Workflow keine npm-Flags – nur die einmalige Trusted-Publisher-Einrichtung.

Für andere CI-Systeme (GitLab CI, CircleCI usw.) führen Sie zuerst yarn install und dann yarn twenty app:publish aus. Provenance wird ausgegeben, wenn die Umgebung ein OIDC-Token erstellen kann, und andernfalls automatisch übersprungen.

npm-Provenance fügt Ihrem npm-Eintrag ein Vertrauensabzeichen hinzu, sodass Nutzer überprüfen können, dass das Paket aus einem bestimmten Commit in einer öffentlichen CI-Pipeline gebaut wurde. Damit können Sie außerdem die Inhaberschaft Ihrer App in einem Twenty-Marktplatz beanspruchen. Siehe die npm-Provenance-Dokumentation für Details.

​

Apps installieren

Sobald eine App veröffentlicht (npm) oder bereitgestellt (Tarball) wurde, können Arbeitsbereiche sie über die Benutzeroberfläche installieren.

Gehen Sie zur Seite Einstellungen > Anwendungen in Twenty, auf der sowohl Marktplatz- als auch per Tarball bereitgestellte Apps durchsucht und installiert werden können.

Sie können Apps auch über die Befehlszeile installieren:

yarn twenty app:install

Der Server erzwingt bei der Installation semver-Versionierung und spiegelt damit die Regeln beim Bereitstellen wider:

• Die Installation derselben Version, die in Ihrem Arbeitsbereich bereits installiert ist, wird mit einem APP_ALREADY_INSTALLED-Fehler abgelehnt.
• Die Installation einer niedrigeren Version als die aktuell installierte wird mit einem CANNOT_DOWNGRADE_APPLICATION-Fehler abgelehnt.

Um eine neuere Version zu installieren, stellen Sie sie zuerst bereit oder veröffentlichen Sie sie und führen Sie dann yarn twenty app:install erneut aus.