Release Definitions

A release definition is a YAML file that carries attributes of artifacts and other details. A release definition is the main input for a release command.

release: Sprint-2-13-11-6844956242
skipIfAlreadyInstalled: true
artifacts:
  feature-management: 1.0.19-6844956242
  apex-logger: 1.0.20-89
promotePackagesBeforeDeploymentToOrg: prod
changelog:
  workItemFilters:
    - (FGK|FFK)-[0-9]{3,4}
  workItemUrl: https://flxbl.atlassian.net/browse
  limit: 30

Lets examine closely the above release defintion file and understand the various attributes and it purposes

release: Sprint-2-13-11-6844956242

This defines the name of the release. this value will be utilised to generate changelogs or as an identification for other systems to understand what release went into an org

skipIfAlreadyInstalled: true

This attribute determines whether artifacts should be skipped from installing if the same version number is already installed in the target org

artifacts:
  feature-management: 1.0.19-6844956242
  apex-logger: 1.0.20-89

This attribute determines which artifacts constitute the provided release.

promotePackagesBeforeDeploymentToOrg: <targetOrgAlias>

The above attribute determines whether an artifact of type unlocked package should be promoted before installing into the target org as provided by the alias. If the alias of the requested org and the targeOrgAlias matches, the unlocked packages are promoted before installing into the org

changelog:
  workItemFilters:
    - (FGK|FFK)-[0-9]{3,4}
  workItemUrl: https://flxbl.atlassian.net/browse
  limit: 30

The reminder of the attributes are about generating change log, which are explained here

Here is a run down of all attributes that make up a release definition

Package dependencies

packageDependencies is the set of external packages — typically managed packages, or unlocked packages produced outside this project — that a release installs alongside its artifacts. Each entry maps a package name to a version:

packageDependencies:
  MyManagedPackage: 04tXXXXXXXXXXXXXXX
  SharedLibrary: 1.4.4.LATEST

How the list is built

In most projects you do not write packageDependencies by hand. When a release definition is generated, sfp assembles it from two sources, both controlled by the release config:

1. Discovered from the project. The external packages declared in packageAliases in sfdx-project.json (subscriber package version ids, 04t...), filtered by:
   • excludeAllPackageDependencies: true — drop every discovered dependency.
   • includeOnlyPackageDependencies — keep only the listed packages.
   • excludePackageDependencies — keep everything except the listed packages.
2. Declared explicitly. A packageDependencies map in the release config is copied into the generated definition. These entries may be a 04t id or a version number, and an entry overrides a discovered dependency of the same name.

Entries are kept in order — discovered dependencies first, then the release-config entries in the order you declare them. Package dependencies are installed sequentially, so list a prerequisite before anything that needs it.

These attributes live in the release config, not the release definition — see Release config. To carry a version-number dependency through the generated definition, declare it in the release config's packageDependencies map.

Accepted values

Each packageDependencies value is one of:

• A subscriber package version id (04t...). The exact version is pinned and installed as provided.
• A four-part version number — X.Y.Z.BuildNumber (for example 1.4.3.2), or X.Y.Z.LATEST (for example 1.4.4.LATEST, the latest build matching 1.4.4). Version numbers are resolved to a concrete package version at release time.

Resolving version numbers

When a value is a version number rather than a 04t id, sfp release resolves it against a Dev Hub as the release runs. Versioned entries require:

• --devhubalias on the sfp release command. A release that carries a versioned dependency without it fails.
• A packageAliases entry in sfdx-project.json for each versioned package, pointing at its Package2 id (0Ho...):

{
  "packageAliases": {
    "SharedLibrary": "0HoXXXXXXXXXXXXXXX"
  }
}

Pinned 04t values need neither a Dev Hub nor a package alias — they are installed directly.