Actions cannot be updated due to keyword preservation

[alex-suciu]

Checklist

• I have looked into the README and have not found a suitable solution or answer.
• I have looked into the documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have upgraded to the latest version of this tool and the issue still persists.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Description

I use the latest version 8.29.0 of auth0-deploy-cli and run into issues while exporting resources using "AUTH0_PRESERVE_KEYWORDS": true. I tested it with version 8.26.0 as well but same issue exists. Here's what happens:

I got an action that should only if the login has been initiated from specific applications. Each application has a different client ID depending on the Auth0 environment (we use development, staging and production). In order to achieve this, we use keywords for the client ID of the applications in our Auth0 deploy configuration files:

{
  "AUTH0_PRESERVE_KEYWORDS": true,
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "FIRST_APPLICATION_ID": "robkqXymKTioghjisJNyJofUAWgJQksnf",
    "SECOND_APPLICATION_ID": "tupWHHtoVBTPpQgfbBFLxUJbaKeihmZNR",
    ...
  },
  ...
}

Within the Auth0 action, we then verify if the login event has been initiated by one of those two applications before executing the remaining code:

/**
 * Handler that will be called during the execution of a PostLogin flow.
 *
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  const ALLOWED_APPLICATION_IDS = [
    '##FIRST_APPLICATION_ID##',
    '##SECOND_APPLICATION_ID##'
  ];
  if (!ALLOWED_APPLICATION_IDS.includes(event.client.client_id)) {
    return;
  }
  ...
}

Everything worked fine until we tried to export the resources from Auth0 today after changing the action (in this example, the scope write:users has been added). The command didn't replace the action that has been modified in Auth0. Instead, it printed this warning:

WARNING! The remote value with address of actions.[name=...].code has value of "/**
 * Handler that will be called during the execution of a PostLogin flow.
 *
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  const ALLOWED_APPLICATION_IDS = [
    'robkqXymKTioghjisJNyJofUAWgJQksnf',
    'tupWHHtoVBTPpQgfbBFLxUJbaKeihmZNR'
  ];
  if (!ALLOWED_APPLICATION_IDS.includes(event.client.client_id)) {
    return;
  }
  var scopes = ['openid', 'profile'];
  scopes.push('read:users', 'write:users');
  ...
}" but will be preserved with "/**
 * Handler that will be called during the execution of a PostLogin flow.
 *
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  const ALLOWED_APPLICATION_IDS = [
    'robkqXymKTioghjisJNyJofUAWgJQksnf',
    'tupWHHtoVBTPpQgfbBFLxUJbaKeihmZNR'
  ];
  if (!ALLOWED_APPLICATION_IDS.includes(event.client.client_id)) {
    return;
  }
  scopes.push('read:users');
  ...
}" due to keyword preservation.

I'd appreciate if somebody could look into this issue because in this state the Auth0 deploy tool is unusable.

Expectation

1. I'd have expected that keyword replacement is limited to the string defined by the keyword. But that's clearly not the case because the whole action code is being rejected not just the string matching the keyword.
2. My change was completely unrelated to any of my keywords (just added an additional scope). If I compare the code of the two versions from the warning message, I can see that the actions are identical except for the additional scope. This means that the keywords are matching. In this case, I'd have expected that the local action code gets replaced with the one from Auth0 without any issues.

Reproduction

1. Use "AUTH0_PRESERVE_KEYWORDS": true in the configuration of the Auth0 deploy tool and two keywords:

{
  "AUTH0_PRESERVE_KEYWORDS": true,
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "FIRST_APPLICATION_ID": "robkqXymKTioghjisJNyJofUAWgJQksnf",
    "SECOND_APPLICATION_ID": "tupWHHtoVBTPpQgfbBFLxUJbaKeihmZNR",
  }
}

2. Create an action with following code:

/**
 * Handler that will be called during the execution of a PostLogin flow.
 *
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  const ALLOWED_APPLICATION_IDS = [
    '##FIRST_APPLICATION_ID##',
    '##SECOND_APPLICATION_ID##'
  ];
  if (!ALLOWED_APPLICATION_IDS.includes(event.client.client_id)) {
    return;
  }
  var scopes = ['openid', 'profile'];
  scopes.push('read:users');
}

3. In Auth0, modify the action and add a scope:

/**
 * Handler that will be called during the execution of a PostLogin flow.
 *
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  const ALLOWED_APPLICATION_IDS = [
    '##FIRST_APPLICATION_ID##',
    '##SECOND_APPLICATION_ID##'
  ];
  if (!ALLOWED_APPLICATION_IDS.includes(event.client.client_id)) {
    return;
  }
  var scopes = ['openid', 'profile'];
  scopes.push('read:users', 'write:users');
}

4. Execute a0deploy export --config_file config/config.development.json --output_folder src --format directory

Deploy CLI version

8.29.0

Node version

v22.22.0

[kushalshit27]

Hi, @alex-suciu,

Generally, the Deploy CLI works best when operating in a uni-directional workflow from your lower-level environments (ex: dev, test) up to your production environments. more

The keyword preservation functionality will attempt to preserve as many keywords while also maintaining the accuracy of your resource configuration files. And it the majority of cases, it will work without any intervention by the user. However, some key limitations exist:

• In the case of a keyword-replaced configuration field with differing values between local and remote, the local configuration value will always be favored. This will cause any out-of-band changes on remote to be wiped away if a keyword replace marker exists anywhere in that field's value in the resource definition file; there is no "intelligent" reconciliation.
• Arrays without a specific identifiers are not eligible for preservation. Ex: [ "http://site.com/logout", "localhost:3000/logout", "##LOGOUT_URL##" ]. This is because the ordering of these values are non-deterministic. Alternatively, to preserve these values, it is recommended to leverage the @@ARRAY_REPLACE@@ keyword replace syntax with the entire value.

actions code.js is considered a single block of value; the deploy cli doesn't work like git (bi-directional). The deploy cli works best with a uni-directional flow.

So, if the changes are made directly in Auth0 for the action code, changes must be merged manually to avoid a keyword-preservation mismatch.

[alex-suciu]

Hi, @alex-suciu,

Generally, the Deploy CLI works best when operating in a uni-directional workflow from your lower-level environments (ex: dev, test) up to your production environments. more

The keyword preservation functionality will attempt to preserve as many keywords while also maintaining the accuracy of your resource configuration files. And it the majority of cases, it will work without any intervention by the user. However, some key limitations exist:

• In the case of a keyword-replaced configuration field with differing values between local and remote, the local configuration value will always be favored. This will cause any out-of-band changes on remote to be wiped away if a keyword replace marker exists anywhere in that field's value in the resource definition file; there is no "intelligent" reconciliation.
• Arrays without a specific identifiers are not eligible for preservation. Ex: [ "http://site.com/logout", "localhost:3000/logout", "##LOGOUT_URL##" ]. This is because the ordering of these values are non-deterministic. Alternatively, to preserve these values, it is recommended to leverage the @@ARRAY_REPLACE@@ keyword replace syntax with the entire value.

actions code.js is considered a single block of value; the deploy cli doesn't work like git (bi-directional). The deploy cli works best with a uni-directional flow.

So, if the changes are made directly in Auth0 for the action code, changes must be merged manually to avoid a keyword-preservation mismatch.

Hi @kushalshit27

Thanks a lot for your reply and for looking into it, we appreciate it.

I understand your point although it's not what I expected.

Our current desired process for modifying Auth0 is:

1. Manually edit Auth0 development tenant (because sometimes it's difficult to find the corresponding setting in the code base)
2. Test changes
3. Export changes from Auth0 development tenant to update code base
4. Verify that diff corresponds to expected change set
5. Deploy changes to Auth0 staging tenant
6. Test staging tenant
7. Deploy changes to Auth0 production tenant

By following this process I experienced some changes due to new features or deprecations from Auth0 which I was only aware of because I exported them from Auth0 in step 3. If I only use a uni-directional flow then I'd need to make sure to be aware of each of those changes and then to manually add them to my code base. IMO it's especially risky when using the option AUTH0_ALLOW_DELETE because unknown resources or configurations would be removed.

My main concern is that the uni-directional process can only work if changes are exclusively performed by the deploy tool. But that's not the case so we need a possibility to first verify the current state in Auth0 before deploying our changes.

[kushalshit27]

I would request to go through https://github.com/auth0/auth0-deploy-cli/blob/master/docs/multi-environment-workflow.md
After internal discussion, we believe this can be considered as a feature request for future consideration.

Here is a workaround: one export once to see the real remote state, export again to keep local keywords, then use Git diff/merge to safely copy the Action code changes into the preserved file. That helps avoid manual merge mistakes.

Hope it helps.

[kushalshit27]

To ensure this request gets the visibility it deserves and to encourage broader collaboration, we are moving this to a GitHub Discussion.
This will allow us to gather more input from the community and better prioritize this feature within our roadmap. We appreciate your input and look forward to seeing the conversation grow there!

We've already added your suggestion to our backlog for future consideration.