manage-app

使用する場面

ユーザーが既存の Twenty アプリを操作、トラブルシューティング、またはリリースしたい場合に、このスキルを選択してください。「アプリはある」という段階から「本番環境で稼働している」段階までが対象です。よくある例：

• 「アプリの変更をサーバーに同期して」
• 「Twenty アプリを本番環境にデプロイして」
• 「ロジック関数のログを確認して」
• 「別の Twenty リモート／インスタンスに切り替えて」
• 「ステージング用の新しいリモートを追加して」
• 「Twenty アプリ用の CI/CD を設定して」
• 「失敗したデプロイ／同期／ビルドをトラブルシューティングして」
• 「本番環境からアプリをアンインストールして」
• 「Twenty アプリのテストを実行して」
• 「テスト用にロジック関数を手動で実行して」

アプリのスキャフォールディングにはこのスキルを使用しないでください（create-app を使用）。アプリのエンティティやコードの変更には使用しないでください（develop-app を使用）。マーケットプレイス用アセットの準備には使用しないでください（publish-app を使用）。ワークスペースのレコードのクエリには使用しないでください（use-twenty-mcp を使用）。

適用範囲

Twenty アプリの仕組み（SDK パッケージ、リモート、同期のライフサイクル、レンダリングモデル）の背景については、../../references/concepts/how-apps-work.md を読んでください。あらゆる Twenty アプリのタスクに適用されるスキル横断の運用ルールは、../../references/concepts/operating-rules.md に記載されています。これらは権威あるルールであり、各スキルで繰り返し説明されていません。

ここでは新しいアプリをスキャフォールディングしないでください。アプリが存在しない場合は $create-app を使用してください。

ここではアプリのエンティティを追加または変更しないでください。オブジェクト、フィールド、ロジック関数、ロール、ビュー、ナビゲーション、ページレイアウト、スキル、エージェント、接続プロバイダー、フロントコンポーネントの登録、設定メニュー項目には $develop-app を使用してください。

ここではマーケットプレイス用の README、スクリーンショット、ロゴ、npm 掲載文を準備しないでください。公開掲載に関する作業には $publish-app を使用してください。

ここでは CRM レコードを取得しないでください。ワークスペースデータの取得には $use-twenty-mcp を使用してください。

運用ルール

まず、現在のディレクトリが Twenty アプリであることを確認してください。

test -f package.json
test -f src/application-config.ts

運用コマンドを実行する前に、現在のアプリとスクリプトを確認してください。

sed -n '1,220p' package.json
twenty remote list

デプロイ、アンインストール、本番リモートの変更、本番環境への同期は、外部から確認できる操作として扱ってください。対象が本番環境である場合、またはユーザーデータに影響する可能性がある場合は、実行前に明示的な確認を求めてください。

コマンドの詳細、リモート、検証コマンドのセマンティクス、同期モード、トラブルシューティング、ビルド、デプロイ、ログ、exec、CI/CD については、../../references/manage-app/cli-and-sync.md を読んでください。

ユーザーからテストの実行を依頼された場合は、テストコマンドを実行する前に ../../references/develop-app/tests.md も読んでください。テストスイート全体には、対象サーバーへのアプリのインストールとアンインストールを行う統合テストが含まれます。そのため、分離されたテストインスタンスを起動または確認したうえで、次を実行してください。

docker start twenty-app-dev-test
TWENTY_API_URL=http://localhost:2021 yarn test

ユーザーがその対象を明示的に指定しない限り、http://localhost:2020 の開発インスタンスに対して統合テストを実行しないでください。ユーザーがユニットテストのみを依頼した場合は、パッケージのユニットテスト用スクリプトを使用してください。TWENTY_API_URL のオーバーライドは不要です。

リモート

リモートとは、アプリを同期またはデプロイできる Twenty サーバーのことです。認証情報はスタンドアロン CLI で管理します。twenty auth login と twenty remote list を使用してください。

よく使われるコマンド：

# Add a remote interactively.
twenty auth login

# Connect to a local Twenty server.
twenty auth login --url http://localhost:2020

# Add a remote non-interactively.
printf '%s' "$TWENTY_API_KEY" | twenty auth login --with-token --url https://your-twenty-server.com --name production

# List configured remotes.
twenty remote list

# Switch the active remote.
twenty remote use <name>

ユーザーが「prod」、「production」、または「workspace de prod」と言った場合は、同期またはデプロイの前に対象のリモートを特定してください。存在しない場合は、--as production またはユーザー指定の名前を付けて追加してください。

開発同期

アプリの変更をアクティブなリモートと同期するには、必ず適用範囲を限定した apply を使用してください。

twenty app apply

単独の twenty app dev は使用しないでください（監視モード）。変更を同期する必要があるたびに、twenty app apply を実行してください。

適用範囲を限定した apply には、認証済みのリモートが必要です。認証に失敗した場合は、再試行する前にリモートを再追加するか、別のリモートに切り替えてください。

トラブルシューティング

まず、どのレイヤーで問題が発生しているかを特定します。

• リモート接続／認証。
• 開発時の同期または範囲を限定した適用。
• ビルド／パッケージの生成。
• デプロイ／アップロード／インストール。
• ランタイムでの関数実行。
• CI/CD 環境またはシークレット。

設定を変更する前に、必要最小限の情報を収集します。

sed -n '1,220p' package.json
sed -n '1,220p' src/application-config.ts
twenty remote list
twenty app apply --json

リモート接続または認証の問題の場合：

• アクティブなリモートが、意図したワークスペースまたはサーバーであることを確認します。
• ローカルの app-dev サーバーでは、twenty auth login --url http://localhost:2020 を再実行します。
• リモートサーバーでは、twenty auth login --url <url> --name <name> を再実行します。
• 接続先の URL を確認するまでは、本番環境のリモートを上書きしないでください。

同期の問題の場合：

• 範囲を限定した失敗を確認するには、twenty app apply --json を優先して使用します。
• アプリのエンティティを編集する前に、生成された型またはスキーマのエラーを確認します。
• アプリが変更されたデータモデルに依存している場合は、$develop-app を使用してエンティティ定義を修正します。

ビルドまたはデプロイの問題の場合：

• twenty app publish --private または twenty app publish を実行する前に、twenty app build を実行します。
• すでにデプロイ済みのアプリを更新する場合は、package.json のバージョンを確認します。
• 本番環境が関係する場合は、アクティブなリモートに頼らず、twenty app publish --private --remote <name> で接続先を指定します。

ランタイムの動作に関する問題の場合：

• twenty app logs を使用して、関数の実行ログを確認します。
• twenty app exec --name <function-name> --payload '<json>' を使用して、制御されたペイロードでロジック関数を再現します。

CI/CD の失敗の場合：

• .github/workflows/ を確認します。
• TWENTY_DEPLOY_URL が、ランナーから到達可能なサーバーを指していることを確認します。
• TWENTY_DEPLOY_API_KEY がソースにコミットされておらず、シークレットとして設定されていることを確認します。

ビルドとデプロイ

ユーザーがリリースの準備状況を尋ねた場合、またはパッケージの問題をデバッグする場合は、デプロイ前にビルドします。

twenty app build

アプリを npm に公開するか、設定済みの Twenty サーバーのレジストリに非公開で公開します。

twenty app publish
twenty app publish --private --remote production
twenty app install --remote production

更新をデプロイする前に、package.json の version が、現在デプロイされているバージョンよりも厳密に大きいセマンティックバージョンであることを確認します。同じバージョンの再デプロイは拒否されます。非公開で公開した後、対象のワークスペースで使用する場合は、twenty app install でデプロイ済みのバージョンをインストールします。

ユーザーが npm マーケットプレイスへの公開、掲載文、スクリーンショット、または公開アプリストアのメタデータを求めている場合は、代わりに $publish-app を使用します。

ログ、実行、クリーンアップ

接続先サーバーのランタイム動作をデバッグする場合は、関数のログを使用します。

twenty app logs
twenty app logs --name <function-name>

トリガーを使わずに動作をテストする場合は、ロジック関数を手動で実行します。

twenty app exec --name <function-name>
twenty app exec --name <function-name> --payload '{"key":"value"}'

確認後にのみアンインストールします。

twenty app uninstall
twenty app uninstall --yes

CI/CD

twenty app init で生成されたアプリでは、CI と CD に GitHub Actions を使用できます。デプロイを自動化する場合は、アプリの .github/workflows/ ファイルを確認し、次の項目を設定します。

• TWENTY_DEPLOY_URL
• TWENTY_DEPLOY_API_KEY

ソースファイルに API キーを記載しないでください。リポジトリまたは CI のシークレットストアを使用します。