sfdx-predeploy-hook-org-env

> sfdx predeploy hook to export target org details as environment variables

> [!IMPORTANT] > > This plugin currently only works with sfdx force:source:push and sfdx force:source:deploy. > > The sf project deploy start command does not (yet) emit the predeploy hook.

Use Case

Example: When deploying Metadata of type Portal you'll need to provide an `` which is a username in the org. The Metadata String Replacements feature already supports replacing strings with values stored in a file or in an environment variable.

sfdx-project.json

{
  ...
  "replacements": [
    {
      "filename": "force-app/main/default/portals/Customer Portal.portal-meta.xml",
      "stringToReplace": "admin@example.com",
      "replaceWithEnv": "ORG_USERNAME"
    }
  ]
}

Let's assume that for a Scratch Org we create, we simply want to make the default scratch org user the admin of the portal.

So in this example, we'll set the environment variable ORG_USERNAME, but first we need to get the default scratch org username from the org:

export ORG_USERNAME="$(node -pe 'JSON.parse(fs.readFileSync(0, "utf8")).result.username' < <(sfdx force:org:display -u my-target-org --json))"
sfdx force source deploy -p "force-app/main/default/portals/Customer Portal.portal-meta.xml" -u my-target-org

Although this works just fine, we need to remember to set this environment variable before deploying or pushing.

> Note > > For common things like username, email address, org id, it would be handy to have these environment variables with target specific values built-in. > > And this is exactly what this sfdx plugin does!

Installation

sfdx plugins install sfdx-predeploy-hook-org-env

Usage

Once you've installed this sfdx plugin, you can immediately use the following environment variables mentioned for the Metadata String Replacements:

> Note > > Do you have ideas for other target specific values which could be useful? > > Please get in touch by creating an issue.

Example:

Make sure your sfdx-project.json contains some replacements using one of the environment variables listed above.

sfdx-project.json:

{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true
    }
  ],
  "replacements": [
    {
      "filename": "force-app/main/default/portals/Customer Portal.portal-meta.xml",
      "stringToReplace": "admin@example.com",
      "replaceWithEnv": "SFDX_TARGET_ORG_USERNAME"
    },
    {
      "filename": "force-app/main/default/portals/Customer Portal.portal-meta.xml",
      "stringToReplace": "admin@gmail.com",
      "replaceWithEnv": "SFDX_TARGET_ORG_USER_EMAIL"
    }
  ],
  "sourceApiVersion": "57.0"
}

Now you can run sfdx force source push or sfdx force source deploy and the Metadata replacement will automatically use the dynamically generated environment variables for the given target org:

sfdx force source deploy -p "Portal:Customer Portal" -u my-target-org1
sfdx force source deploy -p "Portal:Customer Portal" -u my-target-org2
sfdx force source deploy -p "Portal:Customer Portal" -u my-target-org3

Debugging

To preview the environment variables, set the environment variable DEBUG to *:sfdx-predeploy-hook-org-env:* and perform a validation deployment to the target org.

Example

MacOS/Linux:

$ DEBUG="*:sfdx-predeploy-hook-org-env:*" sfdx force source deploy --checkonly -u mytargetorg -p force-app

Windows PowerShell:

$env:DEBUG="*:sfdx-predeploy-hook-org-env:*"
sfdx force source deploy --checkonly -u mytargetorg -p force-app

This will output something like:

...
sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy Setting environment variables for target org +2s
sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_ID="00D7g0000006RKmEAM"
sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USERNAME="john.doe@example.com"
sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_ID="0058F000002RfcKQAS"
sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_EMAIL="john.doe@gmail.com"
sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_FIRSTNAME="John"
sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_LASTNAME="Doe"
sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_DISPLAYNAME="John Doe" +0ms
...