> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/releasing-artifacts/release-definitions.md). # 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. {% hint style="info" %} Please note, when using release definition with exact version numbers. The format of the version number would be \: 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). However the format is slightly different from the version that is tagged in the git repository where it follows X.Y.Z.BuildNumber **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 {% endhint %} ``` promotePackagesBeforeDeploymentToOrg: ``` 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](/flxbl/sfp/releasing-artifacts/generating-a-changelog.md) Here is a run down of all attributes that make up a release definition | 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 | Package dependencies (e.g. managed packages) to install as part of the release. Each value is either a `04t` subscriber package version id or a four-part version number such as `1.4.3.2` or `1.4.4.LATEST`. See [Package dependencies](#package-dependencies). | | 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 | ## 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](/flxbl/sfp/development/defining-a-domain/release-config.md). 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flxbl.io/flxbl/sfp/releasing-artifacts/release-definitions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.