Публикация

Обзор

После того как ваше приложение собрано и протестировано локально, у вас есть два пути для его распространения:

Разверните tar-архив — загрузите своё приложение напрямую на конкретный сервер Twenty для внутреннего или частного использования.
Опубликовать в npm — разместите ваше приложение в маркетплейсе Twenty, чтобы любое рабочее пространство могло его найти и установить.

Оба пути начинаются с одного и того же шага build.

Сборка вашего приложения

Выполните команду сборки, чтобы скомпилировать приложение и сгенерировать готовый к распространению manifest.json:

yarn twenty dev:build

Это компилирует исходные файлы TypeScript, транспилирует функции логики и фронтенд-компоненты и записывает всё в .twenty/output/. Добавьте --tarball, чтобы также создать пакет .tgz для ручного распространения или для команды publish.

Развертывание на сервер (tarball)

Для приложений, которые вы не хотите делать общедоступными — собственные инструменты, интеграции только для предприятий или экспериментальные сборки — вы можете развернуть tarball напрямую на сервер Twenty.

Требования

Перед развертыванием вам нужен настроенный remote, указывающий на целевой сервер. Remotes локально хранят URL сервера и учётные данные аутентификации в ~/.twenty/config.json. Добавьте remote:

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

Развертывание

Соберите и загрузите ваше приложение на сервер в одном шаге:

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

Общий доступ к развернутому приложению

Совместный доступ к частным приложениям (tarball) между рабочими пространствами — функция уровня Enterprise. Вкладка Distribution будет показывать предложение обновиться вместо элементов управления совместным доступом, пока в вашем рабочем пространстве не будет действительного ключа Enterprise. Перейдите в Настройки > Панель администратора > Enterprise, чтобы включить её.

Приложения в формате tarball не отображаются в публичном маркетплейсе, поэтому другие рабочие пространства на том же сервере не найдут их при просмотре. Как только ваше рабочее пространство перейдёт на тарифный план Enterprise, вы сможете поделиться развёрнутым приложением следующим образом:

Перейдите в Настройки > Приложения > Регистрации и откройте ваше приложение
На вкладке Распространение нажмите Копировать ссылку для общего доступа
Поделитесь этой ссылкой с пользователями в других рабочих пространствах — она ведёт их прямо на страницу установки приложения

Ссылка общего доступа использует базовый URL сервера (без какого-либо поддомена рабочего пространства), поэтому она работает для любого рабочего пространства на сервере.

Управление версиями

При обновлении уже развернутого tarball-приложения сервер требует, чтобы значение version в package.json было строго выше (согласно упорядочиванию по semver), чем текущая развернутая версия. Повторное развёртывание той же версии или публикация более низкой версии отклоняются до сохранения tarball — в CLI вы увидите ошибку VERSION_ALREADY_EXISTS. Чтобы выпустить обновление:

Увеличьте значение поля version в вашем package.json (например: 1.2.3 → 1.2.4, 1.3.0 или 2.0.0).
Выполните yarn twenty app:publish --private (или yarn twenty app:publish --private --remote production)
Рабочие пространства, в которых установлено приложение, увидят доступное обновление в своих настройках

Пререлизные теги работают как ожидается: повышение версии 1.0.0-rc.1 → 1.0.0-rc.2 допускается, а финальный релиз вроде 1.0.0 корректно распознаётся как более высокий, чем 1.0.0-rc.5. Версия в package.json должна сама по себе быть корректной строкой semver.

Совместимость версий сервера

Если ваше приложение использует функцию, появившуюся в конкретной версии сервера Twenty (например, провайдеры OAuth, добавленные в v2.3.0), следует объявить минимальную требуемую версию сервера с помощью поля engines.twenty в package.json:

{
  "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 не задано, проверка пропускается.

Сервер выполняет окончательную проверку — он проверяет engines.twenty как при загрузке tarball-архива, так и при установке в рабочем пространстве. Если вы развёртываете tarball вне стандартного процесса или устанавливаете из маркетплейса, сервер всё равно принудительно проверяет совместимость.

Автоматизированный CI/CD (рабочие процессы, сгенерированные шаблоном)

Приложения, созданные с помощью create-twenty-app, «из коробки» включают два рабочих процесса GitHub Actions в каталоге .github/workflows/. Они готовы к запуску, как только вы запушите репозиторий на GitHub — для CI не требуется дополнительной настройки, а для CD нужен лишь один секрет.

CI — `ci.yml`

Автоматически запускает интеграционные тесты при каждом пуше в main и для каждого pull request. Что делает:

Извлекает исходный код вашего приложения.
Запускает изолированный тестовый экземпляр Twenty с помощью составного действия twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main (эквивалент для CI yarn twenty docker:start --test).
Включает Corepack, настраивает Node.js на основе вашего .nvmrc и устанавливает зависимости с помощью yarn install --immutable.
Запускает yarn test, передавая TWENTY_API_URL и TWENTY_API_KEY из запущенного экземпляра, чтобы ваши тесты могли взаимодействовать с реальным сервером.

Параметры конфигурации:

TWENTY_VERSION (переменная окружения, по умолчанию latest) — зафиксируйте версию сервера Twenty, используемую в CI, отредактировав это значение в ci.yml.
Параллельные запуски группируются по github.ref и отменяют выполняющиеся прогоны при новых пушах.

Секреты не требуются — тестовый экземпляр эфемерен и существует только на время выполнения задания.

CD — `cd.yml`

Разворачивает ваше приложение на настроенном сервере Twenty при каждом пуше в main и, при необходимости, из pull request при наличии метки deploy. Что делает:

Извлекает head-коммит PR (для PR с меткой) или запушенный коммит.
Запускает twentyhq/twenty/.github/actions/deploy-twenty-app@main — эквивалент для CI yarn twenty app:publish --private.
Запускает twentyhq/twenty/.github/actions/install-twenty-app@main, чтобы новая развернутая версия была установлена в целевое рабочее пространство.

Обязательная конфигурация:

Настройка	Где	Назначение
`TWENTY_DEPLOY_URL`	`env` в `cd.yml` (по умолчанию `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 вашего сервера (или используйте self-hosted раннер с сетевым доступом).

Запуск предварительного деплоя из PR: Добавьте к pull request метку deploy. Условие if: в cd.yml запустит задачу для этого PR, используя его head-коммит, что позволит проверить изменение на целевом сервере до слияния.

Закрепление версий повторно используемых действий

Оба рабочих процесса ссылаются на повторно используемые действия с указанием @main, поэтому обновления действий в репозитории twentyhq/twenty подхватываются автоматически. Если вам нужны детерминированные сборки, замените @main на SHA коммита или тег релиза в каждой строке uses:.

Публикация в npm

Публикация в npm делает ваше приложение видимым в маркетплейсе Twenty. Любое рабочее пространство Twenty может просматривать, устанавливать и обновлять приложения из маркетплейса непосредственно из интерфейса.

Требования

Учётная запись npm
Ключевое слово twenty-app в массиве keywords вашего package.json (добавьте его вручную — по умолчанию оно не включено в шаблон create-twenty-app)

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

Метаданные маркетплейса

Конфигурация defineApplication() поддерживает необязательные поля, которые определяют, как ваше приложение отображается в маркетплейсе. Используйте logoUrl и screenshots, чтобы ссылаться на изображения из папки public/:

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

См. аккордеон defineApplication на странице «Создание приложений» для полного списка полей маркетплейса (author, category, aboutDescription, websiteUrl, termsUrl и т. д.).

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.

Если ваше приложение не определяет aboutDescription в defineApplication(), маркетплейс автоматически использует README.md вашего пакета из npm в качестве содержимого страницы «О приложении». Это означает, что вы можете поддерживать единый README как для npm, так и для маркетплейса Twenty. Если вы хотите другое описание в маркетплейсе, явно задайте aboutDescription.

Публикация через CI

Используйте этот workflow 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 и др.) применимы те же три команды: yarn install, yarn twenty dev:build, затем npm publish из .twenty/output.

npm provenance — опционально, но рекомендуется. Публикация с флагом --provenance добавляет к вашему пакету в npm значок доверия, позволяя пользователям проверить, что пакет был собран из конкретного коммита в общедоступном конвейере CI. См. инструкции по настройке в документации по npm provenance.

Установка приложений

После публикации приложения (npm) или его развертывания (tarball) рабочие пространства могут установить его через интерфейс. Перейдите на страницу Настройки > Приложения в 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

​Закрепление версий повторно используемых действий

​Публикация в npm

​Требования

​Метаданные маркетплейса

​Рекомендуемые размеры скриншотов

​Публикация

​Как работает обнаружение приложений в маркетплейсе

​Публикация через CI

​Установка приложений

Обзор

Сборка вашего приложения

Развертывание на сервер (tarball)

Требования

Развертывание

Общий доступ к развернутому приложению

Управление версиями

Совместимость версий сервера

Автоматизированный CI/CD (рабочие процессы, сгенерированные шаблоном)

CI — `ci.yml`

CD — `cd.yml`

Закрепление версий повторно используемых действий

Публикация в npm

Требования

Метаданные маркетплейса

Рекомендуемые размеры скриншотов

Публикация

Как работает обнаружение приложений в маркетплейсе

Публикация через CI

Установка приложений