公開 - Twenty Documentation

概要

tarball をデプロイ — 内部またはプライベート用途のために、特定の Twenty サーバーにアプリを直接アップロードします。
npm に公開 — Twenty マーケットプレイスにアプリを掲載し、任意のワークスペースが見つけてインストールできるようにします。

どちらの方法も同じビルド手順から始まります。

アプリのビルド

build コマンドを実行してアプリをコンパイルし、配布可能な manifest.json を生成します:

yarn twenty dev:build

これにより、TypeScript ソースがコンパイルされ、ロジック関数とフロントエンドコンポーネントがトランスパイルされ、すべてが .twenty/output/ に書き込まれます。手動配布または公開コマンド用の .tgz パッケージも生成するには、--tarball を追加します。

サーバーへのデプロイ（tarball）

一般公開したくないアプリ（プロプライエタリなツール、エンタープライズ専用の連携、実験的ビルドなど）の場合は、tarball を Twenty サーバーに直接デプロイできます。

前提条件

デプロイ前に、対象サーバーを指すリモートを設定しておく必要があります。リモートは、サーバーの URL と認証情報をローカルの ~/.twenty/config.json に保存します。リモートを追加:

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

デプロイ

アプリをビルドしてサーバーにアップロードするまでを1ステップで実行します:

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

デプロイ済みアプリの共有

プライベート（tarball）アプリをワークスペース間で共有することは、Enterprise の機能です。ワークスペースに有効な Enterprise キーがあるまで、Distribution タブは共有コントロールの代わりにアップグレードのプロンプトを表示します。有効にするには、設定 > 管理パネル > Enterprise に移動します。

tarball アプリは公開マーケットプレイスには掲載されないため、同じサーバー上の他のワークスペースは、ブラウズしてもそれらを見つけられません。ワークスペースが Enterprise プランの場合、デプロイ済みのアプリを次のように共有できます:

設定 > アプリケーション > 登録 に移動して、あなたのアプリを開きます
Distribution タブで、Copy share link をクリックします
このリンクを他のワークスペースのユーザーと共有すると、アプリのインストールページに直接移動できます。

共有リンクはサーバーのベース URL（ワークスペースのサブドメインなし）を使用するため、サーバー上のどのワークスペースでも機能します。

バージョン管理

既にデプロイ済みの tarball アプリを更新する場合、サーバーは、package.json の version が、現在デプロイされているバージョンよりも 厳密に大きい (semver の順序に従って) ことを要求します。同じバージョンを再デプロイする、またはそれより低いバージョンをプッシュする操作は、tarball が保存される前に拒否されます—CLI から VERSION_ALREADY_EXISTS エラーが表示されます。アップデートをリリースするには:

package.json の version フィールドを更新してください（例：1.2.3 → 1.2.4、1.3.0、または 2.0.0）
yarn twenty app:publish --private（または yarn twenty app:publish --private --remote production）を実行します。
アプリがインストールされ、「Settings」タブで自動アップグレードが有効になっているワークスペースは、バックグラウンドで自動的にアップグレードされます。それ以外のワークスペースでは、設定内で利用可能なアップグレードが表示されます。

プレリリースタグは期待どおりに動作します。1.0.0-rc.1 → 1.0.0-rc.2 への引き上げは許可され、1.0.0 のような最終リリースは 1.0.0-rc.5 よりも高いバージョンとして正しく認識されます。 package.json のバージョンは、それ自体が有効な semver 文字列でなければなりません。

サーバーバージョンの互換性

特定の Twenty サーバーバージョンで導入された機能（例: v2.3.0 で追加された OAuth プロバイダー）をアプリで使用している場合、package.json の engines.twenty フィールドを使用して、アプリが必要とする最小サーバーバージョンを宣言してください:

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

値は標準的な SemVer の範囲です。よくあるパターン:

範囲	意味
`>=2.3.0`	2.3.0 以降のどのサーバーでも
`>=2.3.0 \<3.0.0`	2.3.0 以上（次のメジャーバージョン未満）
`^2.3.0`	`>=2.3.0 \<3.0.0` と同じ

デプロイ時とインストール時に起こること:

engines.twenty が設定されていて、ターゲットサーバーのバージョンがその範囲を満たさない場合、デプロイ（tarball のアップロード）またはインストールは SERVER_VERSION_INCOMPATIBLE エラーと、要求される範囲と実際のサーバーバージョンの双方を示すメッセージとともに拒否されます。
engines.twenty が未設定の場合、アプリはどのサーバーバージョンでも受け入れられます（既存のアプリとの後方互換性）。
サーバーで APP_VERSION が設定されていない場合、このチェックはスキップされます。

サーバーが最終的な判定を行い、tarball のアップロードとワークスペースへのインストールの両方で engines.twenty を検証します。 tarball を別経路でデプロイする場合やマーケットプレイスからインストールする場合でも、サーバーは互換性を引き続き強制します。

自動化された CI/CD（スキャフォールド済みのワークフロー）

create-twenty-app で生成されたアプリには、.github/workflows/ 配下に GitHub Actions のワークフローが 3 つ、最初から同梱されています。 CI はセットアップ不要で実行でき、CD には 1 つのシークレットを設定するだけでよく、npm への公開には 1 回だけの npm trusted-publisher セットアップが必要です。

CI — `ci.yml`

main へのプッシュやプルリクエストのたびに、統合テストを自動実行します。 機能:

アプリのソースをチェックアウトします。
twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main 複合アクションを使って、分離された Twenty のテスト用インスタンスを起動します（yarn twenty docker:start --test の CI 版）。
Corepack を有効化し、.nvmrc に基づいて Node.js をセットアップし、yarn install --immutable で依存関係をインストールします。
yarn test を実行し、起動したインスタンスから TWENTY_API_URL と TWENTY_API_KEY を渡すことで、テストが実サーバーと通信できるようにします。

設定項目:

TWENTY_VERSION（env、デフォルトは latest）— ci.yml でこれを編集して、CI で使用する Twenty サーバーのバージョンを固定します。
同時実行は github.ref 単位でグループ化され、新しいプッシュ時に進行中の実行をキャンセルします。

シークレットは不要です。テスト用インスタンスは一時的で、ジョブの実行中のみ存続します。

CD — `cd.yml`

main へのプッシュのたびに、設定済みの Twenty サーバーへアプリをデプロイします。また、deploy ラベルが付与されたプルリクエストからのデプロイにも対応します（任意）。 機能:

（ラベル付き PR の場合は）PR のヘッド、またはプッシュされたコミットをチェックアウトします。
twentyhq/twenty/.github/actions/deploy-twenty-app@main を実行します（yarn twenty app:publish --private の CI 版）。
twentyhq/twenty/.github/actions/install-twenty-app@main を実行し、新しくデプロイしたバージョンを対象ワークスペースにインストールします。

必須の設定:

設定	場所	目的
`TWENTY_DEPLOY_URL`	`cd.yml` の `env`（デフォルトは `http://localhost:3000`）	デプロイ先の Twenty サーバー。初回利用前に、実際のサーバーの URL に変更してください。
`TWENTY_DEPLOY_API_KEY`	GitHub リポジトリの Settings → Secrets and variables → Actions	対象サーバーでデプロイ権限を持つ API キー。

デフォルトの TWENTY_DEPLOY_URL（http://localhost:3000）はプレースホルダーであり、GitHub ホストランナーからは到達できません。 CD を有効化する前に、サーバーの公開 URL に更新するか、ネットワークアクセス可能なセルフホストランナーを使用してください。

PR からプレビューデプロイをトリガーする: プルリクエストに deploy ラベルを追加します。 cd.yml の if: ガードにより、その PR のヘッドコミットを使ってジョブが実行され、マージ前に対象サーバー上で変更を検証できます。

公開 — `publish.yml`

バージョンタグ（例: v1.0.0）をプッシュしたとき、または Actions タブからワークフローを手動実行したときに、プロビナンス付きでアプリを npm に公開します。 機能:

あなたのアプリをチェックアウトし、Node.js をセットアップして npm を更新します（信頼できる公開には npm 11.5.1 以降が必要です）。
yarn twenty app:publish を実行します。これによりアプリがビルドされ、.twenty/output が npm に公開されます。 CI 環境では自動的に --provenance と --access public が追加されるため、ワークフロー内でフラグを指定する必要はありません。

一度きりのセットアップ: npmjs.com で自分のパッケージを開き、Settings → Trusted Publisher から、このリポジトリを publish.yml ワークフローで登録します（詳しくは npm trusted publishing docs を参照してください）。 provenance 付きで公開すると、どの GitHub リポジトリがそのパッケージをビルドしたかが証明されます。これは、Twenty マーケットプレイスでアプリの所有権を主張する方法にもなります。

再利用可能なアクションのバージョン固定

ci.yml と cd.yml のワークフローは、@main の再利用可能なアクションを参照しているため、twentyhq/twenty リポジトリでのアクションの更新が自動的に取り込まれます。ビルドを決定的にしたい場合は、各 uses: 行の @main をコミット SHA またはリリースタグに置き換えてください。

npm への公開

npm に公開すると、Twenty マーケットプレイスでアプリが見つけられるようになります。任意の Twenty ワークスペースは、UI からマーケットプレイスのアプリを参照、インストール、およびアップグレードできます。

要件

npm アカウント
package.json の keywords 配列にある twenty-app キーワード（手動で追加してください — create-twenty-app テンプレートにはデフォルトで含まれていません）

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

マーケットプレイスのメタデータ

defineApplication() の設定は、マーケットプレイスでのアプリの表示方法を制御する任意のフィールドをサポートします。 public/ フォルダー内の画像を参照するには、logo と galleryImages を使用します:

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',
  ],
});

マーケットプレイスのフィールド（author、category、aboutDescription、websiteUrl、termsUrl など）の完全な一覧は、Building Apps ページのdefineApplication アコーディオンを参照してください。

推奨されるギャラリー画像のサイズ

マーケットプレイスでは、galleryImages は固定の 8:5 コンテナ内で表示されます（例：1600×1000 px）。

どのようなアスペクト比でもギャラリー画像は全体が表示され、トリミングされることはありません。ただし、8:5 よりも著しく縦長の場合は、左右に空白の帯が表示されます。

画像サイズの上限

logo と各 galleryImages ファイルは 10 MB を超えてはいけません。マーケットプレイスが公開済みアセットを再ホスティングする際、サイズが大きすぎるファイルはスキップされるため、表示されません。

公開

yarn twenty app:publish

特定の dist-tag（例: beta や next）で公開するには:

yarn twenty app:publish --tag beta

マーケットプレイスの検出の仕組み

Twenty サーバーは、npm レジストリからマーケットプレイスのカタログを毎時同期します。待たずにすぐに同期をトリガーできます:

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

マーケットプレイスに表示されるメタデータは、defineApplication() 設定から取得されます。上記の Marketplace metadata を参照してください。

アプリでdefineApplication()内にaboutDescriptionが定義されていない場合、マーケットプレイスはnpm上のパッケージのREADME.mdを概要ページのコンテンツとして自動的に使用します。つまり、npm と Twenty のマーケットプレイスの両方に対して、1 つの README を維持できます。マーケットプレイスで異なる説明文を使用したい場合は、aboutDescription を明示的に設定してください。

CI での公開

上で説明したスキャフォールド済みの publish.yml ワークフローは、バージョンタグが付けられたときに provenance 情報付きで自動的に npm へ公開します。 yarn twenty app:publish は CI で実行される際に --provenance と --access public を自動的に追加するため、ワークフローで npm フラグを指定する必要はありません。一度きりの trusted-publisher セットアップだけが必要です。その他の CI システム（GitLab CI、CircleCI など）の場合は、yarn install を実行してから yarn twenty app:publish を実行します。環境が OIDC トークンを発行できる場合は provenance が生成され、それ以外の場合は自動的にスキップされます。

npm provenance により npm のリスティングにトラストバッジが追加され、公開 CI パイプライン上の特定のコミットからビルドされたパッケージであることをユーザーが検証できるようになります。また、これにより Twenty マーケットプレイスでアプリの所有権を主張できるようになります。詳細は npm provenance のドキュメントを参照してください。

アプリのインストール

アプリが公開（npm）またはデプロイ（tarball）されると、ワークスペースは UI からインストールできます。 Twenty の 設定 > アプリケーション ページに移動すると、マーケットプレイスと tarball でデプロイされたアプリの両方を参照してインストールできます。コマンドラインからアプリをインストールすることもできます:

yarn twenty app:install

サーバーはインストール時に semver によるバージョニングを強制し、デプロイ時の規則を反映しています:

ワークスペースに既にインストールされているものと同じバージョンをインストールしようとすると、APP_ALREADY_INSTALLED エラーで拒否されます。
現在インストールされているものより低いバージョンをインストールしようとすると、CANNOT_DOWNGRADE_APPLICATION エラーで拒否されます。

より新しいバージョンをインストールするには、まずデプロイまたは公開してから、yarn twenty app:install を再実行してください。

​概要

​アプリのビルド

​サーバーへのデプロイ（tarball）

​前提条件

​デプロイ

​デプロイ済みアプリの共有

​バージョン管理

​サーバーバージョンの互換性

​自動化された CI/CD（スキャフォールド済みのワークフロー）

​CI — ci.yml

​CD — cd.yml

​公開 — publish.yml

​再利用可能なアクションのバージョン固定

​npm への公開

​要件

​マーケットプレイスのメタデータ

​推奨されるギャラリー画像のサイズ

​画像サイズの上限

​公開

​マーケットプレイスの検出の仕組み

​CI での公開

​アプリのインストール

概要

アプリのビルド

サーバーへのデプロイ（tarball）

前提条件

デプロイ

デプロイ済みアプリの共有

バージョン管理

サーバーバージョンの互換性

自動化された CI/CD（スキャフォールド済みのワークフロー）

CI — `ci.yml`

CD — `cd.yml`

公開 — `publish.yml`

再利用可能なアクションのバージョン固定

npm への公開

要件

マーケットプレイスのメタデータ

推奨されるギャラリー画像のサイズ

画像サイズの上限

公開

マーケットプレイスの検出の仕組み

CI での公開

アプリのインストール