メインコンテンツへスキップ

​
概要

ローカルでビルドとテストが完了したら、配布方法は次の2通りです:
  • 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 プランの場合、デプロイ済みのアプリを次のように共有できます:
  1. 設定 > アプリケーション > 登録 に移動して、あなたのアプリを開きます
  2. Distribution タブで、Copy share link をクリックします
  3. このリンクを他のワークスペースのユーザーと共有すると、アプリのインストールページに直接移動できます。
共有リンクはサーバーのベース URL（ワークスペースのサブドメインなし）を使用するため、サーバー上のどのワークスペースでも機能します。

​
バージョン管理

既にデプロイ済みの tarball アプリを更新する場合、サーバーは、package.json の version が、現在デプロイされているバージョンよりも 厳密に大きい (semver の順序に従って) ことを要求します。 同じバージョンを再デプロイする、またはそれより低いバージョンをプッシュする操作は、tarball が保存される前に拒否されます—CLI から VERSION_ALREADY_EXISTS エラーが表示されます。 アップデートをリリースするには:
  1. package.json の version フィールドを更新してください（例：1.2.3 → 1.2.4、1.3.0、または 2.0.0）
  2. yarn twenty app:publish --private（または yarn twenty app:publish --private --remote production）を実行します。
  3. アプリをインストールしているワークスペースの設定に、利用可能なアップグレードが表示されます。
プレリリースタグは期待どおりに動作します。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.02.3.0 以降のどのサーバーでも
>=2.3.0 \<3.0.02.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 のワークフローが 2 つ、最初から同梱されています。 リポジトリを GitHub にプッシュするとすぐに実行可能です。CI に追加のセットアップは不要で、CD にはシークレットを 1 つ用意するだけです。

​
CI — ci.yml

main へのプッシュやプルリクエストのたびに、統合テストを自動実行します。 機能:
  1. アプリのソースをチェックアウトします。
  2. twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main 複合アクションを使って、分離された Twenty のテスト用インスタンスを起動します（yarn twenty docker:start --test の CI 版）。
  3. Corepack を有効化し、.nvmrc に基づいて Node.js をセットアップし、yarn install --immutable で依存関係をインストールします。
  4. yarn test を実行し、起動したインスタンスから TWENTY_API_URL と TWENTY_API_KEY を渡すことで、テストが実サーバーと通信できるようにします。
設定項目:
  • TWENTY_VERSION（env、デフォルトは latest）— ci.yml でこれを編集して、CI で使用する Twenty サーバーのバージョンを固定します。
  • 同時実行は github.ref 単位でグループ化され、新しいプッシュ時に進行中の実行をキャンセルします。
シークレットは不要です。テスト用インスタンスは一時的で、ジョブの実行中のみ存続します。

​
CD — cd.yml

main へのプッシュのたびに、設定済みの Twenty サーバーへアプリをデプロイします。また、deploy ラベルが付与されたプルリクエストからのデプロイにも対応します（任意）。 機能:
  1. （ラベル付き PR の場合は）PR のヘッド、またはプッシュされたコミットをチェックアウトします。
  2. twentyhq/twenty/.github/actions/deploy-twenty-app@main を実行します（yarn twenty app:publish --private の CI 版）。
  3. twentyhq/twenty/.github/actions/install-twenty-app@main を実行し、新しくデプロイしたバージョンを対象ワークスペースにインストールします。
必須の設定:
設定場所目的
TWENTY_DEPLOY_URLcd.yml の env（デフォルトは http://localhost:3000）デプロイ先の Twenty サーバー。 初回利用前に、実際のサーバーの URL に変更してください。
TWENTY_DEPLOY_API_KEYGitHub リポジトリの Settings → Secrets and variables → Actions対象サーバーでデプロイ権限を持つ API キー。
デフォルトの TWENTY_DEPLOY_URL（http://localhost:3000）はプレースホルダーであり、GitHub ホストランナーからは到達できません。 CD を有効化する前に、サーバーの公開 URL に更新するか、ネットワークアクセス可能なセルフホストランナーを使用してください。
PR からプレビューデプロイをトリガーする: プルリクエストに deploy ラベルを追加します。 cd.yml の if: ガードにより、その PR のヘッドコミットを使ってジョブが実行され、マージ前に対象サーバー上で変更を検証できます。

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

両方のワークフローは再利用可能なアクションを @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/ フォルダー内の画像を参照するには、logoUrl と screenshots を使用します:
src/application-config.ts
export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  logoUrl: 'public/logo.png',
  screenshots: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
});
マーケットプレイスのフィールド（author、category、aboutDescription、websiteUrl、termsUrl など）の完全な一覧は、Building Apps ページのdefineApplication アコーディオンを参照してください。

​
推奨されるスクリーンショットのサイズ

マーケットプレイスでは、screenshots は固定の 8:5 コンテナ内で表示されます（例：1600×1000 px）。
どのようなアスペクト比でもスクリーンショットは全体が表示され、トリミングされることはありません。ただし、8:5 よりも著しく縦長または横長の場合は、上下または左右に空白の帯が表示されます。

​
公開

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() の設定に由来します。displayName、description、author、category、logoUrl、screenshots、aboutDescription、websiteUrl、termsUrl などのフィールドです。
アプリでdefineApplication()内にaboutDescriptionが定義されていない場合、マーケットプレイスはnpm上のパッケージのREADME.mdを概要ページのコンテンツとして自動的に使用します。 つまり、npm と Twenty のマーケットプレイスの両方に対して、1 つの README を維持できます。 マーケットプレイスで異なる説明文を使用したい場合は、aboutDescription を明示的に設定してください。

​
CI での公開

この GitHub Actions のワークフローを使用すると、各リリース時に自動で公開できます（OIDC を使用）。 
name: Publish
on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          registry-url: https://registry.npmjs.org
      - run: yarn install --immutable
      - run: npx twenty dev:build
      - run: npm publish --provenance --access public
        working-directory: .twenty/output
他の CI システム（GitLab CI、CircleCI など）でも同じ3つのコマンドを使用します: yarn install、yarn twenty dev:build、そして .twenty/output から npm publish を実行します。
npm provenance は任意ですが、推奨されます。 --provenance を付けて公開すると、npm のリスティングにトラストバッジが追加され、公開 CI パイプラインの特定のコミットからビルドされたことをユーザーが検証できるようになります。 セットアップ手順は、npm provenance のドキュメントを参照してください。

​
アプリのインストール

アプリが公開（npm）またはデプロイ（tarball）されると、ワークスペースは UI からインストールできます。 Twenty の 設定 > アプリケーション ページに移動すると、マーケットプレイスと tarball でデプロイされたアプリの両方を参照してインストールできます。 コマンドラインからアプリをインストールすることもできます: 
yarn twenty app:install
サーバーはインストール時に semver によるバージョニングを強制し、デプロイ時の規則を反映しています:
  • ワークスペースに既にインストールされているものと同じバージョンをインストールしようとすると、APP_ALREADY_INSTALLED エラーで拒否されます。
  • 現在インストールされているものより低いバージョンをインストールしようとすると、CANNOT_DOWNGRADE_APPLICATION エラーで拒否されます。
より新しいバージョンをインストールするには、まずデプロイまたは公開してから、yarn twenty app:install を再実行してください。