From 92d6bcd8acd67923e31ebb70b626acd7099ddddc Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 20 Jul 2026 19:00:53 +0200 Subject: [PATCH] i18n - docs translations (#23083) Created by Github action Review in cubic Co-authored-by: github-actions --- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../extend/apps/operations/testing.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 46 ++++++++++++++++++ .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../apps/operations/sync-and-recovery.mdx | 2 +- .../extend/apps/operations/testing.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 46 ++++++++++++++++++ .../getting-started/project-structure.mdx | 1 + .../extend/apps/operations/publishing.mdx | 48 +++++++------------ .../apps/operations/sync-and-recovery.mdx | 2 +- .../extend/apps/operations/testing.mdx | 2 +- 40 files changed, 334 insertions(+), 374 deletions(-) diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/getting-started/project-structure.mdx index 8d403e4a7a..93556cb982 100644 --- a/packages/twenty-docs/l/ar/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/ar/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/operations/publishing.mdx index ead4033588..d8e62bd2eb 100644 --- a/packages/twenty-docs/l/ar/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/ar/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ yarn twenty app:publish --private ## CI/CD المؤتمتة (مهام سير عمل مُولَّدة بالقوالب) -التطبيقات المُولَّدة باستخدام `create-twenty-app` تأتي افتراضيًا مع مهمَّتي سير عمل من GitHub Actions ضمن `.github/workflows/`. هي جاهزة للتشغيل بمجرد دفع المستودع إلى GitHub — لا حاجة لأي إعداد إضافي لـ CI، وCD يتطلّب سرًّا واحدًا فقط. +التطبيقات المُولَّدة باستخدام `create-twenty-app` تأتي افتراضيًا مع ثلاث مهام سير عمل من GitHub Actions ضمن `.github/workflows/`. يعمل CI بدون أي إعداد، بينما يتطلّب CD سرًّا واحدًا فقط، ويتطلّب النشر إلى npm إعدادًا لمرة واحدة لـ npm trusted-publisher. ### CI — `ci.yml` @@ -157,9 +157,22 @@ yarn twenty app:publish --private أضِف الوسم `deploy` إلى طلب سحب. الشرط `if:` في `cd.yml` سيشغّل المهمّة لذلك الطلب مستخدمًا التزام رأس الطلب، مما يتيح لك التحقّق من التغيير على الخادم المستهدف قبل الدمج. +### النشر — `publish.yml` + +ينشر تطبيقك إلى npm مع إثبات المصدر (provenance) عند دفع وسم إصدار (مثلًا: `v1.0.0`)، أو عند تشغيل سير العمل يدويًا من علامة التبويب Actions. + +**ماذا يفعل:** + +1. يتحقق من تطبيقك، ويُعد Node.js، ويُحدِّث npm (يتطلّب النشر الموثوق npm 11.5.1 أو أحدث). +2. يشغّل `yarn twenty app:publish`، الذي يبني التطبيق وينشر `.twenty/output` إلى npm. في بيئة CI يضيف تلقائيًا `--provenance` و`--access public`، لذا لا حاجة للرايات داخل سير العمل. + +**إعداد لمرة واحدة:** + +على npmjs.com افتح الحزمة الخاصة بك > **Settings → Trusted Publisher** وسجّل هذا المستودع مع سير عمل `publish.yml` (راجع [وثائق النشر الموثوق من npm](https://docs.npmjs.com/trusted-publishers)). يُصادِق النشر مع بيانات provenance على مستودع GitHub الذي بنى الحزمة، وهو أيضًا ما يتيح لك المطالبة بملكية تطبيقك في سوق Twenty. + ### تثبيت الإجراءات القابلة لإعادة الاستخدام -يشير كلا سيرَي العمل إلى إجراءات قابلة لإعادة الاستخدام عند `@main`، لذا تُلتقط تحديثات الإجراءات في مستودع `twentyhq/twenty` تلقائيًا. إذا كنت تريد بناءات حتمية، فاستبدِل `@main` بقيمة SHA لالتزام أو بوسم إصدار في كل سطر `uses:`. +يشير سيرَا العمل `ci.yml` و`cd.yml` إلى إجراءات قابلة لإعادة الاستخدام عند `@main`، لذا تُلتقط تحديثات الإجراءات في مستودع `twentyhq/twenty` تلقائيًا. إذا كنت تريد بناءات حتمية، فاستبدِل `@main` بقيمة SHA لالتزام أو بوسم إصدار في كل سطر `uses:`. ## النشر على npm @@ -241,37 +254,12 @@ yarn twenty dev:catalog-sync ### النشر عبر CI -استخدم سير عمل GitHub Actions هذا للنشر تلقائيًا مع كل إصدار (يستخدم [OIDC](https://docs.npmjs.com/trusted-publishers)): +ينشر سير عمل `publish.yml` المُنشأ تلقائيًا والموصوف أعلاه إلى npm تلقائيًا عند علامات الإصدارات، مع بيانات provenance. نظرًا لأن `yarn twenty app:publish` يضيف `--provenance` و`--access public` نيابةً عنك عند تشغيله في CI، فلا يحتاج سير العمل إلى أي رايات npm — فقط إعداد الناشر الموثوق لمرة واحدة. -```yaml filename=".github/workflows/publish.yml" -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`. +بالنسبة لأنظمة CI الأخرى (GitLab CI وCircleCI وغيرها)، شغّل `yarn install` ثم `yarn twenty app:publish`. يُصدِر بيانات provenance عندما تتمكّن البيئة من إصدار رمز OIDC، ويتم تخطيه تلقائيًا خلاف ذلك. -**npm provenance** اختياري ولكنه موصى به. يضيف النشر باستخدام `--provenance` شارة ثقة إلى إدراجك على npm، مما يتيح للمستخدمين التحقق من أن الحزمة تم بناؤها من التزام محدد ضمن خط أنابيب CI عام. راجع [وثائق npm provenance](https://docs.npmjs.com/generating-provenance-statements) للحصول على تعليمات الإعداد. +تضيف **npm provenance** شارة ثقة إلى إدراجك على npm، مما يتيح للمستخدمين التحقّق من أن الحزمة تم بناؤها من التزام محدد ضمن خط أنابيب CI عام. وهي أيضًا ما يتيح لك المطالبة بملكية تطبيقك في سوق Twenty. راجع [وثائق npm provenance](https://docs.npmjs.com/generating-provenance-statements) للتفاصيل. ## تثبيت التطبيقات diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/operations/testing.mdx index 92899b138c..1566e9eab0 100644 --- a/packages/twenty-docs/l/ar/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/ar/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ yarn twenty dev:typecheck تولّد أداة إنشاء الهيكل سير عمل جاهزًا للاستخدام في `.github/workflows/ci.yml`. عند كل دفع إلى الفرع `main` وكل طلب سحب، تُنشئ الأداة خادم Twenty مؤقتًا في بيئة التشغيل (عبر الإجراء `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`)، ثم تشغِّل الأوامر `yarn lint` و`yarn typecheck` و`yarn test:unit` و`yarn test` مع ضبط المتغيرين `TWENTY_API_URL` و`TWENTY_API_KEY` للإشارة إلى ذلك الخادم. لا تُطلَب أي أسرار، ويمكنك تثبيت إصدار الخادم عبر متغير البيئة `TWENTY_VERSION` في أعلى سير العمل. -راجع قسم [النشر → التكامل/التسليم المستمران الآليان](/l/ar/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) للاطلاع على شرح كامل لكلا سيرَي العمل المُنشأين بالهيكل (`ci.yml` وخط أنابيب النشر `cd.yml`). +راجع قسم [النشر → التكامل/التسليم المستمران الآليان](/l/ar/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) للاطلاع على شرح كامل لسير العمل الثلاثة المُنشأة بالهيكل (`ci.yml` وخط أنابيب النشر `cd.yml`، و`publish.yml` للنشر على npm). diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/getting-started/project-structure.mdx index 8faaac2621..e3aa0cb184 100644 --- a/packages/twenty-docs/l/cs/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/cs/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/operations/publishing.mdx index 2281bbd9f1..7e8b5cbcd9 100644 --- a/packages/twenty-docs/l/cs/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/cs/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ Server je rozhodující autoritou — ověřuje `engines.twenty` jak při nahrá ## Automatizované CI/CD (předpřipravené workflowy) -Aplikace vygenerované pomocí `create-twenty-app` jsou hned připravené se dvěma workflowy GitHub Actions ve složce `.github/workflows/`. Jsou připravené ke spuštění hned, jakmile repozitář pushnete na GitHub — pro CI není potřeba žádné další nastavení a CD vyžaduje pouze jeden secret. +Aplikace vygenerované pomocí `create-twenty-app` jsou hned připravené se třemi workflowy GitHub Actions ve složce `.github/workflows/`. CI běží bez jakéhokoli nastavování, CD vyžaduje jediný secret a publikování na npm vyžaduje jednorázové nastavení npm trusted-publisher. ### CI — `ci.yml` @@ -157,9 +157,22 @@ Výchozí `TWENTY_DEPLOY_URL` `http://localhost:3000` je pouze zástupná hodnot Přidejte k pull requestu štítek `deploy`. Podmínka `if:` v `cd.yml` spustí úlohu pro dané PR s použitím head commitu PR, což vám umožní ověřit změnu na cílovém serveru před sloučením. +### Publish — `publish.yml` + +Publikuje vaši aplikaci na npm s doloženým původem, když odešlete tag verze (např. `v1.0.0`), nebo když workflow spustíte ručně na kartě Actions. + +**K čemu slouží:** + +1. Zkontroluje vaši aplikaci, nastaví Node.js a aktualizuje npm (důvěryhodné publikování vyžaduje npm 11.5.1 nebo novější). +2. Spustí `yarn twenty app:publish`, který sestaví aplikaci a publikuje `.twenty/output` na npm. V CI automaticky přidá `--provenance` a `--access public`, takže ve workflowu nejsou potřeba žádné přepínače. + +**Jednorázové nastavení:** + +Na npmjs.com otevřete svůj balíček > **Settings → Trusted Publisher** a zaregistrujte tento repozitář s workflowem `publish.yml` (viz [dokumentaci k důvěryhodnému publikování na npm](https://docs.npmjs.com/trusted-publishers)). Publikování s provenance potvrzuje, který repozitář na GitHubu balíček sestavil, a zároveň tak uplatňujete vlastnictví své aplikace na tržišti Twenty. + ### Připnutí verzí znovupoužitelných akcí -Obě workflowy odkazují na znovupoužitelné akce na `@main`, takže aktualizace akcí v repozitáři `twentyhq/twenty` se přeberou automaticky. Pokud chcete deterministická sestavení, nahraďte `@main` v každém řádku `uses:` za commit SHA nebo tag vydání. +Workflowy `ci.yml` a `cd.yml` odkazují na znovupoužitelné akce na `@main`, takže aktualizace akcí v repozitáři `twentyhq/twenty` se přeberou automaticky. Pokud chcete deterministická sestavení, nahraďte `@main` v každém řádku `uses:` za commit SHA nebo tag vydání. ## Publikování na npm @@ -241,37 +254,12 @@ Pokud vaše aplikace nedefinuje `aboutDescription` v `defineApplication()`, trž ### Publikování pomocí CI -Použijte tento pracovní postup GitHub Actions k automatickému publikování při každém vydání (používá [OIDC](https://docs.npmjs.com/trusted-publishers)): +Vygenerované workflow `publish.yml` popsané výše publikuje na npm automaticky při verzovacích tazích (tagách), s provenance. Protože `yarn twenty app:publish` při běhu v CI přidá `--provenance` a `--access public` za vás, workflow nepotřebuje žádné přepínače npm — pouze jednorázové nastavení důvěryhodného vydavatele. -```yaml filename=".github/workflows/publish.yml" -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 -``` - -Pro jiné systémy CI (GitLab CI, CircleCI atd.) platí stejné tři příkazy: `yarn install`, `yarn twenty dev:build` a poté `npm publish` z `.twenty/output`. +Pro jiné CI systémy (GitLab CI, CircleCI atd.) spusťte `yarn install` a poté `yarn twenty app:publish`. Provenance se vydává, pokud prostředí umí vytvořit token OIDC, a v opačném případě se automaticky vynechá. -**npm provenance** je volitelné, ale doporučené. Publikování s `--provenance` přidá k vašemu záznamu na npm odznak důvěryhodnosti a umožní uživatelům ověřit, že balíček byl sestaven z konkrétního commitu ve veřejné CI pipeline. Pokyny k nastavení najdete v [dokumentaci k npm provenance](https://docs.npmjs.com/generating-provenance-statements). +**npm provenance** přidává k vašemu záznamu na npm odznak důvěryhodnosti a umožňuje uživatelům ověřit, že balíček byl sestaven z konkrétního commitu ve veřejné CI pipeline. Také vám umožňuje uplatnit vlastnictví vaší aplikace na tržišti Twenty. Podrobnosti najdete v [dokumentaci k npm provenance](https://docs.npmjs.com/generating-provenance-statements). ## Instalace aplikací diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/operations/testing.mdx index cce7946196..02852b158e 100644 --- a/packages/twenty-docs/l/cs/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/cs/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ Spustí se `tsc --noEmit` proti souboru `tsconfig.json` vaší aplikace a nahlá Generátor kostry vytvoří připravený k použití workflow v `.github/workflows/ci.yml`. Při každém pushi do `main` a při každém pull requestu spustí efemérní server Twenty v runneru (pomocí akce `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`), poté spustí `yarn lint`, `yarn typecheck`, `yarn test:unit` a `yarn test` s `TWENTY_API_URL` / `TWENTY_API_KEY` směřujícími na tento server. Nejsou vyžadovány žádné tajné údaje a verzi serveru můžete připnout pomocí proměnné prostředí `TWENTY_VERSION` na začátku workflow. -Úplný postup pro obě workflow generované kostrou (`ci.yml` a nasazovací pipeline `cd.yml`) najdete v části [Publishing → Automated CI/CD](/l/cs/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows). +Úplný postup pro tři workflow generované kostrou (`ci.yml`, nasazovací pipeline `cd.yml` a `publish.yml` pro publikování na npm) najdete v části [Publishing → Automated CI/CD](/l/cs/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows). diff --git a/packages/twenty-docs/l/de/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/de/developers/extend/apps/getting-started/project-structure.mdx index d1ff1ab877..41a6aa3d7f 100644 --- a/packages/twenty-docs/l/de/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/de/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/de/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/de/developers/extend/apps/operations/publishing.mdx index 44eeef9bb8..d8aeed445d 100644 --- a/packages/twenty-docs/l/de/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/de/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ Der Server ist die maßgebliche Prüfinstanz — er validiert `engines.twenty` s ## Automatisiertes CI/CD (vorgefertigte Workflows) -Apps, die mit `create-twenty-app` erzeugt wurden, enthalten von Haus aus zwei GitHub-Actions-Workflows unter `.github/workflows/`. Sie sind einsatzbereit, sobald Sie das Repository zu GitHub pushen — für CI ist keine zusätzliche Einrichtung erforderlich, und für CD ist nur ein einziges Secret nötig. +Apps, die mit `create-twenty-app` erzeugt wurden, enthalten von Haus aus drei GitHub-Actions-Workflows unter `.github/workflows/`. CI läuft ohne Einrichtung, CD erfordert ein einziges Secret, und das Veröffentlichen auf npm erfordert eine einmalige Einrichtung als npm Trusted Publisher. ### CI — `ci.yml` @@ -157,9 +157,22 @@ Der Standardwert von `TWENTY_DEPLOY_URL` (`http://localhost:3000`) ist ein Platz Fügen Sie einem Pull Request das Label `deploy` hinzu. Die `if:`-Bedingung in `cd.yml` führt den Job für diesen PR mit dem Head-Commit des PR aus, sodass Sie eine Änderung auf dem Zielserver vor dem Mergen validieren können. +### Veröffentlichen — `publish.yml` + +Veröffentlicht Ihre App mit Herkunftsnachweis auf npm, wenn Sie ein Versions-Tag pushen (z. B. `v1.0.0`), oder wenn Sie den Workflow manuell über den Actions-Tab ausführen. + +**Was sie macht:** + +1. Checkt eure App aus, richtet Node.js ein und aktualisiert npm (Trusted Publishing erfordert npm 11.5.1 oder neuer). +2. Führt `yarn twenty app:publish` aus, wodurch die App gebaut und `.twenty/output` auf npm veröffentlicht wird. In CI werden automatisch `--provenance` und `--access public` hinzugefügt, sodass im Workflow keine Flags benötigt werden. + +**Einmalige Einrichtung:** + +Öffnen Sie auf npmjs.com Ihr Paket > **Settings → Trusted Publisher** und registrieren Sie dieses Repository mit dem `publish.yml`-Workflow (siehe die [npm trusted publishing docs](https://docs.npmjs.com/trusted-publishers)). Das Veröffentlichen mit Provenance bestätigt, welches GitHub-Repository das Paket gebaut hat; zugleich beanspruchen Sie damit die Inhaberschaft Ihrer App in einem Twenty-Marktplatz. + ### Fixieren der wiederverwendbaren Actions -Beide Workflows verweisen auf wiederverwendbare Actions mit `@main`, sodass Aktualisierungen der Actions im Repository `twentyhq/twenty` automatisch übernommen werden. Wenn Sie deterministische Builds möchten, ersetzen Sie `@main` in jeder `uses:`-Zeile durch eine Commit-SHA oder einen Release-Tag. +Die Workflows `ci.yml` und `cd.yml` verweisen auf wiederverwendbare Actions mit `@main`, sodass Aktualisierungen der Actions im Repository `twentyhq/twenty` automatisch übernommen werden. Wenn Sie deterministische Builds möchten, ersetzen Sie `@main` in jeder `uses:`-Zeile durch eine Commit-SHA oder einen Release-Tag. ## Auf npm veröffentlichen @@ -241,37 +254,12 @@ Wenn Ihre App keine `aboutDescription` in `defineApplication()` definiert, verwe ### CI-Veröffentlichung -Verwenden Sie diesen GitHub-Actions-Workflow, um bei jedem Release automatisch zu veröffentlichen (verwendet [OIDC](https://docs.npmjs.com/trusted-publishers)): +Der oben beschriebene, erzeugte `publish.yml`-Workflow veröffentlicht mit Provenance bei Versions-Tags automatisch auf npm. Da `yarn twenty app:publish` beim Ausführen in CI `--provenance` und `--access public` für Sie hinzufügt, benötigt der Workflow keine npm-Flags – nur die einmalige Trusted-Publisher-Einrichtung. -```yaml filename=".github/workflows/publish.yml" -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 -``` - -Für andere CI-Systeme (GitLab CI, CircleCI usw.) gelten die gleichen drei Befehle: `yarn install`, `yarn twenty dev:build` und anschließend `npm publish` aus `.twenty/output`. +Für andere CI-Systeme (GitLab CI, CircleCI usw.) führen Sie zuerst `yarn install` und dann `yarn twenty app:publish` aus. Provenance wird ausgegeben, wenn die Umgebung ein OIDC-Token erstellen kann, und andernfalls automatisch übersprungen. -**npm-Provenance** ist optional, wird jedoch empfohlen. Das Veröffentlichen mit `--provenance` fügt Ihrem npm-Eintrag ein Vertrauensabzeichen hinzu, sodass Nutzer überprüfen können, dass das Paket aus einem bestimmten Commit in einer öffentlichen CI-Pipeline gebaut wurde. Siehe die [npm-Provenance-Dokumentation](https://docs.npmjs.com/generating-provenance-statements) für Einrichtungshinweise. +**npm-Provenance** fügt Ihrem npm-Eintrag ein Vertrauensabzeichen hinzu, sodass Nutzer überprüfen können, dass das Paket aus einem bestimmten Commit in einer öffentlichen CI-Pipeline gebaut wurde. Damit können Sie außerdem die Inhaberschaft Ihrer App in einem Twenty-Marktplatz beanspruchen. Siehe die [npm-Provenance-Dokumentation](https://docs.npmjs.com/generating-provenance-statements) für Details. ## Apps installieren diff --git a/packages/twenty-docs/l/de/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/de/developers/extend/apps/operations/testing.mdx index e612a6e931..9076e8728b 100644 --- a/packages/twenty-docs/l/de/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/de/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ Dies führt `tsc --noEmit` unter Verwendung der `tsconfig.json` Ihrer App aus un Das Scaffolding-Tool erzeugt einen einsatzbereiten Workflow unter `.github/workflows/ci.yml`. Bei jedem Push auf `main` und jeder Pull-Request startet es einen kurzlebigen Twenty-Server im Runner (über die Aktion `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`) und führt anschließend `yarn lint`, `yarn typecheck`, `yarn test:unit` und `yarn test` aus, wobei `TWENTY_API_URL` / `TWENTY_API_KEY` auf diesen Server verweisen. Es sind keine Geheimnisse erforderlich, und Sie können die Serverversion über die Umgebungsvariable `TWENTY_VERSION` oben im Workflow fixieren. -Unter [Veröffentlichen → Automatisiertes CI/CD](/l/de/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) finden Sie eine vollständige Schritt-für-Schritt-Anleitung zu beiden eingerichteten Workflows (`ci.yml` und der `cd.yml`-Bereitstellungspipeline). +Unter [Veröffentlichen → Automatisiertes CI/CD](/l/de/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) finden Sie eine vollständige Schritt-für-Schritt-Anleitung zu den drei eingerichteten Workflows (`ci.yml`, der `cd.yml`-Bereitstellungspipeline und `publish.yml` für die npm-Veröffentlichung). diff --git a/packages/twenty-docs/l/es/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/es/developers/extend/apps/getting-started/project-structure.mdx index c558d32ded..514af45ab0 100644 --- a/packages/twenty-docs/l/es/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/es/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/es/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/es/developers/extend/apps/operations/publishing.mdx index 49e91d3a0a..2fb6c3b25b 100644 --- a/packages/twenty-docs/l/es/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/es/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ El servidor es la autoridad en la comprobación — valida `engines.twenty` tant ## CI/CD automatizado (flujos de trabajo preconfigurados) -Las aplicaciones generadas con `create-twenty-app` incluyen de forma predeterminada dos flujos de trabajo de GitHub Actions, en `.github/workflows/`. Están listas para ejecutarse en cuanto hagas push del repositorio a GitHub — no se necesita configuración adicional para CI, y CD solo requiere un único secreto. +Las aplicaciones generadas con `create-twenty-app` 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` @@ -157,9 +157,22 @@ La `TWENTY_DEPLOY_URL` predeterminada de `http://localhost:3000` es un marcador Añade la etiqueta `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:** + +1. Revisa tu aplicación, configura Node.js y actualiza npm (la publicación de confianza requiere npm 11.5.1 o posterior). +2. Ejecuta `yarn twenty app:publish`, que compila la aplicación y publica `.twenty/output` en npm. En CI agrega automáticamente `--provenance` y `--access public`, por lo que no se necesitan banderas en el flujo de trabajo. + +**Configuración única:** + +En npmjs.com abre tu paquete > **Settings → Trusted Publisher** y registra este repositorio con el flujo de trabajo `publish.yml` (consulta la [documentación de publicación de confianza de npm](https://docs.npmjs.com/trusted-publishers)). Publicar con provenance certifica qué repositorio de GitHub compiló el paquete, lo cual también es cómo reclamas la propiedad de tu aplicación en un marketplace de Twenty. + ### Fijar las acciones reutilizables -Ambos flujos de trabajo 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:`. +Los flujos de trabajo `ci.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 @@ -241,37 +254,12 @@ Si tu aplicación no define un `aboutDescription` en `defineApplication()`, el m ### Publicación en CI -Usa este flujo de trabajo de GitHub Actions para publicar automáticamente en cada versión (usa [OIDC](https://docs.npmjs.com/trusted-publishers)): +El flujo de trabajo `publish.yml` generado automáticamente descrito arriba publica en npm de forma automática en las etiquetas de versión, con provenance. Como `yarn twenty app:publish` añade `--provenance` y `--access public` por ti cuando se ejecuta en CI, el flujo de trabajo no necesita banderas de npm, solo la configuración única de trusted publisher. -```yaml filename=".github/workflows/publish.yml" -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 -``` - -Para otros sistemas de CI (GitLab CI, CircleCI, etc.), se aplican los mismos tres comandos: `yarn install`, `yarn twenty dev:build` y luego `npm publish` desde `.twenty/output`. +Para otros sistemas de CI (GitLab CI, CircleCI, etc.), ejecuta `yarn install` y luego `yarn twenty app:publish`. La provenance se emite cuando el entorno puede generar un token OIDC y, en caso contrario, se omite automáticamente. -**npm provenance** es opcional pero recomendable. Publicar con `--provenance` 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. Consulta la [documentación de npm sobre provenance](https://docs.npmjs.com/generating-provenance-statements) para las instrucciones de configuración. +La **provenance 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 npm sobre provenance](https://docs.npmjs.com/generating-provenance-statements) para más detalles. ## Instalar aplicaciones diff --git a/packages/twenty-docs/l/es/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/es/developers/extend/apps/operations/testing.mdx index a71f1efe38..0dcc98afe7 100644 --- a/packages/twenty-docs/l/es/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/es/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ Esto ejecuta `tsc --noEmit` contra el `tsconfig.json` de tu aplicación e inform El generador crea un flujo de trabajo listo para usar en `.github/workflows/ci.yml`. En cada push a `main` y en cada pull request, inicia un servidor efímero de Twenty en el runner (mediante la acción `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`), luego ejecuta `yarn lint`, `yarn typecheck`, `yarn test:unit` y `yarn test` con `TWENTY_API_URL` / `TWENTY_API_KEY` apuntando a ese servidor. No se requieren secretos y puedes fijar la versión del servidor mediante la variable de entorno `TWENTY_VERSION` en la parte superior del flujo de trabajo. -Consulta [Publicación → CI/CD automatizado](/l/es/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) para ver una guía completa de ambos flujos de trabajo generados (`ci.yml` y la canalización de despliegue `cd.yml`). +Consulta [Publicación → CI/CD automatizado](/l/es/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) para ver una guía completa de los tres flujos de trabajo generados (`ci.yml`, la canalización de despliegue `cd.yml` y `publish.yml` para la publicación en npm). diff --git a/packages/twenty-docs/l/fr/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/getting-started/project-structure.mdx index e3ee1cceb7..9041109fa0 100644 --- a/packages/twenty-docs/l/fr/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/fr/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/fr/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/operations/publishing.mdx index 72d61b96f6..48d079fbbb 100644 --- a/packages/twenty-docs/l/fr/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/fr/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ Le serveur est l'autorité de référence pour la vérification — il valide `e ## CI/CD automatisés (workflows préconfigurés) -Les applications générées avec `create-twenty-app` sont livrées avec deux workflows GitHub Actions prêts à l’emploi, sous `.github/workflows/`. Ils sont prêts à s’exécuter dès que vous poussez le dépôt sur GitHub — aucune configuration supplémentaire n’est nécessaire pour la CI, et le CD ne nécessite qu’un seul secret. +Les applications générées avec `create-twenty-app` sont livrées avec trois workflows GitHub Actions prêts à l’emploi, sous `.github/workflows/`. L’intégration continue (CI) s’exécute sans configuration, le déploiement continu (CD) ne nécessite qu’un seul secret, et la publication sur npm requiert une configuration unique de npm trusted-publisher. ### CI — `ci.yml` @@ -157,9 +157,22 @@ La valeur par défaut de `TWENTY_DEPLOY_URL`, `http://localhost:3000`, est un es Ajoutez le label `deploy` à une pull request. La condition `if:` dans `cd.yml` exécutera le job pour cette PR en utilisant le commit de tête de la PR, vous permettant de valider une modification sur le serveur cible avant la fusion. +### Publication — `publish.yml` + +Publie votre application sur npm avec provenance lorsque vous poussez une étiquette de version (par exemple `v1.0.0`), ou lorsque vous exécutez manuellement le workflow depuis l’onglet Actions. + +**Ce que cela fait:** + +1. Récupère votre application, configure Node.js et met à jour npm (la publication de confiance nécessite npm 11.5.1 ou une version ultérieure). +2. Exécute `yarn twenty app:publish`, qui génère l’application et publie `.twenty/output` sur npm. En CI, il ajoute automatiquement `--provenance` et `--access public`, de sorte qu’aucun indicateur n’est nécessaire dans le workflow. + +**Configuration unique :** + +Sur npmjs.com, ouvrez votre package > **Settings → Trusted Publisher** et enregistrez ce dépôt avec le workflow `publish.yml` (voir la [documentation npm sur la publication de confiance](https://docs.npmjs.com/trusted-publishers)). La publication avec provenance certifie quel dépôt GitHub a construit le package, ce qui est aussi la façon de revendiquer la propriété de votre application dans une marketplace Twenty. + ### Épingler les actions réutilisables -Les deux workflows référencent des actions réutilisables sur `@main`, de sorte que les mises à jour des actions dans le dépôt `twentyhq/twenty` sont récupérées automatiquement. Si vous souhaitez des builds déterministes, remplacez `@main` par un SHA de commit ou un tag de version sur chaque ligne `uses:`. +Les workflows `ci.yml` et `cd.yml` référencent des actions réutilisables sur `@main`, de sorte que les mises à jour des actions dans le dépôt `twentyhq/twenty` sont récupérées automatiquement. Si vous souhaitez des builds déterministes, remplacez `@main` par un SHA de commit ou un tag de version sur chaque ligne `uses:`. ## Publication sur npm @@ -241,37 +254,12 @@ Si votre application ne définit pas de `aboutDescription` dans `defineApplicati ### Publication via CI -Utilisez ce workflow GitHub Actions pour publier automatiquement à chaque version (utilise [OIDC](https://docs.npmjs.com/trusted-publishers)) : +Le workflow `publish.yml` préconfiguré décrit ci-dessus publie automatiquement sur npm lors des tags de version, avec provenance. Comme `yarn twenty app:publish` ajoute `--provenance` et `--access public` pour vous lorsqu’il s’exécute en CI, le workflow n’a besoin d’aucun indicateur npm — seulement de la configuration unique du trusted publisher. -```yaml filename=".github/workflows/publish.yml" -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 -``` - -Pour d'autres systèmes CI (GitLab CI, CircleCI, etc.), les mêmes trois commandes s'appliquent : `yarn install`, `yarn twenty dev:build`, puis `npm publish` depuis `.twenty/output`. +Pour d’autres systèmes de CI (GitLab CI, CircleCI, etc.), exécutez `yarn install` puis `yarn twenty app:publish`. La provenance est émise lorsque l’environnement peut générer un jeton OIDC et est ignorée automatiquement dans le cas contraire. -**npm provenance** est facultatif mais recommandé. Publier avec `--provenance` ajoute un badge de confiance à votre fiche npm, permettant aux utilisateurs de vérifier que le package a été construit à partir d'un commit spécifique dans un pipeline CI public. Voir la [documentation npm sur la provenance](https://docs.npmjs.com/generating-provenance-statements) pour les instructions de configuration. +La **provenance npm** ajoute un badge de confiance à votre fiche npm, permettant aux utilisateurs de vérifier que le package a été construit à partir d’un commit spécifique dans un pipeline CI public. C’est également ce qui vous permet de revendiquer la propriété de votre application dans une marketplace Twenty. Voir la [documentation npm sur la provenance](https://docs.npmjs.com/generating-provenance-statements) pour plus de détails. ## Installation des applications diff --git a/packages/twenty-docs/l/fr/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/operations/testing.mdx index fea5c9ded0..583603ee83 100644 --- a/packages/twenty-docs/l/fr/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/fr/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ Cela exécute `tsc --noEmit` sur le `tsconfig.json` de votre application et sign Le générateur crée un workflow prêt à l’emploi dans `.github/workflows/ci.yml`. À chaque push sur `main` et à chaque pull request, il lance un serveur Twenty éphémère dans le runner (via l’action `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`), puis exécute `yarn lint`, `yarn typecheck`, `yarn test:unit` et `yarn test` avec `TWENTY_API_URL` / `TWENTY_API_KEY` pointant vers ce serveur. Aucun secret n’est requis, et vous pouvez fixer la version du serveur via la variable d’environnement `TWENTY_VERSION` en haut du workflow. -Voir [Publication → CI/CD automatisé](/l/fr/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) pour un guide complet des deux workflows générés (`ci.yml` et le pipeline de déploiement `cd.yml`). +Voir [Publication → CI/CD automatisé](/l/fr/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) pour un guide complet des trois workflows générés (`ci.yml`, le pipeline de déploiement `cd.yml` et `publish.yml` pour la publication sur npm). diff --git a/packages/twenty-docs/l/it/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/it/developers/extend/apps/getting-started/project-structure.mdx index 251607e1ac..cf548b845d 100644 --- a/packages/twenty-docs/l/it/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/it/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/it/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/it/developers/extend/apps/operations/publishing.mdx index b76165ddd0..b901d98396 100644 --- a/packages/twenty-docs/l/it/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/it/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ Il server è l'autorità di controllo — convalida `engines.twenty` sia durante ## CI/CD automatizzati (workflow preconfigurati) -Le app generate con `create-twenty-app` includono due workflow di GitHub Actions pronti all'uso, nella cartella `.github/workflows/`. Sono pronti all'esecuzione non appena esegui il push del repository su GitHub — non è necessaria alcuna configurazione aggiuntiva per la CI e la CD richiede solo un singolo secret. +Le app generate con `create-twenty-app` includono tre workflow di GitHub Actions pronti all'uso, nella cartella `.github/workflows/`. L'esecuzione della CI non richiede alcuna configurazione, la CD richiede un solo secret e la pubblicazione su npm richiede una configurazione una tantum di npm trusted-publisher. ### CI — `ci.yml` @@ -157,9 +157,22 @@ Il valore predefinito di `TWENTY_DEPLOY_URL`, `http://localhost:3000`, è un seg Aggiungi l'etichetta `deploy` a una pull request. La condizione `if:` in `cd.yml` eseguirà il job per quella PR utilizzando il commit di testa della PR, permettendoti di convalidare una modifica sul server di destinazione prima del merge. +### Pubblica — `publish.yml` + +Pubblica la tua app su npm con attestazione di provenienza quando esegui il push di un tag di versione (ad es. `v1.0.0`), oppure quando esegui manualmente il workflow dalla scheda Actions. + +**Cosa fa:** + +1. Clona la tua app, configura Node.js e aggiorna npm (la pubblicazione con attendibilità richiede npm 11.5.1 o versioni successive). +2. Esegue `yarn twenty app:publish`, che crea la build dell'app e pubblica `.twenty/output` su npm. In CI aggiunge automaticamente `--provenance` e `--access public`, quindi non sono necessari flag nel workflow. + +**Impostazione una tantum:** + +Su npmjs.com apri il tuo pacchetto > **Settings → Trusted Publisher** e registra questo repository con il workflow `publish.yml` (consulta la [documentazione su npm trusted publishing](https://docs.npmjs.com/trusted-publishers)). La pubblicazione con provenance certifica quale repository GitHub ha creato il pacchetto ed è anche il modo in cui dichiari la proprietà della tua app in un marketplace Twenty. + ### Bloccare le azioni riutilizzabili -Entrambi i workflow fanno riferimento ad azioni riutilizzabili a `@main`, quindi gli aggiornamenti delle azioni nel repository `twentyhq/twenty` vengono recepiti automaticamente. Se desideri build deterministiche, sostituisci `@main` con uno SHA di commit o un tag di release in ciascuna riga `uses:`. +I workflow `ci.yml` e `cd.yml` fanno riferimento ad azioni riutilizzabili a `@main`, quindi gli aggiornamenti delle azioni nel repository `twentyhq/twenty` vengono recepiti automaticamente. Se desideri build deterministiche, sostituisci `@main` con uno SHA di commit o un tag di release in ciascuna riga `uses:`. ## Pubblicazione su npm @@ -241,37 +254,12 @@ Se la tua app non definisce un `aboutDescription` in `defineApplication()`, il m ### Pubblicazione con CI -Usa questo workflow di GitHub Actions per pubblicare automaticamente a ogni release (usa [OIDC](https://docs.npmjs.com/trusted-publishers)): +Il workflow `publish.yml` generato dallo scaffold descritto sopra pubblica automaticamente su npm sui tag di versione, con provenance. Poiché `yarn twenty app:publish` aggiunge `--provenance` e `--access public` per te quando viene eseguito in CI, il workflow non ha bisogno di flag npm — serve solo l'impostazione una tantum del trusted publisher. -```yaml filename=".github/workflows/publish.yml" -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 -``` - -Per altri sistemi CI (GitLab CI, CircleCI, ecc.), si applicano gli stessi tre comandi: `yarn install`, `yarn twenty dev:build`, quindi `npm publish` da `.twenty/output`. +Per altri sistemi CI (GitLab CI, CircleCI, ecc.), esegui `yarn install` e poi `yarn twenty app:publish`. La provenance viene emessa quando l'ambiente può generare un token OIDC e, in caso contrario, viene saltata automaticamente. -**npm provenance** è opzionale ma consigliata. La pubblicazione con `--provenance` aggiunge un badge di attendibilità alla tua scheda npm, consentendo agli utenti di verificare che il pacchetto sia stato creato a partire da uno specifico commit in una pipeline CI pubblica. Consulta la [documentazione su npm provenance](https://docs.npmjs.com/generating-provenance-statements) per le istruzioni di configurazione. +La **npm provenance** aggiunge un badge di attendibilità alla tua scheda npm, consentendo agli utenti di verificare che il pacchetto sia stato creato a partire da uno specifico commit in una pipeline CI pubblica. È anche ciò che ti permette di dichiarare la proprietà della tua app in un marketplace Twenty. Consulta la [documentazione su npm provenance](https://docs.npmjs.com/generating-provenance-statements) per maggiori dettagli. ## Installazione delle app diff --git a/packages/twenty-docs/l/it/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/it/developers/extend/apps/operations/testing.mdx index 22757a838c..b614b47bd4 100644 --- a/packages/twenty-docs/l/it/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/it/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ Questo esegue `tsc --noEmit` sul file `tsconfig.json` della tua app e riporta ev Lo strumento di scaffolding genera un workflow pronto all'uso in `.github/workflows/ci.yml`. A ogni push su `main` e a ogni pull request, avvia un server Twenty effimero nel runner (tramite l'azione `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`), quindi esegue `yarn lint`, `yarn typecheck`, `yarn test:unit` e `yarn test` con `TWENTY_API_URL` / `TWENTY_API_KEY` che puntano a quel server. Non sono necessari segreti e puoi fissare la versione del server tramite la variabile di ambiente `TWENTY_VERSION` all'inizio del workflow. -Vedi [Pubblicazione → CI/CD automatizzato](/l/it/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) per una spiegazione completa di entrambi i workflow generati dallo scaffolder (`ci.yml` e la pipeline di deploy `cd.yml`). +Vedi [Pubblicazione → CI/CD automatizzato](/l/it/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) per una spiegazione completa dei tre workflow generati dallo scaffolder (`ci.yml`, la pipeline di deploy `cd.yml` e `publish.yml` per la pubblicazione su npm). diff --git a/packages/twenty-docs/l/ja/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/getting-started/project-structure.mdx index 36f77dcc9c..a30a748c29 100644 --- a/packages/twenty-docs/l/ja/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/ja/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/ja/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/operations/publishing.mdx index afb406eb05..537cb90237 100644 --- a/packages/twenty-docs/l/ja/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/ja/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ tarball アプリは公開マーケットプレイスには掲載されないた ## 自動化された CI/CD（スキャフォールド済みのワークフロー） -`create-twenty-app` で生成されたアプリには、`.github/workflows/` 配下に GitHub Actions のワークフローが 2 つ、最初から同梱されています。 リポジトリを GitHub にプッシュするとすぐに実行可能です。CI に追加のセットアップは不要で、CD にはシークレットを 1 つ用意するだけです。 +`create-twenty-app` で生成されたアプリには、`.github/workflows/` 配下に GitHub Actions のワークフローが 3 つ、最初から同梱されています。 CI はセットアップ不要で実行でき、CD には 1 つのシークレットを設定するだけでよく、npm への公開には 1 回だけの npm trusted-publisher セットアップが必要です。 ### CI — `ci.yml` @@ -157,9 +157,22 @@ tarball アプリは公開マーケットプレイスには掲載されないた プルリクエストに `deploy` ラベルを追加します。 `cd.yml` の `if:` ガードにより、その PR のヘッドコミットを使ってジョブが実行され、マージ前に対象サーバー上で変更を検証できます。 +### 公開 — `publish.yml` + +バージョンタグ（例: `v1.0.0`）をプッシュしたとき、または Actions タブからワークフローを手動実行したときに、プロビナンス付きでアプリを npm に公開します。 + +**機能:** + +1. あなたのアプリをチェックアウトし、Node.js をセットアップして npm を更新します（信頼できる公開には npm 11.5.1 以降が必要です）。 +2. `yarn twenty app:publish` を実行します。これによりアプリがビルドされ、`.twenty/output` が npm に公開されます。 CI 環境では自動的に `--provenance` と `--access public` が追加されるため、ワークフロー内でフラグを指定する必要はありません。 + +**一度きりのセットアップ:** + +npmjs.com で自分のパッケージを開き、**Settings → Trusted Publisher** から、このリポジトリを `publish.yml` ワークフローで登録します（詳しくは [npm trusted publishing docs](https://docs.npmjs.com/trusted-publishers) を参照してください）。 provenance 付きで公開すると、どの GitHub リポジトリがそのパッケージをビルドしたかが証明されます。これは、Twenty マーケットプレイスでアプリの所有権を主張する方法にもなります。 + ### 再利用可能なアクションのバージョン固定 -両方のワークフローは再利用可能なアクションを `@main` で参照しているため、`twentyhq/twenty` リポジトリでのアクション更新が自動的に取り込まれます。 ビルドを決定的にしたい場合は、各 `uses:` 行の `@main` をコミット SHA またはリリースタグに置き換えてください。 +`ci.yml` と `cd.yml` のワークフローは、`@main` の再利用可能なアクションを参照しているため、`twentyhq/twenty` リポジトリでのアクションの更新が自動的に取り込まれます。 ビルドを決定的にしたい場合は、各 `uses:` 行の `@main` をコミット SHA またはリリースタグに置き換えてください。 ## npm への公開 @@ -241,37 +254,12 @@ yarn twenty dev:catalog-sync ### CI での公開 -この GitHub Actions のワークフローを使用すると、各リリース時に自動で公開できます（[OIDC](https://docs.npmjs.com/trusted-publishers) を使用）。 +上で説明したスキャフォールド済みの `publish.yml` ワークフローは、バージョンタグが付けられたときに provenance 情報付きで自動的に npm へ公開します。 `yarn twenty app:publish` は CI で実行される際に `--provenance` と `--access public` を自動的に追加するため、ワークフローで npm フラグを指定する必要はありません。一度きりの trusted-publisher セットアップだけが必要です。 -```yaml filename=".github/workflows/publish.yml" -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 など）でも同じ3つのコマンドを使用します: `yarn install`、`yarn twenty dev:build`、そして `.twenty/output` から `npm publish` を実行します。 +その他の CI システム（GitLab CI、CircleCI など）の場合は、`yarn install` を実行してから `yarn twenty app:publish` を実行します。 環境が OIDC トークンを発行できる場合は provenance が生成され、それ以外の場合は自動的にスキップされます。 -**npm provenance** は任意ですが、推奨されます。 `--provenance` を付けて公開すると、npm のリスティングにトラストバッジが追加され、公開 CI パイプラインの特定のコミットからビルドされたことをユーザーが検証できるようになります。 セットアップ手順は、[npm provenance のドキュメント](https://docs.npmjs.com/generating-provenance-statements)を参照してください。 +**npm provenance** により npm のリスティングにトラストバッジが追加され、公開 CI パイプライン上の特定のコミットからビルドされたパッケージであることをユーザーが検証できるようになります。 また、これにより Twenty マーケットプレイスでアプリの所有権を主張できるようになります。 詳細は [npm provenance のドキュメント](https://docs.npmjs.com/generating-provenance-statements)を参照してください。 ## アプリのインストール diff --git a/packages/twenty-docs/l/ja/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/operations/testing.mdx index e7aee97c8e..4df643a437 100644 --- a/packages/twenty-docs/l/ja/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/ja/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ yarn twenty dev:typecheck スキャフォルダーは、すぐに使えるワークフローを `.github/workflows/ci.yml` に生成します。 `main` へのすべてのプッシュおよびすべてのプルリクエスト時に、ランナー内で一時的な Twenty サーバーを起動（`twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test` アクション経由）し、そのサーバーを指すように `TWENTY_API_URL` / `TWENTY_API_KEY` を設定した上で、`yarn lint`、`yarn typecheck`、`yarn test:unit`、`yarn test` を実行します。 シークレットは一切不要で、ワークフローの先頭にある `TWENTY_VERSION` 環境変数を通じてサーバーバージョンを固定できます。 -スキャフォルドされた 2 つのワークフロー（`ci.yml` と `cd.yml` デプロイパイプライン）の詳細な手順については、[Publishing → Automated CI/CD](/l/ja/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) を参照してください。 +スキャフォルドされた 3 つのワークフロー（`ci.yml`、`cd.yml` デプロイパイプライン、npm パブリッシング用の `publish.yml`）の詳細な手順については、[Publishing → Automated CI/CD](/l/ja/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) を参照してください。 diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/getting-started/project-structure.mdx index f3f7915378..c927b2b710 100644 --- a/packages/twenty-docs/l/ko/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/ko/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/operations/publishing.mdx index 5ca746b621..c661d9cb0f 100644 --- a/packages/twenty-docs/l/ko/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/ko/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ yarn twenty app:publish --private ## 자동화된 CI/CD (스캐폴드된 워크플로) -`create-twenty-app`으로 생성된 앱은 `.github/workflows/` 아래에 기본으로 두 개의 GitHub Actions 워크플로가 포함되어 있습니다. 저장소를 GitHub에 푸시하는 즉시 실행할 준비가 되어 있습니다 — CI에는 추가 설정이 필요 없고, CD에는 단 하나의 시크릿만 필요합니다. +`create-twenty-app`으로 생성된 앱은 `.github/workflows/` 아래에 기본으로 세 개의 GitHub Actions 워크플로가 포함되어 있습니다. CI는 별도 설정 없이 실행되며, CD는 하나의 시크릿만 필요하고, npm으로의 배포는 한 번만 설정하면 되는 npm trusted-publisher 설정이 필요합니다. ### CI — `ci.yml` @@ -157,9 +157,22 @@ yarn twenty app:publish --private 풀 리퀘스트에 `deploy` 라벨을 추가하세요. `cd.yml`의 `if:` 가드는 해당 PR의 헤드 커밋을 사용해 그 PR에 대한 잡을 실행하므로, 머지 전에 대상 서버에서 변경 사항을 검증할 수 있습니다. +### 게시 — `publish.yml` + +버전 태그(예: `v1.0.0`)를 푸시하거나 Actions 탭에서 워크플로를 수동으로 실행하면, 출처 정보(provenance)와 함께 앱을 npm에 게시합니다. + +**하는 일:** + +1. 앱을 체크아웃하고 Node.js를 설정한 다음 npm을 업데이트합니다(신뢰할 수 있는 게시 기능을 사용하려면 npm 11.5.1 이상이 필요합니다). +2. `yarn twenty app:publish`를 실행하여 앱을 빌드하고 `.twenty/output`를 npm에 게시합니다. CI에서는 자동으로 `--provenance` 및 `--access public`를 추가하므로, 워크플로에는 플래그가 필요하지 않습니다. + +**일회성 설정:** + +npmjs.com에서 패키지를 연 다음 **Settings → Trusted Publisher**로 이동하여 이 저장소를 `publish.yml` 워크플로에 등록하세요([npm trusted publishing 문서](https://docs.npmjs.com/trusted-publishers)를 참고하세요). provenance와 함께 게시하면 어떤 GitHub 리포지터리가 패키지를 빌드했는지 증명되며, 이는 Twenty 마켓플레이스에서 앱 소유권을 주장하는 방법이기도 합니다. + ### 재사용 가능한 액션 고정하기 -두 워크플로 모두 `@main`의 재사용 가능한 액션을 참조하므로, `twentyhq/twenty` 저장소의 액션 업데이트가 자동으로 반영됩니다. 결정적 빌드를 원한다면, 각 `uses:` 줄에서 `@main`을 커밋 SHA 또는 릴리스 태그로 바꾸세요. +`ci.yml` 및 `cd.yml` 워크플로는 `@main`의 재사용 가능한 액션을 참조하므로, `twentyhq/twenty` 리포지터리의 액션 업데이트가 자동으로 반영됩니다. 결정적 빌드를 원한다면, 각 `uses:` 줄에서 `@main`을 커밋 SHA 또는 릴리스 태그로 바꾸세요. ## npm에 게시 @@ -241,37 +254,12 @@ yarn twenty dev:catalog-sync ### CI 게시 -모든 릴리스마다 자동으로 게시하려면 이 GitHub Actions 워크플로를 사용하세요([OIDC](https://docs.npmjs.com/trusted-publishers) 사용): +위에서 설명한 스캐폴딩된 `publish.yml` 워크플로는 버전 태그에 따라 provenance와 함께 npm에 자동으로 게시합니다. `yarn twenty app:publish`는 CI에서 실행될 때 `--provenance` 및 `--access public`를 자동으로 추가하므로, 워크플로에는 npm 플래그가 전혀 필요하지 않고 한 번만 설정하는 trusted-publisher만 있으면 됩니다. -```yaml filename=".github/workflows/publish.yml" -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`, 그리고 `.twenty/output`에서 `npm publish`. +다른 CI 시스템(GitLab CI, CircleCI 등)에서는 `yarn install`을 실행한 다음 `yarn twenty app:publish`를 실행하세요. 환경에서 OIDC 토큰을 생성할 수 있을 때는 provenance가 생성되고, 그렇지 않은 경우에는 자동으로 건너뜁니다. -**npm provenance**는 선택 사항이지만 권장됩니다. `--provenance` 옵션으로 게시하면 npm 목록에 신뢰 배지가 추가되어, 사용자가 공개 CI 파이프라인의 특정 커밋에서 패키지가 빌드되었는지 확인할 수 있습니다. 설정 방법은 [npm provenance 문서](https://docs.npmjs.com/generating-provenance-statements)를 참고하세요. +**npm provenance**는 npm 목록에 신뢰 배지를 추가하여, 사용자가 공개 CI 파이프라인의 특정 커밋에서 패키지가 빌드되었는지 검증할 수 있게 해줍니다. 또한 Twenty 마켓플레이스에서 앱 소유권을 주장할 수 있게 해 주는 요소이기도 합니다. 자세한 내용은 [npm provenance 문서](https://docs.npmjs.com/generating-provenance-statements)를 참고하세요. ## 앱 설치 diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/operations/testing.mdx index 2af264d26a..943d2a75e1 100644 --- a/packages/twenty-docs/l/ko/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/ko/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ yarn twenty dev:typecheck 스캐폴더는 `.github/workflows/ci.yml`에 바로 사용할 수 있는 워크플로를 생성합니다. `main`으로의 모든 푸시와 모든 풀 리퀘스트마다, 러너에서 임시 Twenty 서버를 실행하고(`twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test` 액션을 통해), 그 서버를 가리키도록 설정된 `TWENTY_API_URL` / `TWENTY_API_KEY`와 함께 `yarn lint`, `yarn typecheck`, `yarn test:unit`, `yarn test`를 실행합니다. 시크릿은 필요 없으며, 워크플로 상단의 `TWENTY_VERSION` 환경 변수로 서버 버전을 고정할 수 있습니다. -스캐폴딩된 두 워크플로(`ci.yml` 및 `cd.yml` 배포 파이프라인)에 대한 전체 단계별 안내는 [Publishing → Automated CI/CD](/l/ko/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows)를 참고하세요. +스캐폴딩된 세 워크플로(`ci.yml`, `cd.yml` 배포 파이프라인, npm 게시용 `publish.yml`)에 대한 전체 단계별 안내는 [Publishing → Automated CI/CD](/l/ko/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows)를 참고하세요. diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/getting-started/project-structure.mdx index 9a00033e46..640d6c5bd8 100644 --- a/packages/twenty-docs/l/pt/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/pt/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/operations/publishing.mdx index ee92e3083d..0a363dab31 100644 --- a/packages/twenty-docs/l/pt/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/pt/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ O servidor realiza a verificação definitiva — ele valida `engines.twenty` ta ## CI/CD automatizado (fluxos de trabalho pré-configurados) -Os apps gerados com `create-twenty-app` já vêm com dois fluxos de trabalho do GitHub Actions prontos, em `.github/workflows/`. Eles estão prontos para executar assim que você fizer push do repositório para o GitHub — nenhuma configuração extra é necessária para CI, e CD requer apenas um único segredo. +Os apps gerados com `create-twenty-app` já vêm com três fluxos de trabalho do GitHub Actions prontos, em `.github/workflows/`. A CI é executada sem nenhuma configuração, a CD requer um único segredo e a publicação no npm exige uma configuração única de trusted-publisher do npm. ### CI — `ci.yml` @@ -157,9 +157,22 @@ O `TWENTY_DEPLOY_URL` padrão de `http://localhost:3000` é um placeholder — e Adicione o rótulo `deploy` a um pull request. A condição `if:` em `cd.yml` executará o job para esse PR usando o commit HEAD do PR, permitindo que você valide uma alteração no servidor de destino antes de fazer o merge. +### Publicar — `publish.yml` + +Publica seu app no npm com procedência quando você envia uma tag de versão (por exemplo, `v1.0.0`), ou quando executa o fluxo de trabalho manualmente na aba Actions. + +**O que faz:** + +1. Faz o checkout do seu app, configura o Node.js e atualiza o npm (a publicação confiável requer o npm 11.5.1 ou posterior). +2. Executa `yarn twenty app:publish`, que compila o app e publica `.twenty/output` no npm. Em CI, adiciona automaticamente `--provenance` e `--access public`, portanto não são necessárias flags no fluxo de trabalho. + +**Configuração única:** + +Em npmjs.com, abra o seu pacote > **Settings → Trusted Publisher** e registre este repositório com o fluxo de trabalho `publish.yml` (consulte a [documentação de publicação confiável do npm](https://docs.npmjs.com/trusted-publishers)). Publicar com proveniência certifica qual repositório do GitHub compilou o pacote, o que também é como você reivindica a propriedade do seu app em um marketplace da Twenty. + ### Fixando as ações reutilizáveis -Ambos os fluxos de trabalho fazem referência a ações reutilizáveis em `@main`, portanto as atualizações de ações no repositório `twentyhq/twenty` são aplicadas automaticamente. Se você quiser builds determinísticos, substitua `@main` por um SHA de commit ou uma tag de release em cada linha `uses:`. +Os fluxos de trabalho `ci.yml` e `cd.yml` fazem referência a ações reutilizáveis em `@main`, portanto as atualizações de ações no repositório `twentyhq/twenty` são aplicadas automaticamente. Se você quiser builds determinísticos, substitua `@main` por um SHA de commit ou uma tag de release em cada linha `uses:`. ## Publicação no npm @@ -241,37 +254,12 @@ Se o seu aplicativo não definir um `aboutDescription` em `defineApplication()`, ### Publicação via CI -Use este workflow do GitHub Actions para publicar automaticamente a cada release (usa [OIDC](https://docs.npmjs.com/trusted-publishers)): +O fluxo de trabalho `publish.yml` estruturado conforme descrito acima publica automaticamente no npm em tags de versão, com proveniência. Como `yarn twenty app:publish` adiciona `--provenance` e `--access public` para você quando é executado em CI, o fluxo de trabalho não precisa de flags do npm — apenas da configuração única de trusted publisher. -```yaml filename=".github/workflows/publish.yml" -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 -``` - -Para outros sistemas de CI (GitLab CI, CircleCI etc.), aplicam-se os mesmos três comandos: `yarn install`, `yarn twenty dev:build` e, em seguida, `npm publish` a partir de `.twenty/output`. +Para outros sistemas de CI (GitLab CI, CircleCI, etc.), execute `yarn install` e depois `yarn twenty app:publish`. A proveniência é emitida quando o ambiente pode gerar um token OIDC e é ignorada automaticamente caso contrário. -**Proveniência do npm** é opcional, mas recomendada. Publicar com `--provenance` adiciona um selo de confiança à sua listagem no npm, permitindo que os usuários verifiquem que o pacote foi construído a partir de um commit específico em um pipeline de CI público. Consulte a [documentação de proveniência do npm](https://docs.npmjs.com/generating-provenance-statements) para instruções de configuração. +A **proveniência do npm** adiciona um selo de confiança à sua listagem no npm, permitindo que os usuários verifiquem que o pacote foi construído a partir de um commit específico em um pipeline de CI público. É também o que permite que você reivindique a propriedade do seu app em um marketplace da Twenty. Consulte a [documentação de proveniência do npm](https://docs.npmjs.com/generating-provenance-statements) para mais detalhes. ## Instalando aplicativos diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/operations/testing.mdx index 76d6785811..6d388c0714 100644 --- a/packages/twenty-docs/l/pt/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/pt/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ Isso executa `tsc --noEmit` no `tsconfig.json` do seu app e informa quaisquer er O gerador de scaffold cria um workflow pronto para uso em `.github/workflows/ci.yml`. A cada push para `main` e a cada pull request, ele inicia um servidor Twenty efêmero no runner (por meio da action `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`) e então executa `yarn lint`, `yarn typecheck`, `yarn test:unit` e `yarn test` com `TWENTY_API_URL` / `TWENTY_API_KEY` apontando para esse servidor. Nenhum secret é necessário e você pode fixar a versão do servidor por meio da variável de ambiente `TWENTY_VERSION` no topo do workflow. -Consulte [Publicação → CI/CD automatizado](/l/pt/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) para um passo a passo completo de ambos os workflows criados pelo scaffold (`ci.yml` e o pipeline de deploy `cd.yml`). +Consulte [Publicação → CI/CD automatizado](/l/pt/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) para um passo a passo completo dos três workflows criados pelo scaffold (`ci.yml`, o pipeline de deploy `cd.yml` e `publish.yml` para publicação no npm). diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/getting-started/project-structure.mdx index b5327bf6f5..a1416a9af8 100644 --- a/packages/twenty-docs/l/ro/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/ro/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/operations/publishing.mdx index bdc43b49ee..241ebadd1e 100644 --- a/packages/twenty-docs/l/ro/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/ro/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ Serverul este verificarea autoritativă — validează `engines.twenty` atât la ## CI/CD automatizat (fluxuri de lucru preconfigurate) -Aplicațiile generate cu `create-twenty-app` vin, gata de utilizare, cu două fluxuri de lucru GitHub Actions, în `.github/workflows/`. Acestea sunt gata să ruleze imediat ce faci push al repozitoriului pe GitHub — nu este necesară nicio configurare suplimentară pentru CI, iar CD necesită doar un singur secret. +Aplicațiile generate cu `create-twenty-app` vin, gata de utilizare, cu trei fluxuri de lucru GitHub Actions, în `.github/workflows/`. CI rulează fără nicio configurare, CD necesită un singur secret, iar publicarea pe npm necesită o configurare unică pentru npm trusted publisher. ### CI — `ci.yml` @@ -157,9 +157,22 @@ Valoarea implicită a `TWENTY_DEPLOY_URL`, `http://localhost:3000`, este un plac Adaugă eticheta `deploy` la un pull request. Condiția `if:` din `cd.yml` va rula jobul pentru acel PR folosind commitul head al PR-ului, permițându-ți să validezi o modificare pe serverul țintă înainte de a face merge. +### Publicare — `publish.yml` + +Publică aplicația pe npm, cu proveniență, când împingi un tag de versiune (de ex. `v1.0.0`) sau când rulezi manual fluxul de lucru din fila Actions. + +**Ce face:** + +1. Face checkout pentru aplicația ta, configurează Node.js și actualizează npm (publicarea de încredere necesită npm 11.5.1 sau o versiune ulterioară). +2. Rulează `yarn twenty app:publish`, care construiește aplicația și publică `.twenty/output` în npm. În CI adaugă automat `--provenance` și `--access public`, astfel încât nu sunt necesari indicatori în workflow. + +**Configurare unică:** + +Pe npmjs.com deschide pachetul tău > **Settings → Trusted Publisher** și înregistrează acest repository cu workflow-ul `publish.yml` (vezi [documentația npm trusted publishing](https://docs.npmjs.com/trusted-publishers)). Publicarea cu provenance certifică ce repository GitHub a construit pachetul, ceea ce este, de asemenea, modul în care îți revendici proprietatea asupra aplicației tale într-un marketplace Twenty. + ### Fixarea acțiunilor reutilizabile -Ambele fluxuri de lucru fac referire la acțiuni reutilizabile la `@main`, astfel încât actualizările acțiunilor din repo-ul `twentyhq/twenty` sunt preluate automat. Dacă dorești builduri deterministe, înlocuiește `@main` cu un SHA de commit sau cu un tag de release pe fiecare linie `uses:`. +Workflows `ci.yml` și `cd.yml` fac referire la acțiuni reutilizabile la `@main`, astfel încât actualizările acțiunilor din repo-ul `twentyhq/twenty` sunt preluate automat. Dacă dorești builduri deterministe, înlocuiește `@main` cu un SHA de commit sau cu un tag de release pe fiecare linie `uses:`. ## Publicarea pe npm @@ -241,37 +254,12 @@ Dacă aplicația ta nu definește un `aboutDescription` în `defineApplication() ### Publicare CI -Folosește acest workflow GitHub Actions pentru a publica automat la fiecare release (folosește [OIDC](https://docs.npmjs.com/trusted-publishers)): +Workflow-ul generat `publish.yml` descris mai sus publică automat în npm la etichetele de versiune, cu provenance. Deoarece `yarn twenty app:publish` adaugă `--provenance` și `--access public` pentru tine când rulează în CI, workflow-ul nu are nevoie de indicatori npm — doar de configurarea unică a trusted-publisher. -```yaml filename=".github/workflows/publish.yml" -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 -``` - -Pentru alte sisteme CI (GitLab CI, CircleCI etc.), se aplică aceleași trei comenzi: `yarn install`, `yarn twenty dev:build`, apoi `npm publish` din `.twenty/output`. +Pentru alte sisteme CI (GitLab CI, CircleCI etc.), rulează `yarn install` apoi `yarn twenty app:publish`. Provenance este emisă atunci când mediul poate genera un token OIDC și este omisă automat în caz contrar. -**npm provenance** este opțională, dar recomandată. Publicarea cu `--provenance` adaugă un badge de încredere la listarea ta în npm, permițând utilizatorilor să verifice că pachetul a fost construit dintr-un commit specific într-un pipeline CI public. Vezi [documentația npm provenance](https://docs.npmjs.com/generating-provenance-statements) pentru instrucțiuni de configurare. +**npm provenance** adaugă un badge de încredere la listarea ta în npm, permițând utilizatorilor să verifice că pachetul a fost construit dintr-un commit specific într-un pipeline CI public. Este, de asemenea, ceea ce îți permite să revendici proprietatea asupra aplicației tale într-un marketplace Twenty. Vezi [documentația npm provenance](https://docs.npmjs.com/generating-provenance-statements) pentru detalii. ## Instalarea aplicațiilor diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/operations/testing.mdx index 80c779d109..c5ce97a9c6 100644 --- a/packages/twenty-docs/l/ro/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/ro/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ Aceasta rulează `tsc --noEmit` pe fișierul `tsconfig.json` al aplicației și Scaffolderul generează un workflow gata de utilizare la `.github/workflows/ci.yml`. La fiecare push pe `main` și la fiecare pull request, acesta pornește un server Twenty efemer în runner (prin acțiunea `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`), apoi rulează `yarn lint`, `yarn typecheck`, `yarn test:unit` și `yarn test` cu `TWENTY_API_URL` / `TWENTY_API_KEY` îndreptate către acel server. Nu sunt necesare secrete și poți fixa versiunea serverului prin variabila de mediu `TWENTY_VERSION` din partea de sus a workflow-ului. -Vezi [Publicare → CI/CD automatizat](/l/ro/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) pentru un ghid complet al ambelor workflow-uri create cu scaffolderul (`ci.yml` și pipeline-ul de deploy `cd.yml`). +Vezi [Publicare → CI/CD automatizat](/l/ro/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) pentru un ghid complet al celor trei workflow-uri create cu scaffolderul (`ci.yml`, pipeline-ul de deploy `cd.yml` și `publish.yml` pentru publicare pe npm). diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/data/system-fields.mdx index 385deb17ac..4398306856 100644 --- a/packages/twenty-docs/l/tr/developers/extend/apps/data/system-fields.mdx +++ b/packages/twenty-docs/l/tr/developers/extend/apps/data/system-fields.mdx @@ -84,6 +84,52 @@ Aynı çözümlenen id, bir `fieldMetadataUniversalIdentifier` beklendiği her y türettiği için, `getFieldUniversalIdentifier` çağrısı, bu girdiler değişse bile referansınızı doğru tutar ve türetme zaman içinde gelişirse sapmayı önler. +## System relation fields + + + `getSystemRelationFieldUniversalIdentifier` is available from `twenty-sdk` + 2.23 onward and requires a Twenty server on 2.23 or later. + + +Besides the scalar system fields above, the server also provisions four **system relation fields** on every object: `timelineActivities`, `attachments`, `noteTargets` and `taskTargets`, each pointing at the matching standard relation object. + +These fields are not resolved with `getFieldUniversalIdentifier`: their identifier is derived **name-free**, from the object hosting the field and the object the field points to. That way renaming an object never changes the identifiers of its relation fields. + +Use `getSystemRelationFieldUniversalIdentifier` to resolve them: + +```ts +import { + getSystemRelationFieldUniversalIdentifier, + STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS, +} from 'twenty-sdk/define'; + +// rocket.attachments — the relation field hosted on your custom object +const rocketAttachmentsFieldId = getSystemRelationFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + relationTargetObjectUniversalIdentifier: + STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier, +}); +``` + +* `objectUniversalIdentifier` is the object **hosting** the field. +* `relationTargetObjectUniversalIdentifier` is the object the field **points to**. + +The direction is encoded by the argument order. To resolve the reverse side (e.g. `attachment.targetRocket`, the morph field the server creates on the standard relation object), swap the two: + +```ts +// attachment.targetRocket — the reverse morph field on Attachment +const attachmentTargetRocketFieldId = + getSystemRelationFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: + STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier, + relationTargetObjectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + }); +``` + +As with scalar system fields, the resolved id works anywhere a `fieldMetadataUniversalIdentifier` is expected. + ## Standart Twenty nesneleri **Standart** bir Twenty nesnesi (Person, Company, Opportunity, …) için hiçbir şey türetmeniz gerekmez: sistem alanı tanımlayıcıları, doğrudan içe aktarabileceğiniz önceden hesaplanmış sabitlerdir. diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/getting-started/project-structure.mdx index 56e93e1218..36c56d6d5a 100644 --- a/packages/twenty-docs/l/tr/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/tr/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/operations/publishing.mdx index 4b0e1d92e1..75f24d538a 100644 --- a/packages/twenty-docs/l/tr/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/tr/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ Nihai denetim sunucudadır — hem tarball yüklemesinde hem de çalışma alan ## Otomatik CI/CD (hazır şablonlu iş akışları) -`create-twenty-app` ile oluşturulan uygulamalar, kutudan çıktığı gibi `.github/workflows/` altında iki GitHub Actions iş akışıyla gelir. Depoyu GitHub’a iter itmez çalışmaya hazırdır — CI için ek bir kurulum gerekmez ve CD yalnızca tek bir gizli anahtar gerektirir. +`create-twenty-app` ile oluşturulan uygulamalar, kutudan çıktığı gibi `.github/workflows/` altında üç GitHub Actions iş akışıyla gelir. CI herhangi bir kurulum gerektirmez, CD tek bir gizli bilgi gerektirir ve npm'e yayınlama, bir kerelik npm trusted-publisher kurulumu gerektirir. ### CI — `ci.yml` @@ -157,9 +157,22 @@ Varsayılan `TWENTY_DEPLOY_URL` olan `http://localhost:3000` bir yer tutucudur Bir çekme isteğine `deploy` etiketini ekleyin. `cd.yml` içindeki `if:` koruması, ilgili PR için işi PR'in head commit'ini kullanarak çalıştırır; böylece birleştirmeden önce hedef sunucuda değişikliği doğrulayabilirsiniz. +### Yayınla — `publish.yml` + +Uygulamanızı, bir sürüm etiketi (ör. `v1.0.0`) gönderdiğinizde veya Actions sekmesinden iş akışını manuel olarak çalıştırdığınızda, kanıt zinciri (provenance) ile npm'e yayınlar. + +**Ne yapar:** + +1. Uygulamanızı alır, Node.js’i kurar ve npm’i günceller (güvenilir yayımlama için npm 11.5.1 veya üstü gereklidir). +2. `yarn twenty app:publish` komutunu çalıştırır; bu komut uygulamayı derler ve `.twenty/output` içeriğini npm’e yayımlar. CI ortamında otomatik olarak `--provenance` ve `--access public` ekler; bu nedenle iş akışında hiçbir bayrağa gerek yoktur. + +**Tek seferlik kurulum:** + +npmjs.com’da paketinizin sayfasını açın > **Settings → Trusted Publisher** bölümüne gidin ve bu deposunu `publish.yml` iş akışıyla kaydedin ([npm trusted publishing belgelerine](https://docs.npmjs.com/trusted-publishers) bakın). Provenance ile yayımlama, paketi hangi GitHub deposunun oluşturduğunu doğrular; ayrıca Twenty pazaryerinde uygulamanızın sahipliğini bu şekilde talep edersiniz. + ### Yeniden kullanılabilir eylemleri sabitleme -Her iki iş akışı da `@main` üzerindeki yeniden kullanılabilir eylemlere başvurur; bu nedenle `twentyhq/twenty` deposundaki eylem güncellemeleri otomatik olarak alınır. Deterministik derlemeler istiyorsanız, her `uses:` satırında `@main` ifadesini bir commit SHA'sı veya sürüm etiketiyle değiştirin. +`ci.yml` ve `cd.yml` iş akışları, `@main` üzerindeki yeniden kullanılabilir eylemlere başvurur; bu nedenle `twentyhq/twenty` deposundaki eylem güncellemeleri otomatik olarak alınır. Deterministik derlemeler istiyorsanız, her `uses:` satırında `@main` ifadesini bir commit SHA'sı veya sürüm etiketiyle değiştirin. ## npm’ye yayımlama @@ -241,37 +254,12 @@ Uygulamanız `defineApplication()` içinde bir `aboutDescription` tanımlamıyor ### CI üzerinden yayımlama -Her sürümde otomatik olarak yayımlamak için bu GitHub Actions iş akışını kullanın ([OIDC](https://docs.npmjs.com/trusted-publishers) kullanır): +Yukarıda açıklanan, iskeleti oluşturulmuş `publish.yml` iş akışı sürüm etiketlerinde, provenance ile birlikte npm’e otomatik olarak yayımlar. `yarn twenty app:publish`, CI içinde çalıştığında sizin için `--provenance` ve `--access public` eklediği için, iş akışının herhangi bir npm bayrağına ihtiyacı yoktur — yalnızca tek seferlik güvenilir yayımlayıcı kurulumuna ihtiyaç duyar. -```yaml filename=".github/workflows/publish.yml" -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 -``` - -Diğer CI sistemleri (GitLab CI, CircleCI, vb.) için de aynı üç komut geçerlidir: `yarn install`, `yarn twenty dev:build` ve ardından `.twenty/output` dizininden `npm publish`. +Diğer CI sistemleri (GitLab CI, CircleCI vb.) için önce `yarn install`, ardından `yarn twenty app:publish` komutunu çalıştırın. Ortam bir OIDC jetonu oluşturabildiğinde provenance üretilir, aksi durumda ise otomatik olarak atlanır. -**npm provenance** isteğe bağlıdır ancak önerilir. `--provenance` ile yayımlamak, npm listenize bir güven rozeti ekler ve kullanıcıların paketin herkese açık bir CI ardışık düzenindeki belirli bir commit’ten oluşturulduğunu doğrulamasını sağlar. Kurulum talimatları için [npm provenance belgelerine](https://docs.npmjs.com/generating-provenance-statements) bakın. +**npm provenance**, npm listenize bir güven rozeti ekler ve kullanıcıların paketin herkese açık bir CI ardışık düzenindeki belirli bir commit’ten oluşturulduğunu doğrulamasını sağlar. Ayrıca Twenty pazaryerinde uygulamanızın sahipliğini talep etmenizi de sağlar. Ayrıntılar için [npm provenance belgelerine](https://docs.npmjs.com/generating-provenance-statements) bakın. ## Uygulamaları yükleme diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/operations/sync-and-recovery.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/operations/sync-and-recovery.mdx index a7e153e42a..e6354f1d7b 100644 --- a/packages/twenty-docs/l/tr/developers/extend/apps/operations/sync-and-recovery.mdx +++ b/packages/twenty-docs/l/tr/developers/extend/apps/operations/sync-and-recovery.mdx @@ -73,7 +73,7 @@ yarn twenty plan Building manifest... Computing metadata plan (read-only, nothing will be applied)... - # fieldMetadata "timelineActivities" will be created + # fieldMetadata "crewCapacity" will be created + ... Plan: 1 to add, 1 to change, 0 to destroy. diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/operations/testing.mdx index 1ca6d88aa8..2ac032e8bb 100644 --- a/packages/twenty-docs/l/tr/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/tr/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ Bu, uygulamanızın `tsconfig.json` dosyasına göre `tsc --noEmit` komutunu ça İskelet oluşturucu, `.github/workflows/ci.yml` konumunda kullanıma hazır bir iş akışı üretir. `main` dalına yapılan her itmede ve her çekme isteğinde, çalıştırıcı içinde geçici bir Twenty sunucusu başlatır (`twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test` eylemi aracılığıyla) ve ardından `yarn lint`, `yarn typecheck`, `yarn test:unit` ve `yarn test` komutlarını, `TWENTY_API_URL` / `TWENTY_API_KEY` bu sunucuyu işaret edecek şekilde çalıştırır. Herhangi bir gizli bilgi gerekmez ve iş akışının en üstündeki `TWENTY_VERSION` ortam değişkeni aracılığıyla sunucu sürümünü sabitleyebilirsiniz. -Her iki iskelet iş akışının (`ci.yml` ve `cd.yml` dağıtım hattı) eksiksiz adım adım anlatımı için [Yayınlama → Otomatik CI/CD](/l/tr/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) bölümüne bakın. +Üç iskelet iş akışının (npm yayınlama için `ci.yml`, `cd.yml` dağıtım hattı ve `publish.yml`) eksiksiz adım adım anlatımı için [Yayınlama → Otomatik CI/CD](/l/tr/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) bölümüne bakın. diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/data/system-fields.mdx index da4ee13cea..8f24013d65 100644 --- a/packages/twenty-docs/l/zh/developers/extend/apps/data/system-fields.mdx +++ b/packages/twenty-docs/l/zh/developers/extend/apps/data/system-fields.mdx @@ -84,6 +84,52 @@ export default defineView({ `getFieldUniversalIdentifier` 能在这些输入发生变化时仍保持引用正确，并在派生逻辑演进时避免偏差。 +## 系统关系字段 + + + `getSystemRelationFieldUniversalIdentifier` 可在 `twenty-sdk` + 2.23 及更高版本中使用，并且需要 Twenty 服务器版本为 2.23 或更高。 + + +除了上面的标量系统字段之外，服务器还会在每个对象上预置四个**系统关系字段**：`timelineActivities`、`attachments`、`noteTargets` 和 `taskTargets`，它们各自指向相应的标准关系对象。 + +这些字段不会通过 `getFieldUniversalIdentifier` 解析：它们的标识符是**与名称无关**地，从承载该字段的对象以及该字段指向的对象中派生出来的。 通过这种方式，重命名对象永远不会改变其关系字段的标识符。 + +使用 `getSystemRelationFieldUniversalIdentifier` 来解析它们： + +```ts +import { + getSystemRelationFieldUniversalIdentifier, + STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS, +} from 'twenty-sdk/define'; + +// rocket.attachments — the relation field hosted on your custom object +const rocketAttachmentsFieldId = getSystemRelationFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + relationTargetObjectUniversalIdentifier: + STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier, +}); +``` + +* `objectUniversalIdentifier` 是**承载**该字段的对象。 +* `relationTargetObjectUniversalIdentifier` 是该字段**指向**的对象。 + +方向由参数的顺序编码。 要解析反向端（例如 `attachment.targetRocket`，即服务器在标准关联对象上创建的 morph 字段），交换这两个参数： + +```ts +// attachment.targetRocket — the reverse morph field on Attachment +const attachmentTargetRocketFieldId = + getSystemRelationFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: + STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier, + relationTargetObjectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + }); +``` + +与标量系统字段一样，解析得到的 id 可在任何需要 `fieldMetadataUniversalIdentifier` 的地方使用。 + ## 标准 Twenty 对象 对于**标准** Twenty 对象（Person、Company、Opportunity 等），你不需要进行任何派生：系统字段标识符是预先计算好的常量，你可以直接导入。 diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/getting-started/project-structure.mdx index 9f1eb55b9e..3d3a067060 100644 --- a/packages/twenty-docs/l/zh/developers/extend/apps/getting-started/project-structure.mdx +++ b/packages/twenty-docs/l/zh/developers/extend/apps/getting-started/project-structure.mdx @@ -27,6 +27,7 @@ my-twenty-app/ .github/workflows/ ci.yml # Lint, typecheck, unit + integration tests cd.yml # Deploy + install on push to main + publish.yml # Publish to npm on version tags (with provenance) public/ logo.svg # Static assets vitest.config.ts # Integration test runner config diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/operations/publishing.mdx index 25e9d9b7c9..651a549741 100644 --- a/packages/twenty-docs/l/zh/developers/extend/apps/operations/publishing.mdx +++ b/packages/twenty-docs/l/zh/developers/extend/apps/operations/publishing.mdx @@ -112,7 +112,7 @@ yarn twenty app:publish --private ## 自动化 CI/CD（脚手架生成的工作流） -使用 `create-twenty-app` 生成的应用开箱即带有两个 GitHub Actions 工作流，位于 `.github/workflows/`。 当你将仓库推送到 GitHub 后即可运行——CI 无需额外设置，CD 只需要一个机密。 +使用 `create-twenty-app` 生成的应用开箱即带有三个 GitHub Actions 工作流，位于 `.github/workflows/`。 CI 可在无需任何设置的情况下运行，CD 只需要配置一个 secret，而发布到 npm 只需进行一次性的 npm trusted-publisher 设置。 ### CI — `ci.yml` @@ -157,9 +157,22 @@ yarn twenty app:publish --private 为拉取请求添加 `deploy` 标签。 在 `cd.yml` 中的 `if:` 守卫会使用该 PR 的 head 提交为其运行作业，使你能在合并前在目标服务器上验证更改。 +### 发布 — `publish.yml` + +当你推送版本标签（例如 `v1.0.0`）时，或从 Actions 选项卡中手动运行该工作流时，会将你的应用附带来源证明发布到 npm。 + +**作用:** + +1. 检出你的应用，设置 Node.js，并更新 npm（受信任发布需要 npm 11.5.1 或更高版本）。 +2. 运行 `yarn twenty app:publish`，它会构建应用并将 `.twenty/output` 发布到 npm。 在 CI 中，它会自动添加 `--provenance` 和 `--access public`，因此在工作流中不需要任何标志。 + +**一次性设置：** + +在 npmjs.com 上打开你的包 > **Settings → Trusted Publisher**，并使用 `publish.yml` 工作流为此仓库注册（参见 [npm trusted publishing 文档](https://docs.npmjs.com/trusted-publishers)）。 带有 provenance 的发布会证明是哪个 GitHub 仓库构建了该包，这也同样是你在 Twenty 市场中声明应用所有权的方式。 + ### 固定可复用的 actions -两个工作流都引用了位于 `@main` 的可复用 actions，因此会自动获取 `twentyhq/twenty` 仓库中的 action 更新。 如果你希望构建具有确定性，请在每个 `uses:` 行中将 `@main` 替换为某个提交的 SHA 或发行标签。 +`ci.yml` 和 `cd.yml` 工作流引用了 `@main` 上的可复用 actions，因此会自动获取 `twentyhq/twenty` 仓库中的 action 更新。 如果你希望构建具有确定性，请在每个 `uses:` 行中将 `@main` 替换为某个提交的 SHA 或发行标签。 ## 发布到 npm @@ -241,37 +254,12 @@ yarn twenty dev:catalog-sync ### CI 发布 -使用此 GitHub Actions 工作流，在每次发布时自动进行发布（使用 [OIDC](https://docs.npmjs.com/trusted-publishers)）： +上文所述生成的 `publish.yml` 工作流会在打上版本标签时，自动将包连同 provenance 一并发布到 npm。 由于 `yarn twenty app:publish` 在 CI 中运行时会为你添加 `--provenance` 和 `--access public`，因此该工作流不需要任何 npm 标志——只需要一次性完成受信任发布者的设置。 -```yaml filename=".github/workflows/publish.yml" -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`，然后在 `.twenty/output` 目录下执行 `npm publish`。 +对于其他 CI 系统（GitLab CI、CircleCI 等），先运行 `yarn install`，然后运行 `yarn twenty app:publish`。 当环境可以生成 OIDC 令牌时会发出 provenance，否则会自动跳过。 -**npm provenance** 可选，但建议启用。 使用 `--provenance` 发布会在你的 npm 列表中添加可信徽章，使用户可以验证该包是由公共 CI 流水线中的特定提交构建的。 有关设置说明，请参见 [npm provenance 文档](https://docs.npmjs.com/generating-provenance-statements)。 +**npm provenance** 会在你的 npm 列表中添加可信徽章，使用户可以验证该包是由公共 CI 流水线中的特定提交构建的。 它也同样是你在 Twenty 市场中声明应用所有权的方式。 有关详细信息，请参见 [npm provenance 文档](https://docs.npmjs.com/generating-provenance-statements)。 ## 安装应用 diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/operations/sync-and-recovery.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/operations/sync-and-recovery.mdx index 4565b3e793..99463dbc12 100644 --- a/packages/twenty-docs/l/zh/developers/extend/apps/operations/sync-and-recovery.mdx +++ b/packages/twenty-docs/l/zh/developers/extend/apps/operations/sync-and-recovery.mdx @@ -73,7 +73,7 @@ yarn twenty plan Building manifest... Computing metadata plan (read-only, nothing will be applied)... - # fieldMetadata "timelineActivities" will be created + # fieldMetadata "crewCapacity" will be created + ... Plan: 1 to add, 1 to change, 0 to destroy. diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/operations/testing.mdx index b165f1f685..79154ed71d 100644 --- a/packages/twenty-docs/l/zh/developers/extend/apps/operations/testing.mdx +++ b/packages/twenty-docs/l/zh/developers/extend/apps/operations/testing.mdx @@ -259,4 +259,4 @@ yarn twenty dev:typecheck 脚手架工具会在 `.github/workflows/ci.yml` 生成一个开箱即用的工作流。 在每次向 `main` 推送代码以及每个拉取请求上，它都会在 runner 中启动一个临时的 Twenty 服务器（通过 `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test` action），然后运行 `yarn lint`、`yarn typecheck`、`yarn test:unit` 和 `yarn test`，并将 `TWENTY_API_URL` / `TWENTY_API_KEY` 指向该服务器。 无需任何机密信息，你可以在工作流顶部通过 `TWENTY_VERSION` 环境变量固定服务器版本。 -完整的脚手架工作流（`ci.yml` 和 `cd.yml` 部署流水线）的演练说明，请参见 [发布 → 自动化 CI/CD](/l/zh/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows)。 +完整的三个脚手架工作流（`ci.yml`、`cd.yml` 部署流水线以及用于 npm 发布的 `publish.yml`）的详细演练说明，请参见 [发布 → 自动化 CI/CD](/l/zh/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows)。