DX@Scale
October 23
Ask or search…
K
Comment on page

Release

The orchestrator:release command brings uniformity to the CI/CD landscape, allowing you to define 'releases' no matter which platform you are on. A release is defined by a YAML file, where you can specify the artifacts to be installed in the org, in addition to other parameters. The release will then be orchestrated based on the configuration of the YAML definition file.
sfp orchestrator:release -h
Release a collection of artifacts as defined in the release definition file
USAGE
$ sfp orchestrator:release -u <string> [-p <array>] [--scope <string> [--npm | -f <filepath>]] [--npmrcpath <filepath> ] [-g <array>] [-t <string>] [--waittime
<number>] [--keys <string>] [-d <string>] [-b <string> --generatechangelog] [-v <string>] [--json] [--loglevel
trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
FLAGS
-b, --branchname=<value> Repository branch in which the changelog files are located
-d, --directory=<value> Relative path to directory to which the release defintion file should be
generated, if the directory doesnt exist, it will be created
-f, --scriptpath=<value> (Optional: no-NPM) Path to script that authenticates and downloads artifacts
from the registry
-g, --logsgroupsymbol=<value> Symbol used by CICD platform to group/collapse logs in the console. Provide an
opening group, and an optional closing group symbol.
-p, --releasedefinition=<value> Path to release definiton yaml, Multiple paths can be seperated by commas
-t, --tag=<value> Tag the release with a label, useful for identification in metrics
-u, --targetorg=<value> (required) [default: scratchorg] Alias/User Name of the target environment
-v, --devhubalias=<value> Provide the alias of the devhub previously authenticated, default value is
HubOrg
--generatechangelog Create a release changelog
--json format output as json
--keys=<value> Keys to be used while installing any managed package dependencies. Required
format is a string of key-value pairs separated by spaces e.g. packageA:pw123
packageB:pw123 packageC:pw123
--loglevel=(trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL) [default: info] logging level for this command invocation
--npm Download artifacts from a pre-authenticated private npm registry
--npmrcpath=<value> Path to .npmrc file used for authentication to registry. If left blank,
defaults to home directory
--scope=<value> (required for NPM) User or Organisation scope of the NPM package
--waittime=<value> [default: 120] Wait time for package installation
DESCRIPTION
Release a collection of artifacts as defined in the release definition file
EXAMPLES
$ sfp orchestrator:release -p path/to/releasedefinition.yml -u myorg --npm --scope myscope --generatechangelog

Release Definition

# release-definition.yaml
release: "release-1.0"
skipIfAlreadyInstalled: true
baselineOrg: "myorg"
promotePackagesBeforeDeploymentToOrg:"SIT"
artifacts:
mypackageA: LATEST_GIT_TAG or LATEST_TAG
mypackageB: LATEST_TAG # Substituted with version from latest git tag at runtime
mypackageC: 1.2.3-5 # Provide the exact version to download
packageDependencies:
Marketing Cloud: 04t0H000000xVrw
changelog:
workItemFilters:
- "BRO-[0-9]{3,4}"
workItemUrl: "https://www.atlassian.com/software/jira"
limit: 30
showAllArtifacts: false
Please note, when using release definition with exact version numbers. The format of the version number would be <packageName>: X.Y.Z-BuildNumber, where the version number adopts the following semantics X - Major Y - Minor Z - Patch BuildNumber - The build number that produced the package The version exactly follows the semantics used by the artifact registry (such as Github Packages)\
Example: A package that has the version core_crm_v3.0.0.6936, tagged in git should be referenced as core_crm: 3.0.0-6936
Parameter
Required
Type
Description
release
Yes
string
Name of the release
skipIfAlreadyInstalled
No
boolean
Skip installation of artifact if it's already installed in target org
baselineOrg
No
string
The org used to decide whether or not to skip installation of an artifact. Defaults to the target org when not provided.
artifacts
Yes
Object
Map of artifacts to deploy and their corresponding version
promotePackagesBeforeDeploymentToOrg
No
string
Promote packages before they are installed into an org that matches alias of the org
packageDependencies
No
Object
Packages dependencies (e.g. managed packages) to install as part of the release. Provide the 04t subscriber package version Id.
changelog.repoUrl
No
Prop
The URL of the version control system to push changelog files
changelog.workItemFilters
No
Prop
An array of regular expression used to identify work items in your commit messages
changelog.workitemUrl
No
Prop
The generic URL of work items, to which to append work item codes. Allows easy redirection to user stories by clicking on the work-item link in the changelog.
changelog.limit
No
Prop
Limit the number of releases to display in the changelog markdown
changelog.showAllArtifacts
No
Prop
Whether to show artifacts that haven't changed between releases

Automated generation of release definition

In a high velocity project operating on a trunk and with substantial number of packages, manually generating release definition can be a chore. This can eased by using generating the release definition file automatically after every publish command. Read on more about release definition generation using the link below.

Fetching Artifacts for Release

The orchestrator:release command provides a simplified method of fetching artifacts from an artifact repository using the release definition file which contains the name of the artifacts that you want to download, and a mapping to the version to download. If fetching from a NPM registry, the command will handle everything else for you. However, for universal artifacts there is no uniform method for downloading artifacts from a repository, so you will need to provide a shell script that calls the relevant API.
TheLATEST_TAG keyword is only supported if the current working directory is pointing to the project directory, and if at least one git tag exists for the package.

Fetching universal artifacts

For universal artifacts, there is no uniform method for downloading artifacts from a registry, so you will need to provide a shell script that calls the relevant API. You need to pass the path to script file using the flag --scriptpath
There are multiple parameters available in the shell script. Pass these parameters to the API call, and at runtime they will be substituted with the corresponding values:
  1. 1.
    Artifact name
  2. 2.
    Artifact version
  3. 3.
    Directory to download artifacts
Eg. Fetching from Azure Artifacts using the Az CLI on Linux
#!/bin/bash
# $1 - artifact name
# $2 - artifact version
# $3 - artifact directory
echo "Downloading Artifact $1 Version $2"
az artifacts universal download --feed myfeed --name $1 --version $2 --path $3 \
--organization "https://dev.azure.com/myorg/" --project myproject --scope project

Changelog

When the --generatechangelog flag is passed to the command, a changelog will automatically be generated if the release is successful. The changelog provides traceability for the artifacts, work items and commits that were introduced by each release, as well as an at-a-glance view of all your orgs and which release they are currently on.
To generate a changelog, thechangelog.repoUrlandchangelog.workItemFilter parameters must be configured in the release definition file.
A changelog is generated in markdown format and pushed to the repo, utilizing thebranchname flag provided to the release command. If the command finds a previous changelog files, it will utilize to generate an incremental changelog