Resumen
Una vez que tu aplicación esté compilada y probada localmente, tienes dos vías para distribuirla:- Desplegar un paquete tar — sube tu aplicación directamente a un servidor Twenty específico para uso interno o privado.
- Publicar en npm — publica tu paquete, reclámalo en Twenty y completa su configuración para que otros espacios de trabajo puedan descubrirlo e instalarlo.
Propiedad del registro
La publicación de una aplicación crea un registro de aplicación: la identidad de la aplicación en la instancia, compartida por cada espacio de trabajo que la instala. Contiene la entrada de la aplicación en el marketplace, su cliente OAuth y su estado del lado del servidor: lasserverVariables que configura un operador y las entradas con ámbito de server del almacén de pares clave-valor.
Un universalIdentifier es único en toda la instancia y un registro pertenece como máximo a un espacio de trabajo (su propietario), o a ninguno hasta que se reclame, por lo que instalar una aplicación y desarrollar una son dos derechos diferentes:
Sincronizar código y un manifiesto con un identificador constituye una reivindicación de autoría, por lo que poder instalar una aplicación nunca otorga el derecho a publicar código con su identidad. Se rechaza un espacio de trabajo que no sea el propietario, independientemente de si la aplicación aparece en el marketplace, está preinstalada o es privada.
Dos situaciones provocan ese rechazo:
- El identificador pertenece a otro espacio de trabajo. Cambia el
universalIdentifieren la configuración de tu aplicación, que es la respuesta habitual cuando hiciste un fork de la aplicación de otra persona. Si necesitas conservar el identificador, el espacio de trabajo propietario debe transferir el registro al tuyo. - El identificador no pertenece a ningún espacio de trabajo. Las aplicaciones importadas por la sincronización del catálogo del marketplace comienzan sin propietario. Reclama el tuyo con GitHub antes de desarrollarlo. La publicación con procedencia de npm proporciona prueba de autoría; no asigna automáticamente un espacio de trabajo propietario en Twenty.
Compilar tu aplicación
Ejecuta el comando de compilación para verificar los tipos y empaquetar tu aplicación:--json para inspeccionar el manifiesto y los metadatos del artefacto. twenty app publish crea el paquete en sí; no se requiere una compilación de tarball independiente.
Despliegue en un servidor (tarball)
Para aplicaciones que no quieres que estén disponibles públicamente — herramientas propietarias, integraciones solo para empresas o compilaciones experimentales — puedes desplegar un tarball directamente en un servidor de Twenty.Prerrequisitos
Antes de desplegar, necesitas un remoto configurado que apunte al servidor de destino. Los remotos almacenan la URL del servidor y las credenciales de autenticación localmente en~/.twenty/config.json.
Agrega un remoto:
Despliegue
Compila y sube tu aplicación al servidor en un solo paso:--remote production selecciona la conexión guardada anteriormente, aunque otro remoto sea el predeterminado. Guardar un remoto con nombre no cambia un valor predeterminado existente.
Compartir una aplicación desplegada
Las aplicaciones en tarball no se listan en el marketplace público, por lo que otros espacios de trabajo en el mismo servidor no las descubrirán navegando. Para compartir una aplicación desplegada:- Ve a Configuración > Desarrolladores > Aplicaciones y abre tu aplicación en Mis aplicaciones
- En la pestaña Distribución, haz clic en Copiar enlace para compartir
- Comparte este enlace con usuarios de otros espacios de trabajo — los llevará directamente a la página de instalación de la aplicación
Gestión de versiones
Al actualizar una aplicación tarball ya desplegada, el servidor requiere que laversion en package.json sea estrictamente mayor (según el orden de semver) que la versión actualmente desplegada. Volver a desplegar la misma versión, o publicar una inferior, se rechaza cuando el servidor registra el archivo tarball cargado, que luego se descarta de nuevo. Verás un error VERSION_ALREADY_EXISTS de la CLI.
Para publicar una actualización:
- Incrementa el campo
versionen tupackage.json(p. ej.,1.2.3→1.2.4,1.3.0o2.0.0) - Ejecuta
twenty app publish --private --remote production - Los espacios de trabajo que tienen la aplicación instalada y la actualización automática habilitada (en la pestaña General de la aplicación) se actualizan automáticamente en segundo plano; los demás verán la actualización disponible en su configuración
Las etiquetas de prelanzamiento funcionan como se espera: incrementar
1.0.0-rc.1 → 1.0.0-rc.2 está
permitido, y una versión final como 1.0.0 se reconoce correctamente como superior
a 1.0.0-rc.5. La versión en package.json debe ser en sí misma una cadena semver
válida.Compatibilidad de la versión del servidor
Si tu app usa una función introducida en una versión específica del servidor Twenty (por ejemplo, proveedores de OAuth agregados en v2.3.0), debes declarar la versión mínima del servidor que tu app requiere usando el campoengines.twenty en package.json:
Qué sucede durante la implementación e instalación:
- Si
engines.twentyestá configurado y la versión del servidor de destino no cumple el rango, la implementación (carga del tarball) o la instalación se rechaza con un errorSERVER_VERSION_INCOMPATIBLEy un mensaje que indica tanto el rango requerido como la versión real del servidor. - Si
engines.twentyno está configurado, no se realiza ninguna comprobación de versión y la app se acepta en cualquier versión del servidor (retrocompatible con las apps existentes). Se rechaza un valor en blanco por ser un rango no válido. - El marketplace no incluye en la lista una app cuya versión más reciente declare un rango de
engines.twentyque el servidor no cumpla, o uno no válido. La app permanece registrada y visible en el panel de administración. - Si el servidor no tiene
APP_VERSIONconfigurado, se omite la comprobación.
El servidor es la autoridad en la comprobación — valida
engines.twenty tanto en
la carga del tarball como en la instalación en el espacio de trabajo. Si implementas un tarball fuera de banda o
instalas desde el marketplace, el servidor sigue garantizando la compatibilidad.CI/CD automatizado (flujos de trabajo preconfigurados)
Las aplicaciones generadas contwenty app init incluyen de forma predeterminada tres flujos de trabajo de GitHub Actions, en .github/workflows/. La CI se ejecuta sin configuración, la CD requiere un único secreto y la publicación en npm requiere una configuración por única vez de Trusted Publisher de npm.
CI — ci.yml
Ejecuta pruebas de integración en cada push a main y en cada pull request.
Qué hace:
- Obtiene el código fuente de tu aplicación.
- Inicia una instancia de prueba aislada de Twenty usando la acción compuesta
twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main. - Habilita Corepack y configura Node.js a partir de tu
.nvmrc. - Instala la CLI independiente fijada en el paso Instalar la CLI de Twenty.
- Instala las dependencias con
yarn install --immutabley, a continuación, ejecuta lint, la comprobación de tipos y las pruebas unitarias. - Ejecuta
yarn test, pasandoTWENTY_API_URLyTWENTY_API_KEYde la instancia iniciada para que tus pruebas puedan comunicarse con un servidor real.
TWENTY_VERSION(variable de entorno; por defectolatest) — fija la versión del servidor de Twenty usada en CI editando esto enci.yml.- La concurrencia se agrupa por
github.refy cancela las ejecuciones en progreso cuando hay nuevos pushes.
CD — cd.yml
Despliega tu aplicación en un servidor de Twenty configurado en cada push a main y, opcionalmente, desde un pull request cuando se aplica la etiqueta deploy.
Qué hace:
- Obtiene el head del PR (para PR etiquetados) o el commit enviado.
- Ejecuta
twentyhq/twenty/.github/actions/deploy-twenty-app@main— el equivalente en CI detwenty app publish --private. - Ejecuta
twentyhq/twenty/.github/actions/install-twenty-app@mainpara que la versión recién desplegada se instale en el espacio de trabajo de destino.
La
TWENTY_DEPLOY_URL predeterminada de http://localhost:2020 es un marcador de posición —
no alcanzará nada desde un runner alojado por GitHub. Actualízala a la
URL pública de tu servidor (o usa un runner autohospedado con acceso a la red) antes de
habilitar CD.deploy a un pull request. La condición if: en cd.yml ejecutará el trabajo para ese PR usando el commit head del PR, lo que te permitirá validar un cambio en el servidor de destino antes de hacer merge.
Publicar — publish.yml
Publica tu aplicación en npm con procedencia cuando haces push de una etiqueta de versión (por ejemplo, v1.0.0), o cuando ejecutas el flujo de trabajo manualmente desde la pestaña Actions.
Qué hace:
- Hace checkout de tu aplicación, configura Node.js y actualiza npm (la publicación de confianza requiere npm 11.5.1 o posterior).
- Instala la CLI independiente fijada en el paso Instalar la CLI de Twenty y, a continuación, instala las dependencias de la aplicación con
yarn install --immutable. - Ejecuta
twenty app publish, que compila y empaqueta una instantánea aislada de la aplicación y, a continuación, la publica en npm. En CI agrega automáticamente--provenancey--access public, por lo que no se necesitan banderas en el flujo de trabajo.
publish.yml (consulta la documentación de publicación de confianza de npm). La publicación con procedencia certifica qué repositorio de GitHub creó el paquete. Después de publicar, reclama la propiedad en Twenty.
npm solo acepta procedencia de repositorios de código fuente públicos. Si publicas desde un repositorio privado, npm rechaza el paquete de procedencia OIDC con un Sin procedencia de GitHub, el paquete no se puede reclamar mediante Reclamar con GitHub. Usa un repositorio público con procedencia si necesitas este flujo de propiedad.
E422 ... Visibilidad del repositorio de origen de GitHub Actions no compatible: "private" error. Para publicar desde un repositorio privado, excluya la procedencia configurando TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true' en el env del paso de publicación (se incluye una sugerencia comentada en el archivo publish.yml generado automáticamente):Fijar la versión de la CLI
Los tres flujos de trabajo generados fijan la CLI independiente a la versión detwenty que ejecutó twenty app init. Los pasos Instalar la CLI de Twenty en ci.yml y publish.yml usan npm install -g twenty@\<version>. En cd.yml, tanto las acciones de implementación como de instalación reciben la misma versión mediante su entrada cli-version.
Para actualizar, actualiza conjuntamente los dos comandos de instalación y ambas entradas cli-version. Estas fijaciones son independientes de la versión del servidor TWENTY_VERSION utilizada en CI y de las referencias a acciones reutilizables que aparecen a continuación.
Fijar las acciones reutilizables
Los flujos de trabajoci.yml y cd.yml hacen referencia a acciones reutilizables en @main, por lo que las actualizaciones de acciones en el repositorio twentyhq/twenty se aplican automáticamente. Si quieres compilaciones deterministas, reemplaza @main por un SHA de commit o una etiqueta de versión en cada línea uses:.
Publicación en npm
Publicarla en npm hace que tu aplicación sea apta para el marketplace de Twenty. Tras la sincronización del catálogo y cualquier configuración de rutas del servidor necesaria, los espacios de trabajo pueden buscarla, instalarla y actualizarla desde la interfaz de usuario una vez que supere la revisión del marketplace.Requisitos
- Una cuenta de npm
- La palabra clave
twenty-appen tu matrizkeywordsdepackage.json(agrégala manualmente — no se incluye de forma predeterminada en la plantillatwenty app init)
Metadatos del Marketplace
La configuración dedefineApplication() admite campos opcionales que controlan cómo aparece tu aplicación en el marketplace. Usa logo y galleryImages para hacer referencia a imágenes de la carpeta public/:
src/application-config.ts
author, category, aboutDescription, websiteUrl, termsUrl, etc.).
Dimensiones recomendadas de las imágenes de la galería
El marketplace muestragalleryImages en un contenedor fijo de 8:5 (por ejemplo, 1600×1000 px).
Las imágenes de la galería de cualquier relación de aspecto se muestran completas y nunca se recortan, pero las que sean significativamente más altas o más estrechas que
8:5 mostrarán
franjas vacías a los lados.Límite de tamaño de imagen
Ellogo y cada archivo de galleryImages no deben superar los 10 MB. Los archivos más grandes se omiten cuando el marketplace vuelve a alojar tus recursos publicados, por lo que no se mostrarán.
Publicar
beta o next):
Cómo funciona el descubrimiento en el marketplace
El servidor de Twenty sincroniza su catálogo del marketplace desde el registro de npm cada hora. La CLI independiente no tiene ningún comando de sincronización de catálogo. Espera a la sincronización del catálogo del servidor o usa las herramientas de administración del servidor. Los metadatos que se muestran en el marketplace provienen de tu configuración dedefineApplication(); consulta Metadatos del marketplace arriba.
Si tu aplicación no define un
aboutDescription en defineApplication(), el marketplace usará automáticamente el README.md de tu paquete en npm como el contenido de la página Acerca de. Esto significa que puedes mantener un único README tanto para npm como para el marketplace de Twenty. Si quieres una descripción diferente en el marketplace, establece explícitamente aboutDescription.La pestaña Acerca de solo muestra texto en markdown. Las imágenes no se muestran, ya sea que utilicen sintaxis de markdown o etiquetas <img>, y el HTML sin procesar, como insignias o bloques \<div align="center">, se muestra como texto sin formato.Publicación en CI
El flujo de trabajopublish.yml generado automáticamente descrito arriba publica en npm de forma automática en las etiquetas de versión, con provenance. Como twenty app publish añade --provenance y --access public por ti cuando se ejecuta en CI, el flujo de trabajo no necesita indicadores de npm — solo la configuración única del publicador de confianza.
Para otros sistemas de CI (GitLab CI, CircleCI, etc.), ejecuta yarn install y luego twenty app publish. La provenance se emite cuando el entorno puede generar un token OIDC y, en caso contrario, se omite automáticamente.
La procedencia de npm añade una insignia de confianza a tu ficha de npm, permitiendo que los usuarios
verifiquen que el paquete se compiló a partir de un commit específico en una canalización de CI pública.
También es lo que te permite reclamar la propiedad de tu aplicación en un marketplace de Twenty.
Consulta la documentación de procedencia de npm
para obtener más información.
Reclamar tu aplicación
La reclamación asigna el registro de tu aplicación al espacio de trabajo de Twenty que la administrará. La reclamación de aplicaciones está disponible para todos los espacios de trabajo. Tu rol necesita los permisos de Workspace Apps y Developers para reclamar mediante la pestaña Apps de Settings > Developers. La propiedad es por instancia de Twenty: reclamar en Twenty Cloud no reclama la aplicación en un servidor autohospedado independiente. Otros espacios de trabajo de la misma instancia instalan tu aplicación sin tener que reclamarla por sí mismos.Antes de reclamar
- Publica tu paquete desde un repositorio público de GitHub mediante GitHub Actions y publicación de confianza de npm con procedencia. La versión importada en el catálogo de Twenty debe incluir la certificación de procedencia.
- Incluye la palabra clave
twenty-appenpackage.jsony espera la sincronización del catálogo. - Elige el espacio de trabajo que será propietario de la aplicación. Para aplicaciones con rutas de servidor, este espacio de trabajo también ejecuta y paga el resolvedor compartido.
- Inicia sesión en GitHub como la cuenta personal propietaria del repositorio de origen o como un propietario de la organización que es propietaria de él. El acceso como colaborador del repositorio o como responsable del paquete npm por sí solo no es suficiente.
Reclamar con GitHub
- En el espacio de trabajo del propietario previsto, ve a Configuración > Desarrolladores > Aplicaciones (
/settings/developers#apps). - En Reclamar una aplicación, introduce el nombre exacto del paquete npm, incluido su ámbito (por ejemplo,
@your-org/twenty-app), o eluniversalIdentifierde la aplicación. - Haz clic en Buscar y comprueba que el resultado sea tu aplicación. Si no se encuentra, haz clic en Sincronizar catálogo si está disponible, espera a que finalice la sincronización y vuelve a buscarla.
- Haz clic en Reclamar con GitHub y autoriza a Twenty. Para un repositorio propiedad de una organización, concede acceso a esa organización en la sección Acceso a la organización de GitHub. Los repositorios personales no necesitan una concesión de organización.
- Cuando regreses a Twenty, confirma que la aplicación aparezca en Mis aplicaciones con el tipo NPM. Ábrela y comprueba Distribución > Propiedad para ver Reclamada por este espacio de trabajo.
Configurar rutas de servidor
Una ruta de servidor recibe eventos de varios espacios de trabajo en una URL. Su resolvedor se ejecuta en el espacio de trabajo propietario del registro y luego distribuye el trabajo al espacio de trabajo instalado correspondiente.- Abre tu aplicación en Mis aplicaciones y completa las Variables de servidor requeridas en la pestaña Configuración.
- En Distribución, haz clic en Ver en el marketplace para abrir la página de la aplicación e instalarla en el espacio de trabajo propietario. Puedes abrir esta página incluso antes de que la aplicación aparezca en la búsqueda del marketplace.
- Registra la URL del webhook del servidor con tu proveedor y prueba un evento desde un segundo espacio de trabajo en el que esté instalada la aplicación. Revisa los registros tanto del resolvedor como de la función de destino.
Costes y disponibilidad del espacio de trabajo propietario
Consulta cómo se miden las ejecuciones de funciones lógicas para ver el consumo de créditos, los precios y qué espacio de trabajo recibe la facturación. Desinstalar la aplicación del espacio de trabajo propietario o eliminar ese espacio de trabajo elimina el resolvedor compartido e interrumpe los webhooks del servidor de todas las instalaciones de esa instancia.Propiedad después de mover un repositorio
Mover el repositorio de GitHub a otra cuenta personal u organización no transfiere ni elimina una reclamación existente de Twenty. El registro permanece vinculado a su espacio de trabajo propietario. Mantén el mismo paquete npm yuniversalIdentifier de la aplicación; cambiar el espacio de trabajo propietario de Twenty requiere una transferencia de propiedad independiente.
Solución de problemas de una reclamación
Si tienes problemas para reclamar tu aplicación, contáctanos en Discord o abre una incidencia en GitHub.Configuración de reclamación de GitHub autohospedado
Configuración de reclamación de GitHub autohospedado
El administrador del servidor configura
APP_CLAIM_GITHUB_CLIENT_ID y
APP_CLAIM_GITHUB_CLIENT_SECRET con una aplicación OAuth de GitHub. Establece su
URL de devolución de llamada de autorización en tu SERVER_URL seguida de
/application-registration-claim/github/callback, por ejemplo
https://twenty.example.com/application-registration-claim/github/callback.
Esta configuración ya está gestionada por ti en Twenty Cloud.Visibilidad y revisión en Marketplace
Todas las aplicaciones incluidas en Marketplace han superado la revisión de seguridad y calidad de Twenty. Una aplicación recién publicada permanece sin listar hasta que supera la revisión del marketplace; reclamarla establece la propiedad, pero no la incluye en la lista. Una aplicación sin listar aún se puede instalar. En Configuración > Aplicaciones > Marketplace, abre el filtro y activa Mostrar aplicaciones sin listar, o comparte la página de instalación directa de la aplicación mediante Mis aplicaciones > tu aplicación > Distribución > Copiar enlace para compartir. Los espacios de trabajo ven una advertencia de que la aplicación no ha sido revisada por Twenty. Si tu aplicación está incluida en la lista pero aún no aparece en Marketplace, confirma que la sincronización del catálogo se haya completado, que se hayan rellenado todas las variables de servidor necesarias y que se haya completado cualquier configuración de rutas del servidor.Instalar aplicaciones
Una vez que una aplicación esté publicada (npm) o desplegada (tarball), los espacios de trabajo pueden instalarla a través de la interfaz de usuario. Ve a la página Configuración > Aplicaciones en Twenty, donde se pueden explorar e instalar tanto las aplicaciones del marketplace como las desplegadas mediante tarball. Desde el directorio de la aplicación, instala su versión publicada en el espacio de trabajo de destino:--universal-identifier \<id>.
El servidor aplica el versionado semver al instalar, reflejando las reglas del despliegue:
- Instalar la misma versión que ya está instalada en tu espacio de trabajo se rechaza con un error
APP_ALREADY_INSTALLED. - Instalar una versión inferior a la que está instalada actualmente se rechaza con un error
CANNOT_DOWNGRADE_APPLICATION.
twenty app install --remote production.