Skip to content

The open alternative to Salesforce, designed for AI.

Reserve the TWENTY_ prefix for app variable names (#29210)

Paul Rastoin0c5752d843df
diff --git a/packages/twenty-agent-skills/references/concepts/how-apps-work.md b/packages/twenty-agent-skills/references/concepts/how-apps-work.md
index df479fafdeb..c3fd5501607 100644
--- a/packages/twenty-agent-skills/references/concepts/how-apps-work.md
+++ b/packages/twenty-agent-skills/references/concepts/how-apps-work.md
@@ -110,4 +110,4 @@ my-app/
- **Remotes**: Named connections to Twenty instances. Stored in `~/.twenty/config.json`. Switch with `twenty remote use <name>`.
- **Sync**: `twenty app apply` builds, deploys, and installs the app on the active remote in one step. This is the standard way to get code changes onto a Twenty instance.
- **Publish**: `twenty app publish` packages the app for distribution to other instances or the marketplace. Requires a strictly higher semver version than the previously published version.
-- **Reserved variable names**: `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID` are set by Twenty for every logic function run. A manifest that declares one of them as an application or server variable is rejected on sync and publish.
+- **Reserved variable names**: `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID` are set by Twenty for every logic function run, and every other name starting with `TWENTY_` is kept for variables Twenty adds later. A manifest that declares a reserved name as an application or server variable is rejected on sync and publish.
diff --git a/packages/twenty-agent-skills/references/develop-app/logic.md b/packages/twenty-agent-skills/references/develop-app/logic.md
index b291961349f..694078fd228 100644
--- a/packages/twenty-agent-skills/references/develop-app/logic.md
+++ b/packages/twenty-agent-skills/references/develop-app/logic.md
@@ -22,7 +22,7 @@ Other rules:
- Prefer idempotent behavior for jobs and repeated invocations.
- Read secrets through the application-config helper, not raw `process.env`.
- An application variable declared with `scope: 'USER'` is in `process.env` with the value of the member who triggered the run, or its default until they set their own; a run nobody triggered (cron, install hooks) gets no user variables. That member is not always the one the run is about: a database event runs as whoever edited the record. For example, with a user `SLACK_TOKEN`, a function on opportunity update posts with the editor's token, not the opportunity owner's. When the run is about someone else or every member, read the values with `myUserApplicationVariables` through `new MetadataApiClient({ runAs: 'application' })`.
-- Twenty injects `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID` into every run. Never declare an application or server variable with one of these names: the manifest is rejected on sync and publish.
+- Twenty injects `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID` into every run. Never declare an application or server variable with one of these names, or any other name starting with `TWENTY_`: the manifest is rejected on sync and publish.
- Do not hide customer-impacting side effects behind UI-only actions.
Soft cap: a `*.logic-function.ts` or `*.post-install.ts` file over 200 lines is a refactor signal.
diff --git a/packages/twenty-docs/developers/extend/apps/config/application.mdx b/packages/twenty-docs/developers/extend/apps/config/application.mdx
index c71513fd1e5..a63fda3d3cf 100644
--- a/packages/twenty-docs/developers/extend/apps/config/application.mdx
+++ b/packages/twenty-docs/developers/extend/apps/config/application.mdx
@@ -54,7 +54,7 @@ Notes:
- An app can report its own configuration state with [`defineHealthCheck()`](/developers/extend/apps/logic/logic-functions#health-check), for what only the app can know — a key that is present but revoked, a third-party account on the wrong plan. `isRequired` covers what Twenty can see by itself; the health check covers the rest.
- Both kinds of variable accept `isRequired: true`. A required variable the workspace has not filled in yet leaves the app unconfigured: its settings page shows a banner naming the missing variables, with a button that jumps to the tab where they are set. Mark as required only what the app genuinely cannot run without — an optional variable with a sensible default should stay optional.
- Both kinds of variable accept `isDeprecated: true`. Use it to retire a variable instead of deleting it: keeping the key declared preserves the stored value (deleting it destroys the value the operator entered), and the variable is still injected, so your code can fall back to it — `process.env.NEW_API_KEY ?? process.env.API_KEY`. A deprecated variable disappears from the app's settings once it has no value, and never counts toward the app's configuration check, so `isDeprecated` beats `isRequired`.
-- Twenty sets these names for every logic function run, so they are reserved: `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID`. A manifest that declares one of them as an application or server variable is rejected when the app is synced or published.
+- Twenty sets these names for every logic function run, so they are reserved: `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID`. Every other name starting with `TWENTY_` is reserved too, for variables Twenty adds later. A manifest that declares a reserved name as an application or server variable is rejected when the app is synced or published.
- To add your own entries to the app's settings menu (in place of the generated **Variables** page), declare a front component and point a [`defineSettingsMenuItem()`](/developers/extend/apps/layout/front-components#settings-menu-items) at it, in its own file. Declare as many as you need and order them with `position`; `scope` puts an item under the workspace settings or under each member's own settings. The system-managed **General** item (auto-upgrade, App URL, connections) always comes first, and App URL only shows when the app has HTTP-triggered functions.
## Requested media capabilities
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-registration-variable/application-registration-variable.service.ts b/packages/twenty-server/src/engine/core-modules/application/application-registration-variable/application-registration-variable.service.ts
index 48000a21fab..b4604c5ea4f 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-registration-variable/application-registration-variable.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-registration-variable/application-registration-variable.service.ts
@@ -19,7 +19,7 @@ import {
import { type UpdateApplicationRegistrationVariableInput } from 'src/engine/core-modules/application/application-registration-variable/dtos/update-application-registration-variable.input';
import { type FlatApplication } from 'src/engine/core-modules/application/types/flat-application.type';
import { canCallerReachApplicationRegistrationOrThrow } from 'src/engine/core-modules/application/utils/can-caller-reach-application-registration-or-throw.util';
-import { findEngineInjectedEnvVariableNames } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util';
+import { isReservedEnvVariableName } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util';
import { type PlaintextString } from 'src/engine/core-modules/secret-encryption/branded-strings/plaintext-string.type';
import { SecretEncryptionService } from 'src/engine/core-modules/secret-encryption/secret-encryption.service';
import { ApplicationRegistrationVariableDTO } from 'src/engine/core-modules/application/application-registration-variable/dtos/application-registration-variable.dto';
@@ -113,7 +113,7 @@ export class ApplicationRegistrationVariableService {
const declaredKeys = Object.keys(serverVariables);
- const reservedKeys = findEngineInjectedEnvVariableNames(declaredKeys);
+ const reservedKeys = declaredKeys.filter(isReservedEnvVariableName);
if (reservedKeys.length > 0) {
throw new ApplicationRegistrationException(
diff --git a/packages/twenty-server/src/engine/core-modules/application/utils/__tests__/find-reserved-variable-names-in-application-manifest.util.spec.ts b/packages/twenty-server/src/engine/core-modules/application/utils/__tests__/find-reserved-variable-names-in-application-manifest.util.spec.ts
index 924e437e0b0..ec22c603064 100644
--- a/packages/twenty-server/src/engine/core-modules/application/utils/__tests__/find-reserved-variable-names-in-application-manifest.util.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/utils/__tests__/find-reserved-variable-names-in-application-manifest.util.spec.ts
@@ -49,4 +49,18 @@ describe('findReservedVariableNamesInApplicationManifest', () => {
}),
).toEqual(['TWENTY_API_KEY']);
});
+
+ it('should return names starting with TWENTY_ that Twenty does not inject yet', () => {
+ expect(
+ findReservedVariableNamesInApplicationManifest({
+ serverVariables: { TWENTY_SERVER_SETTING: { isSecret: true } },
+ applicationVariables: {
+ TWENTY_WORKSPACE_SETTING: {
+ universalIdentifier: 'application-variable-id',
+ isSecret: false,
+ },
+ },
+ }),
+ ).toEqual(['TWENTY_SERVER_SETTING', 'TWENTY_WORKSPACE_SETTING']);
+ });
});
diff --git a/packages/twenty-server/src/engine/core-modules/application/utils/find-reserved-variable-names-in-application-manifest.util.ts b/packages/twenty-server/src/engine/core-modules/application/utils/find-reserved-variable-names-in-application-manifest.util.ts
index 41dc063ffb8..c833d712a7c 100644
--- a/packages/twenty-server/src/engine/core-modules/application/utils/find-reserved-variable-names-in-application-manifest.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/utils/find-reserved-variable-names-in-application-manifest.util.ts
@@ -1,6 +1,6 @@
import { type ApplicationManifest } from 'twenty-shared/application';
-import { findEngineInjectedEnvVariableNames } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util';
+import { isReservedEnvVariableName } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util';
export const findReservedVariableNamesInApplicationManifest = ({
serverVariables,
@@ -10,9 +10,9 @@ export const findReservedVariableNamesInApplicationManifest = ({
'serverVariables' | 'applicationVariables'
>): string[] => [
...new Set(
- findEngineInjectedEnvVariableNames([
+ [
...Object.keys(serverVariables ?? {}),
...Object.keys(applicationVariables ?? {}),
- ]),
+ ].filter(isReservedEnvVariableName),
),
];
diff --git a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/constants/reserved-env-variable-name-prefix.constant.ts b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/constants/reserved-env-variable-name-prefix.constant.ts
new file mode 100644
index 00000000000..d4c57af7ffc
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/constants/reserved-env-variable-name-prefix.constant.ts
@@ -0,0 +1 @@
+export const RESERVED_ENV_VARIABLE_NAME_PREFIX = 'TWENTY_';
diff --git a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/__tests__/is-reserved-env-variable-name.util.spec.ts b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/__tests__/is-reserved-env-variable-name.util.spec.ts
new file mode 100644
index 00000000000..f813113df4f
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/__tests__/is-reserved-env-variable-name.util.spec.ts
@@ -0,0 +1,19 @@
+import { isReservedEnvVariableName } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util';
+
+describe('isReservedEnvVariableName', () => {
+ it.each([
+ 'TWENTY_API_URL',
+ 'APPLICATION_ID',
+ 'TWENTY_FUTURE_VARIABLE',
+ 'TWENTY_',
+ ])('should reserve %s', (name) => {
+ expect(isReservedEnvVariableName(name)).toBe(true);
+ });
+
+ it.each(['APP_API_KEY', 'twenty_api_url', 'MY_TWENTY_VARIABLE', 'TWENTY'])(
+ 'should not reserve %s',
+ (name) => {
+ expect(isReservedEnvVariableName(name)).toBe(false);
+ },
+ );
+});
diff --git a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util.ts b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util.ts
deleted file mode 100644
index 8f09c3fefcf..00000000000
--- a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-import { ENGINE_INJECTED_ENV_VARIABLE_NAMES } from 'src/engine/core-modules/logic-function/logic-function-executor/constants/engine-injected-env-variable-names.constant';
-
-export const findEngineInjectedEnvVariableNames = (keys: string[]): string[] =>
- keys.filter((key) => ENGINE_INJECTED_ENV_VARIABLE_NAMES.has(key));
diff --git a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util.ts b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util.ts
new file mode 100644
index 00000000000..ffe6614cec2
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util.ts
@@ -0,0 +1,6 @@
+import { ENGINE_INJECTED_ENV_VARIABLE_NAMES } from 'src/engine/core-modules/logic-function/logic-function-executor/constants/engine-injected-env-variable-names.constant';
+import { RESERVED_ENV_VARIABLE_NAME_PREFIX } from 'src/engine/core-modules/logic-function/logic-function-executor/constants/reserved-env-variable-name-prefix.constant';
+
+export const isReservedEnvVariableName = (name: string): boolean =>
+ ENGINE_INJECTED_ENV_VARIABLE_NAMES.has(name) ||
+ name.startsWith(RESERVED_ENV_VARIABLE_NAME_PREFIX);
diff --git a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-application-variable-validator.service.ts b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-application-variable-validator.service.ts
index 5e657b96006..ff192bd2b35 100644
--- a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-application-variable-validator.service.ts
+++ b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-application-variable-validator.service.ts
@@ -6,7 +6,7 @@ import { ALL_METADATA_NAME } from 'twenty-shared/metadata';
import { isDefined } from 'twenty-shared/utils';
import { ApplicationVariableEntityExceptionCode } from 'src/engine/core-modules/application/application-variable/application-variable.exception';
-import { ENGINE_INJECTED_ENV_VARIABLE_NAMES } from 'src/engine/core-modules/logic-function/logic-function-executor/constants/engine-injected-env-variable-names.constant';
+import { isReservedEnvVariableName } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util';
import { findFlatEntityByUniversalIdentifier } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-universal-identifier.util';
import { type FailedFlatEntityValidation } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/types/failed-flat-entity-validation.type';
import { getEmptyFlatEntityValidationError } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/utils/get-flat-entity-validation-error.util';
@@ -42,7 +42,7 @@ export class FlatApplicationVariableValidatorService {
});
}
- if (ENGINE_INJECTED_ENV_VARIABLE_NAMES.has(flatApplicationVariable.key)) {
+ if (isReservedEnvVariableName(flatApplicationVariable.key)) {
const key = flatApplicationVariable.key;
validationResult.errors.push({
@@ -145,10 +145,7 @@ export class FlatApplicationVariableValidatorService {
const keyUpdate = flatEntityUpdate.key;
- if (
- isDefined(keyUpdate) &&
- ENGINE_INJECTED_ENV_VARIABLE_NAMES.has(keyUpdate)
- ) {
+ if (isDefined(keyUpdate) && isReservedEnvVariableName(keyUpdate)) {
validationResult.errors.push({
code: ApplicationVariableEntityExceptionCode.INVALID_APPLICATION_VARIABLE_INPUT,
message: t`Application variable key ${keyUpdate} is reserved`,
diff --git a/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-sync-application-reserved-variable-name.integration-spec.ts.snap b/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-sync-application-reserved-variable-name.integration-spec.ts.snap
index e19c4b85e24..f5b49c6ba26 100644
--- a/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-sync-application-reserved-variable-name.integration-spec.ts.snap
+++ b/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-sync-application-reserved-variable-name.integration-spec.ts.snap
@@ -72,6 +72,18 @@ exports[`Sync application should fail on reserved variable names should refuse a
}
`;
+exports[`Sync application should fail on reserved variable names should refuse a manifest declaring a server variable named TWENTY_FUTURE_VARIABLE 1`] = `
+{
+ "extensions": {
+ "code": "BAD_USER_INPUT",
+ "subCode": "INVALID_INPUT",
+ "userFriendlyMessage": "Invalid input provided.",
+ },
+ "message": "Variable names are reserved: TWENTY_FUTURE_VARIABLE",
+ "name": "UserInputError",
+}
+`;
+
exports[`Sync application should fail on reserved variable names should refuse a manifest declaring an application variable named APPLICATION_ID 1`] = `
{
"extensions": {
@@ -143,3 +155,15 @@ exports[`Sync application should fail on reserved variable names should refuse a
"name": "UserInputError",
}
`;
+
+exports[`Sync application should fail on reserved variable names should refuse a manifest declaring an application variable named TWENTY_FUTURE_VARIABLE 1`] = `
+{
+ "extensions": {
+ "code": "BAD_USER_INPUT",
+ "subCode": "INVALID_INPUT",
+ "userFriendlyMessage": "Invalid input provided.",
+ },
+ "message": "Variable names are reserved: TWENTY_FUTURE_VARIABLE",
+ "name": "UserInputError",
+}
+`;
diff --git a/packages/twenty-server/test/integration/metadata/suites/application/failing-sync-application-reserved-variable-name.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/application/failing-sync-application-reserved-variable-name.integration-spec.ts
index 6c250553427..99b5984de53 100644
--- a/packages/twenty-server/test/integration/metadata/suites/application/failing-sync-application-reserved-variable-name.integration-spec.ts
+++ b/packages/twenty-server/test/integration/metadata/suites/application/failing-sync-application-reserved-variable-name.integration-spec.ts
@@ -32,7 +32,7 @@ const BASELINE_APPLICATION_VARIABLES: ApplicationVariables = {
},
};
-// The logic function executor injects these into every run
+// Engine-injected names, plus an unused one under the reserved TWENTY_ prefix
const RESERVED_NAMES = [
'TWENTY_API_URL',
'TWENTY_APP_ACCESS_TOKEN',
@@ -40,6 +40,7 @@ const RESERVED_NAMES = [
'TWENTY_API_KEY',
'TWENTY_FUNCTIONS_URL',
'APPLICATION_ID',
+ 'TWENTY_FUTURE_VARIABLE',
];
type TestContext = {