Publishing

Overview

Once your app is built and tested locally, you have two paths for distributing it:

Deploy a tarball — upload your app directly to a specific Twenty server for internal or private use.
Publish to npm — publish your package, claim it in Twenty, and complete its setup so other workspaces can discover and install it.

Both paths start from the same build step.

Registration ownership

Publishing an app creates an application registration: the app’s identity on the instance, shared by every workspace that installs it. It holds the app’s marketplace entry, its OAuth client, and its server-side state — the serverVariables an operator configures and the server-scoped entries of the key-value store. A universalIdentifier is unique across the whole instance and a registration belongs to at most one workspace (its owner) — or none until it is claimed — so installing an app and developing one are two different rights:

Action	Requirement
Installing an app	The app is listed on the marketplace, pre-installed by the operator, or its registration belongs to your workspace.
Developing an app (`yarn twenty dev`, `apply`, `plan`)	The registration belongs to your workspace.

Syncing code and a manifest under an identifier is a claim of authorship, so being able to install an app never grants the right to publish code under its identity. A workspace that is not the owner is refused, whether the app is listed, pre-installed, or private. Two situations lead to that refusal:

The identifier belongs to another workspace. Change the universalIdentifier in your app config, which is the usual answer when you forked someone else’s app. If you need to keep the identifier, the owning workspace has to transfer the registration to yours.
The identifier belongs to no workspace. Apps imported by the marketplace catalog sync start unowned. Claim yours with GitHub before developing on it. Publishing with npm provenance provides proof of authorship; it does not automatically assign an owner workspace in Twenty.

Building your app

Run the build command to compile your app and generate a distribution-ready manifest.json:

yarn twenty dev:build

This compiles TypeScript sources, transpiles logic functions and front components, and writes everything to .twenty/output/. Add --tarball to also produce a .tgz package for manual distribution or the publish command.

Deploying to a server (tarball)

For apps you don’t want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.

Prerequisites

Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in ~/.twenty/config.json. Add a remote:

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

Deploying

Build and upload your app to the server in one step:

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

Tarball apps are not listed in the public marketplace, so other workspaces on the same server won’t discover them by browsing. To share a deployed app:

Go to Settings > Applications > Registrations and open your app
In the Distribution tab, click Copy share link
Share this link with users on other workspaces — it takes them directly to the app’s install page

The share link uses the server’s base URL (without any workspace subdomain) so it works for any workspace on the server.

Version management

When updating an already deployed tarball app, the server requires the version in package.json to be strictly higher (per semver ordering) than the currently deployed version. Re-deploying the same version, or pushing a lower one, is rejected before the tarball is stored — you’ll see a VERSION_ALREADY_EXISTS error from the CLI. To release an update:

Bump the version field in your package.json (e.g. 1.2.3 → 1.2.4, 1.3.0, or 2.0.0)
Run yarn twenty app:publish --private (or yarn twenty app:publish --private --remote production)
Workspaces that have the app installed and enabled auto-upgrade for it (in the app’s General tab) are upgraded automatically in the background; the others will see the upgrade available in their settings

Pre-release tags work as expected: bumping 1.0.0-rc.1 → 1.0.0-rc.2 is allowed, and a final release like 1.0.0 is correctly recognized as higher than 1.0.0-rc.5. The version in package.json must itself be a valid semver string.

Server version compatibility

If your app uses a feature introduced in a specific Twenty server version (for example, OAuth providers added in v2.3.0), you should declare the minimum server version your app requires using the engines.twenty field in package.json:

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

The value is a standard semver range. Common patterns:

Range	Meaning
`>=2.3.0`	Any server from 2.3.0 onward
`>=2.3.0 <3.0.0`	2.3.0 or later, but below the next major
`^2.3.0`	Same as `>=2.3.0 <3.0.0`

What happens at deploy and install time:

If engines.twenty is set and the target server’s version does not satisfy the range, the deploy (tarball upload) or install is rejected with a SERVER_VERSION_INCOMPATIBLE error and a message indicating both the required range and the actual server version.
If engines.twenty is not set, the app is accepted on any server version (backward-compatible with existing apps).
If the server has no APP_VERSION configured, the check is skipped.

The server is the authoritative check — it validates engines.twenty on both tarball upload and workspace install. If you deploy a tarball out-of-band or install from the marketplace, the server still enforces compatibility.

Automated CI/CD (scaffolded workflows)

Apps generated with create-twenty-app ship with three GitHub Actions workflows out of the box, under .github/workflows/. CI runs with no setup, CD requires a single secret, and publishing to npm requires a one-time npm trusted-publisher setup.

CI — `ci.yml`

Runs integration tests on every push to main and every pull request. What it does:

Checks out your app’s source.
Spawns an isolated Twenty test instance using the twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main composite action (the CI equivalent of yarn twenty docker:start --test).
Enables Corepack, sets up Node.js from your .nvmrc, and installs dependencies with yarn install --immutable.
Runs yarn test, passing TWENTY_API_URL and TWENTY_API_KEY from the spawned instance so your tests can talk to a real server.

Config knobs:

TWENTY_VERSION (env, defaults to latest) — pin the Twenty server version used in CI by editing this in ci.yml.
Concurrency is grouped by github.ref and cancels in-progress runs on new pushes.

No secrets are required — the test instance is ephemeral and lives only for the duration of the job.

CD — `cd.yml`

Deploys your app to a configured Twenty server on every push to main, and optionally from a pull request when the deploy label is applied. What it does:

Checks out the PR head (for labeled PRs) or the pushed commit.
Runs twentyhq/twenty/.github/actions/deploy-twenty-app@main — the CI equivalent of yarn twenty app:publish --private.
Runs twentyhq/twenty/.github/actions/install-twenty-app@main so the newly deployed version is installed into the target workspace.

Required configuration:

Setting	Where	Purpose
`TWENTY_DEPLOY_URL`	`env` in `cd.yml` (defaults to `http://localhost:3000`)	The Twenty server to deploy to. Change this to your real server URL before first use.
`TWENTY_DEPLOY_API_KEY`	GitHub repo Settings → Secrets and variables → Actions	API key with deploy permission on the target server.

The default TWENTY_DEPLOY_URL of http://localhost:3000 is a placeholder — it will not reach anything from a GitHub-hosted runner. Update it to your server’s public URL (or use a self-hosted runner with network access) before enabling CD.

Triggering a preview deploy from a PR: Add the deploy label to a pull request. The if: guard in cd.yml will run the job for that PR using the PR’s head commit, letting you validate a change on the target server before merging.

Publish — `publish.yml`

Publishes your app to npm with provenance when you push a version tag (e.g. v1.0.0), or when you run the workflow manually from the Actions tab. What it does:

Checks out your app, sets up Node.js, and updates npm (trusted publishing requires npm 11.5.1 or later).
Runs yarn twenty app:publish, which builds the app and publishes .twenty/output to npm. In CI it automatically adds --provenance and --access public, so no flags are needed in the workflow.

One-time setup: On npmjs.com open your package > Settings → Trusted Publisher and register this repository with the publish.yml workflow (see the npm trusted publishing docs). Publishing with provenance certifies which GitHub repository built the package. After publishing, claim ownership in Twenty.

npm only accepts provenance from public source repositories. If you publish from a private repo, npm rejects the OIDC provenance bundle with an E422 ... Unsupported GitHub Actions source repository visibility: "private" error. To publish from a private repo, opt out of provenance by setting TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true' in the publish step’s env (a commented-out hint is included in the scaffolded publish.yml):

      - name: Publish to npm
        env:
          TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
        run: yarn twenty app:publish

Without GitHub provenance, the package cannot be claimed through Claim with GitHub. Use a public repository with provenance if you need this ownership flow.

Pinning the reusable actions

The ci.yml and cd.yml workflows reference reusable actions at @main, so action updates in the twentyhq/twenty repo are picked up automatically. If you want deterministic builds, replace @main with a commit SHA or release tag on each uses: line.

Publishing to npm

Publishing to npm makes your app eligible for the Twenty marketplace. After catalog sync and any required server-route setup, workspaces can browse, install, and upgrade it from the UI. Community apps appear when users turn off the Vetted only filter.

Requirements

An npm account
The twenty-app keyword in your package.json keywords array (add it manually — it is not included by default in the create-twenty-app template)

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

Marketplace metadata

The defineApplication() config supports optional fields that control how your app appears in the marketplace. Use logo and galleryImages to reference images from the public/ folder:

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

See the defineApplication accordion in the Building Apps page for the full list of marketplace fields (author, category, aboutDescription, websiteUrl, termsUrl, etc.).

Recommended gallery image dimensions

The marketplace renders galleryImages in a fixed 8:5 container (for example, 1600×1000 px).

Gallery images of any aspect ratio are displayed in full and are never cropped, but anything significantly taller or narrower than 8:5 will show empty bands on the sides.

Image size limit

The logo and each galleryImages file must not exceed 10 MB. Larger files are skipped when the marketplace rehosts your published assets, so they will not be displayed.

Publish

yarn twenty app:publish

To publish under a specific dist-tag (e.g., beta or next):

yarn twenty app:publish --tag beta

How marketplace discovery works

The Twenty server syncs its marketplace catalog from the npm registry every hour. You can trigger the sync immediately instead of waiting:

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

The metadata shown in the marketplace comes from your defineApplication() config — see Marketplace metadata above.

If your app does not define an aboutDescription in defineApplication(), the marketplace will automatically use your package’s README.md from npm as the about page content. This means you can maintain a single README for both npm and the Twenty marketplace. If you want a different description in the marketplace, explicitly set aboutDescription.The About tab renders markdown text only. Images do not render, whether they use markdown syntax or <img> tags, and raw HTML such as badges or <div align="center"> blocks shows as plain text.

CI publishing

The scaffolded publish.yml workflow described above publishes to npm automatically on version tags, with provenance. Because yarn twenty app:publish adds --provenance and --access public for you when it runs in CI, the workflow needs no npm flags — only the one-time trusted-publisher setup. For other CI systems (GitLab CI, CircleCI, etc.), run yarn install then yarn twenty app:publish. Provenance is emitted when the environment can mint an OIDC token and skipped automatically otherwise.

npm provenance adds a trust badge to your npm listing, letting users verify the package was built from a specific commit in a public CI pipeline. It is also what lets you claim ownership of your app in a Twenty marketplace. See the npm provenance docs for details.

After the package has synced into the catalog, continue with Claiming your app. The claim flow requires provenance pointing to a GitHub repository.

Claiming your app

Claiming assigns your app’s registration to the Twenty workspace that will manage it. App claiming is available to all workspaces. Your role needs the Applications and MCP & APIs permissions to claim through the Developer tab. Ownership is per Twenty instance: claiming on Twenty Cloud does not claim the app on a separate self-hosted server. Other workspaces on the same instance install your app without claiming it themselves.

Before you claim

Publish your package from a public GitHub repository using GitHub Actions and npm trusted publishing with provenance. The version imported into Twenty’s catalog must carry the provenance attestation.
Include the twenty-app keyword in package.json and wait for catalog sync.
Choose the workspace that will own the app. For apps with server routes, this workspace also runs and pays for the shared resolver.
Sign in to GitHub as the personal account that owns the source repository, or as an owner of the organization that owns it. Repository collaborator access or npm package maintainer access alone is not sufficient.

Claim with GitHub

In your intended owner workspace, go to Settings > Applications > Developer (/settings/applications#developer).
In Claim an application, enter the exact npm package name, including its scope (for example, @your-org/twenty-app), or the app’s universalIdentifier.
Click Look up and check that the result is your app. If it is not found, click Sync catalog if available, wait for the sync to finish, then look it up again.
Click Claim with GitHub and authorize Twenty. For an organization-owned repository, grant access to that organization in GitHub’s Organization access section. Personal repositories do not need an organization grant.
When you return to Twenty, confirm that the app appears under My apps with type NPM. Open it and check Distribution > Ownership for Claimed by this workspace.

Claiming does not install the app. If it exposes server routes, complete the setup below before other workspaces depend on its webhooks.

Setting up server routes

A server route receives events for multiple workspaces at one URL. Its resolver runs in the registration’s owner workspace, then dispatches work to the appropriate installed workspace.

Open your app under My apps and fill in any required Server Variables in the Config tab.
In Distribution, click See on marketplace to open the app page and install it in the owner workspace. You can open this page even before the app appears in marketplace search.
Register the server webhook URL with your provider and test an event from a second workspace where the app is installed. Check both the resolver and the target function’s logs.

An unclaimed app, or an app not installed in its owner workspace, has no server-route resolver to run. Requests return 404 (LOGIC_FUNCTION_NOT_FOUND), even if the app is installed in other workspaces. These apps stay out of marketplace search until claimed, installed on the owner workspace, and configured with all required server variables.

Owner workspace costs and availability

See how logic function runs are metered for credit consumption, pricing, and which workspace is billed. Uninstalling the app from the owner workspace or deleting that workspace removes the shared resolver and interrupts server webhooks for every install on that instance.

Ownership after a repository move

Moving the GitHub repository to another personal account or organization does not transfer or remove an existing Twenty claim. The registration remains attached to its owner workspace. Keep the same npm package and app universalIdentifier; changing the Twenty owner workspace requires a separate ownership transfer.

Troubleshooting a claim

If you have trouble claiming your app, contact us on Discord or open a GitHub issue.

Self-hosted GitHub claim configuration

The server administrator configures APP_CLAIM_GITHUB_CLIENT_ID and APP_CLAIM_GITHUB_CLIENT_SECRET with a GitHub OAuth app. Set its authorization callback URL to your SERVER_URL followed by /application-registration-claim/github/callback, for example https://twenty.example.com/application-registration-claim/github/callback. This configuration is already managed for you on Twenty Cloud.

Marketplace visibility and vetting

Claiming establishes ownership; it does not grant a Vetted badge. The marketplace defaults to Vetted only. To find community apps, go to Settings > Applications > Marketplace, open the filter, and uncheck Vetted only. You can also share your app’s direct install page using My apps > your app > Distribution > Copy sharing link. The Vetted label currently applies to apps maintained by Twenty, for which the team can vouch for security and quality. Third-party apps can be published and installed without this label. If your app is still missing with Vetted only turned off, confirm catalog sync has completed, all required server variables are filled in, and any server-route setup is complete.

Installing apps

Once an app is published (npm) or deployed (tarball), workspaces can install it through the UI. Go to the Settings > Applications page in Twenty, where both marketplace and tarball-deployed apps can be browsed and installed. You can also install apps from the command line:

yarn twenty app:install

The server enforces semver versioning on install, mirroring the rules on deploy:

Installing the same version that is already installed in your workspace is rejected with an APP_ALREADY_INSTALLED error.
Installing a lower version than the one currently installed is rejected with a CANNOT_DOWNGRADE_APPLICATION error.

To install a newer version, deploy or publish it first, then re-run yarn twenty app:install.

Overview

Apps

API

Self-Host

Contribute

UI Library

Overview

Registration ownership

Building your app

Deploying to a server (tarball)

Prerequisites

Deploying

Version management

Server version compatibility

Automated CI/CD (scaffolded workflows)

CI — `ci.yml`

CD — `cd.yml`

Publish — `publish.yml`

Pinning the reusable actions

Publishing to npm

Requirements

Marketplace metadata

Recommended gallery image dimensions

Image size limit

Publish

How marketplace discovery works

CI publishing

Claiming your app

Before you claim

Claim with GitHub

Setting up server routes

Owner workspace costs and availability

Ownership after a repository move

Troubleshooting a claim

Marketplace visibility and vetting

Installing apps

​Overview

​Registration ownership

​Building your app

​Deploying to a server (tarball)

​Prerequisites

​Deploying

​Sharing a deployed app

​Version management

​Server version compatibility

​Automated CI/CD (scaffolded workflows)

​CI — ci.yml

​CD — cd.yml

​Publish — publish.yml

​Pinning the reusable actions

​Publishing to npm

​Requirements

​Marketplace metadata

​Recommended gallery image dimensions

​Image size limit

​Publish

​How marketplace discovery works

​CI publishing

​Claiming your app

​Before you claim

​Claim with GitHub

​Setting up server routes

​Owner workspace costs and availability

​Ownership after a repository move

​Troubleshooting a claim

​Marketplace visibility and vetting

​Installing apps

Overview

Registration ownership

Building your app

Deploying to a server (tarball)

Prerequisites

Deploying

Sharing a deployed app

Version management

Server version compatibility

Automated CI/CD (scaffolded workflows)

CI — `ci.yml`

CD — `cd.yml`

Publish — `publish.yml`

Pinning the reusable actions

Publishing to npm

Requirements

Marketplace metadata

Recommended gallery image dimensions

Image size limit

Publish

How marketplace discovery works

CI publishing

Claiming your app

Before you claim

Claim with GitHub

Setting up server routes

Owner workspace costs and availability

Ownership after a repository move

Troubleshooting a claim

Marketplace visibility and vetting

Installing apps