Continuous Delivery Engine, based on SFDX CLI
CI Engine to automate the Salesforce CRM development process. The Engine communicates with Salesforce through the SFDX CLI.
Installation
You can install this using npm installer.
Requirements
To get started, you'll need to install node v16 (LTS) or greater. While this can be done using an installer from nodejs.com or via an OS-specific package manager.
Install package
> npm install --global @ciguru/sfdx-ci-engineUsage
Tools based on adapter
- SFDX Plugin - Provides the ability to use the CI Engine as part of the SFDX CLI.
Import in your own code
// Import CI Engine
import CiEngine from '@ctsoftware/sfdx-ci-engine';
// Set up the CI Engine by specifying the path to the configuration file
const ci = new CiEngine(configurationfile);
// Tune the behaviur of your configuration by providing input
ci.setGlobalInputs({ foo: 'abra', bar: 123 });
// Performing CI steps(actions) according to configuration
await ci.run();
// Get step results(outputs)
const result = ci.getOutputs();CI Configuration
Supported configuration file formats
You can use YAML (.yaml or .yml) or JSON (.json) files to set up the
configuration. You can import JSON Schema in
your IDE to simplify configuration process (guidelines for
WebStorm and
VS Code).
Configuration
Top-level attributes
| Attribute | Type | Required | Description |
| version | enum | true | CI Configuration version. Values: - 1.x |
| inputs | Input[] | false | User input data. Supported by CLI tools |
| vars | Variable[] | false | Configuration variables |
| steps | Step[] | true | Job steps |
Input attributes
| Attribute | Type | Required | $ref syntax | Description |
| id | string | true | - | Input id. Must be unique for configuration. Pattern: [A-Za-z][0-9A-Za-z_-]{0,78}[0-9A-Za-z]? |
| description | string | false | - | Input variable description. Used bu CLI tool as input question. |
| required | boolean | false | - | Mark input as required (default: false) |
| default | string | number | boolean | null | false | yes, only $env | Default value of input variable (default: null). |
Variable attributes
| Attribute | Type | Required | $ref syntax | Description |
| id | string | true | - | Variable id. Must be unique for configuration. Pattern: [A-Za-z][0-9A-Za-z_-]{0,78}[0-9A-Za-z]? |
| description | string | false | - | Variable description |
| value | string | number | boolean | null | true | yes, only $env and $input | Value of variable |
Step attributes
Attributes for all steps
| Attribute | Type | Required | $ref syntax | Description |
| type | enum | true | - | Type of step. Values: - ci.changeSet.create - Create change sets to deploy and revert Pull Requests - ci.data.transfer - Transfer data form one Salesforce org to Another using bulk data API - sfdx.auth.accessToken - Authorize an org using an access token - sfdx.auth.list - List auth connection information - sfdx.auth.logout - Log out from authorized orgs - sfdx.auth.sfdxUrl - Authorize an org using sfdxurl - sfdx.force.apex.execute - Executes anonymous Apex code - sfdx.force.apex.test.run - Invoke Apex tests - sfdx.force.data.bulk.delete - Bulk delete records from a CSV file - sfdx.force.data.bulk.upsert - Bulk upsert records from a CSV file - sfdx.force.data.tree.import - Import data into an org - sfdx.force.data.soql.query.csv - Import data into an org - sfdx.force.mdApi.deploy - Deploy metadata to an org using Metadata API - sfdx.force.mdApi.retrieve - Retrieve metadata from an org using Metadata API - sfdx.force.org.create.scratch - Create a scratch org - sfdx.force.org.delete - Mark a scratch or sandbox org for deletion - sfdx.force.org.display - Get the description for the current or target org - sfdx.force.package.install - Install a package in the target org - sfdx.force.source.push - Push source to a scratch org from the project |
| id | string | true | - | Step ID to be referenced in output. Must be unique for configuration. Pattern: [A-Za-z][0-9A-Za-z-_]{0,39} |
| description | string | false | - | Step description. |
| continueOnError | string | false | - | Continue configuration execution on step error (default: false) |
Additional attributes for ci.changeSet.create step (since v1.1.0)
Create change sets to deploy and revert Pull Requests
| Attribute | Type | Required | $ref syntax | Description |
| headSha | string | true | yes | The hash number of the commit that contains the changes to merge. Pattern: [a-f0-9]{5,40} |
| baseSha | string | true | yes | The hash number of the target commit into which the changes will be merged. Pattern: [a-f0-9]{5,40} |
| destructiveChangeSetMode | enum | false | - | Specify whether removed components should be deleted before or after component additions. Enum values: - pre - post - default value |
| changeSetDir | string | true | yes | Output directory to store the Metadata API–formatted files for deploy |
| createRevertChangeSet | boolean | false | - | Specify whether to create a Change Set to revert changes (default: false) |
| revertDestructiveChangeSetMode | enum | false | - | Specify whether removed components should be deleted before or after component additions. Enum values: - pre - post - default value |
| revertChangeSetDir | string | true, if createRevertChangeSet=true | yes | Output directory to store the Metadata API–formatted files for revert changes |
Additional attributes for ci.data.transfer step (since v1.2.0)
Create change sets to deploy and revert Pull Requests
| Attribute | Type | Required | $ref syntax | Description |
| sourceOrgAlias | string | true | yes | Alias of the Salesforce org from which data will be loaded for transfer. Pattern: [0-9A-Za-z_-]{1,40} |
| targetOrgAlias | string | true | yes | Salesforce org alias for data transfer. Pattern: [0-9A-Za-z_-]{1,40} |
| sObjectType | string | sObjectItem | true | - | Salesforce object. Specify 'source' and 'target' object if they are different. Pattern: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z] |
| sObjectFields | string | sObjectItem | true | - | Array of Salesforce object fields. Specify 'source' and 'target' fields if they are different. Pattern: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z](\.[A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z]){0,4} |
| queryFilter | string | false | - | Query filter for Source org data. Allowed WHERE and LIMIT |
| externalId | string | true | - | Column name of the external ID in Target Salesforce Org. Pattern: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z] |
| allowNoMoreFailedBatches | number | false | - | Mark a step as successful if the number of Failed Batches is less than the specified number (default: 0). |
| allowNoMoreFailedRecords | number | false | - | Mark a step as successful if the number of Failed Records is less than the specified number (default: 0). |
Additional attributes for sObjectItem step (since v1.2.0)
| Attribute | Type | Required | $ref syntax | Description |
| source | string | true | yes | Source Salesforce org object|field. Pattern for fields: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z] Pattern for fields: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z](\.[A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z]){0,4} |
| target | string | true | yes | Target Salesforce org object|field. Pattern for fields: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z] Pattern for fields: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z](\.[A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z]){0,4} |
Additional attributes for sfdx.auth.accessToken step
Authorize an org using access token
| Attribute | Type | Required | $ref syntax | Description |
| alias | string | true | yes | Alias for the authenticated org. Pattern: [0-9A-Za-z_-]{1,40} |
| instanceUrl | string | true | yes | Login URL of the instance the org lives on. Pattern: https://[a-zA-Z0-9][a-zA-Z0-9.-]{1,255}\.salesforce\.com/? |
| accessToken | string | true | yes | Active access token. Pattern: 00D[0-9A-Za-z]{12}![0-9A-Za-z_.]{96} |
Additional attributes for sfdx.auth.list step
List auth connection information
| Attribute | Type | Required | $ref syntax | Description |
Additional attributes for sfdx.auth.logout step
Log out from authorized orgs
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
Additional attributes for sfdx.auth.sfdxUrl step
Authorize an org using sfdxurl
| Attribute | Type | Required | $ref syntax | Description |
| alias | string | true | yes | Alias for the authenticated org. Pattern: [0-9A-Za-z_-]{1,40} |
| sfdxUrlFile | string | true | yes | Path to a file containing the sfdx url |
Additional attributes for sfdx.force.apex.execute step
Executes anonymous Apex code
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| apexCodeFile | string | true | yes | Path to a local file that contains Apex code |
Additional attributes for sfdx.force.apex.test.run step
Invoke Apex tests
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| testLevel | enum | true | - | Specifies which tests to run, using one of these TestLevel enum values: - RunSpecifiedTests—Only the tests that you specify are run (not supported yet) - RunLocalTests—All tests in your org are run, except the ones that originate from installed managed packages - RunAllTestsInOrg—All tests are in your org and in installed managed packages are run |
| outputDir | string | true | yes | Directory to store test run files |
Additional attributes for sfdx.force.data.bulk.delete step
Bulk delete records from a CSV file
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| csvFile | string | true | yes | Path to the CSV file that defines the records to delete |
| sObjectType | string | true | - | SObject type of the records you want to delete. Pattern: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z] |
| allowNoMoreFailedBatches | number | false | - | Mark a step as successful if the number of Failed Batches is less than the specified number (default: 0). |
| allowNoMoreFailedRecords | number | false | - | Mark a step as successful if the number of Failed Records is less than the specified number (default: 0). |
Additional attributes for sfdx.force.data.bulk.upsert step
Bulk upsert records from a CSV file
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| csvFile | string | true | yes | Path to the CSV file that defines the records to upsert |
| externalId | string | true | - | Column name of the external ID. Pattern: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z] |
| sObjectType | string | true | - | SObject type of the records you want to upsert. Pattern: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z] |
| allowNoMoreFailedBatches | number | false | - | Mark a step as successful if the number of Failed Batches is less than the specified number (default: 0). |
| allowNoMoreFailedRecords | number | false | - | Mark a step as successful if the number of Failed Records is less than the specified number (default: 0). |
Additional attributes for sfdx.force.data.soql.query.csv step
Bulk upsert records from a CSV file
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| csvFile | string | true | yes | Path to the CSV file name to save output data |
| sObjectType | string | true | - | Salesforce object to query data. Pattern: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z] |
| sObjectFields | string[] | true | - | Array of Salesforce object fields to query. Pattern: [A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z](\.[A-Za-z][0-9A-Za-z_]{0,38}[0-9A-Za-z]){0,4} |
| queryFilter | string | false | - | Query filter for Source org data. Allowed WHERE and LIMIT |
Additional attributes for sfdx.force.data.tree.import step
Import data into an org
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| planFile | string | true | yes | Path to plan to insert multiple data files that have master-detail relationships |
Additional attributes for sfdx.force.mdApi.deploy step
Deploy metadata to an org using Metadata API
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| testLevel | string | true | - | Specifies which tests to run, using one of these TestLevel enum values: - NoTestRun-No one test runs. - RunSpecifiedTests — Only the tests that you specify are run (not supported yet). - RunLocalTests — All tests in your org are run, except the ones that originate from installed managed packages. - RunAllTestsInOrg — All tests are in your org and in installed managed packages are run |
| checkOnly | boolean | false | - | Validate deploy but don’t save to the org |
| deployDir | string | false | yes | Root of directory tree of files to deploy. deployDir or deployZip is required. deployDir will be used if specified both parameters |
| deployZip | string | false | yes | Path to Zip of files to deploy. deployDir or deployZip is required. deployDir will be used if specified both parameters |
Additional attributes for sfdx.force.mdApi.retrieve step
Retrieve metadata from an org using Metadata API
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| retrieveTargetDir | string | true | yes | Directory for the retrieved metadata |
| manifestFile | string | false | yes | File path of manifest of components to retrieve |
| packageNames | string[] | false | - | List of packages to retrieve |
Additional attributes for sfdx.force.org.create.scratch step
Create a scratch org
| Attribute | Type | Required | $ref syntax | Description |
| alias | string | true | yes | Alias for the created org. Pattern: [0-9A-Za-z_-]{1,40} |
| noAncestors | boolean | false | - | Do not include second-generation package ancestors in the scratch org (default: false) |
| definitionFile | string | true | yes | Path to an org definition file |
| devHubUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| duration | number | false | yes | Duration of the scratch org (in days) (default: 1, min:1, max:30) |
| overrideDefinition.adminEmail | string | false | yes | Administrator Email address of the Dev Hub user making the scratch org creation request. |
Additional attributes for sfdx.force.org.delete step
Mark a scratch or sandbox org for deletion
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| devHubUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
Additional attributes for sfdx.force.org.display step
Get the description for the current or target org
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
Additional attributes for sfdx.force.package.install step
Install a package in the target org
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| packageId | string | true | yes | ID (starts with 04t) or alias of the package version to install. Pattern: 04t([0-9A-Za-z]{12}|[0-9A-Za-z]{15} |
Additional attributes for sfdx.force.source.push step
Push source to a scratch org from the project
| Attribute | Type | Required | $ref syntax | Description |
| targetUserName | string | true | yes | Username or alias for the target org. Pattern: [0-9A-Za-z_-]{1,40} |
| forceOverwrite | boolean | false | - | Ignore conflict warnings and overwrite changes to scratch org (default: false) |
Reference syntax
- $env.ENVIRONMENT_NAME
- $input.INPUT_ID
- $var.VARIABLE_ID
- $step.STEP_ID.outputs