From 43249d80e88f00c071b1935df78cadbbdbadbe52 Mon Sep 17 00:00:00 2001 From: martmull Date: Tue, 14 Apr 2026 17:30:50 +0200 Subject: [PATCH] Add missing doc (#19693) follow up of the @charlesBochet presentation as title --- .../extend/apps/getting-started.mdx | 15 ++++++ .../developers/extend/apps/publishing.mdx | 51 +++++++++++++++++++ 2 files changed, 66 insertions(+) diff --git a/packages/twenty-docs/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/developers/extend/apps/getting-started.mdx index de240b822a..46ffea8ba8 100644 --- a/packages/twenty-docs/developers/extend/apps/getting-started.mdx +++ b/packages/twenty-docs/developers/extend/apps/getting-started.mdx @@ -220,6 +220,7 @@ The scaffolder already started a local Twenty server for you. To manage it later |---------|-------------| | `yarn twenty server start` | Start the local server (pulls image if needed) | | `yarn twenty server start --port 3030` | Start on a custom port | +| `yarn twenty server start --test` | Start a separate test instance on port 2021 | | `yarn twenty server stop` | Stop the server (preserves data) | | `yarn twenty server status` | Show server status, URL, and credentials | | `yarn twenty server logs` | Stream server logs | @@ -228,6 +229,20 @@ The scaffolder already started a local Twenty server for you. To manage it later Data is persisted across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything and start fresh. +### Running a test instance + +Pass `--test` to any `server` command to manage a second, fully isolated instance — useful for running integration tests or experimenting without touching your main dev data. + +| Command | Description | +|---------|-------------| +| `yarn twenty server start --test` | Start the test instance (defaults to port 2021) | +| `yarn twenty server stop --test` | Stop the test instance | +| `yarn twenty server status --test` | Show test instance status, URL, and credentials | +| `yarn twenty server logs --test` | Stream test instance logs | +| `yarn twenty server reset --test` | Wipe test data and start fresh | + +The test instance runs in its own Docker container (`twenty-app-dev-test`) with dedicated volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) and config, so it can run in parallel with your main instance without conflicts. Combine `--test` with `--port` to override the default 2021. + The server requires **Docker** to be running. If you see a "Docker not running" error, make sure Docker Desktop (or the Docker daemon) is started. diff --git a/packages/twenty-docs/developers/extend/apps/publishing.mdx b/packages/twenty-docs/developers/extend/apps/publishing.mdx index 72b13c211d..3f0df07a84 100644 --- a/packages/twenty-docs/developers/extend/apps/publishing.mdx +++ b/packages/twenty-docs/developers/extend/apps/publishing.mdx @@ -80,6 +80,57 @@ Pre-release tags work as expected: bumping `1.0.0-rc.1` → `1.0.0-rc.2` is allo {/* TODO: add screenshot of the Upgrade button */} +## Automated CI/CD (scaffolded workflows) + +Apps generated with `create-twenty-app` ship with two GitHub Actions workflows out of the box, under `.github/workflows/`. They are ready to run as soon as you push the repo to GitHub — no extra setup is needed for CI, and CD only requires a single secret. + +### CI — `ci.yml` + +Runs integration tests on every push to `main` and every pull request. + +**What it does:** + +1. Checks out your app's source. +2. 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 server start --test`). +3. Enables Corepack, sets up Node.js from your `.nvmrc`, and installs dependencies with `yarn install --immutable`. +4. 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:** + +1. Checks out the PR head (for labeled PRs) or the pushed commit. +2. Runs `twentyhq/twenty/.github/actions/deploy-twenty-app@main` — the CI equivalent of `yarn twenty deploy`. +3. 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. + +### Pinning the reusable actions + +Both 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 discoverable in the Twenty marketplace. Any Twenty workspace can browse, install, and upgrade marketplace apps directly from the UI.