Add setReleaseVersion to release model

Change-type: minor

src/models/release.ts

@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+import * as bSemver from 'balena-semver';
 import * as errors from 'balena-errors';
 import once = require('lodash/once');
 import type * as BalenaSdk from '..';
@@ -561,6 +562,43 @@ const getReleaseModel = function (
 		});
 	}
 
+	/**
+	 * @summary Sets a given release semver.
+	 * @name setReleaseVersion
+	 * @public
+	 * @function
+	 * @memberof balena.models.release
+	 *
+	 * @param {String|Number|Object} commitOrIdOrRawVersion - release commit (string) or id (number) or an object with the unique `application` (number or string) & `rawVersion` (string) pair of the release
+	 * @param {String|Null} semver - valid semver string
+	 *
+	 * @returns {Promise}
+	 *
+	 * @example
+	 * balena.models.release.setKnownIssueList('7cf02a6', '1.2.3');
+	 *
+	 * @example
+	 * balena.models.release.setKnownIssueList(123, '1.2.3');
+	 *
+	 * @example
+	 * balena.models.release.setKnownIssueList({application: 456, rawVersion: '0.0.0'}, '1.2.3');
+	 */
+	async function setReleaseVersion(
+		commitOrIdOrRawVersion: string | number | ReleaseRawVersionApplicationPair,
+		semver: string,
+	): Promise<void> {
+		if (!bSemver.valid(semver)) {
+			throw new errors.BalenaInvalidParameterError('semver', semver);
+		}
+
+		const { id } = await get(commitOrIdOrRawVersion, { $select: 'id' });
+		await pine.patch<Release>({
+			resource: 'release',
+			id,
+			body: { semver },
+		});
+	}
+
 	/**
 	 * @namespace balena.models.release.tags
 	 * @memberof balena.models.release
@@ -721,6 +759,7 @@ const getReleaseModel = function (
 		setIsInvalidated,
 		setNote,
 		setKnownIssueList,
+		setReleaseVersion,
 		tags,
 	};
 };

tests/integration/models/release.spec.ts

@@ -595,6 +595,38 @@ describe('Release Model', function () {
 			});
 		});
 
+		describe('balena.models.release.setReleaseVersion()', function () {
+			uniquePropertyNames.forEach((field) => {
+				const fieldLabel = getFieldLabel(field);
+				it(`should set the semver using the release ${fieldLabel}`, async () => {
+					const release = ctx.currentRelease;
+					const semverParam = getParam(field, release);
+					const semver = '1.2.3';
+					await balena.models.release.setReleaseVerion(semverParam, semver);
+					const updatedRelease = await balena.models.release.get(release.id, {
+						$select: ['id', 'semver'],
+					});
+					expect(updatedRelease).to.deep.match({
+						id: release.id,
+						semver,
+					});
+				});
+
+				it(`should throw when setting invalid semver using the release ${fieldLabel}`, async () => {
+					const release = ctx.currentRelease;
+					const semverParam = getParam(field, release);
+					const semver = 'in.va.lid';
+					const promise = balena.models.release.setReleaseVerion(
+						semverParam,
+						semver,
+					);
+					await expect(promise).to.be.rejectedWith(
+						"Invalid parameter: in.va.lid is not a valid value for parameter 'semver'",
+					);
+				});
+			});
+		});
+
 		describe('balena.models.release.tags', function () {
 			const appTagTestOptions: tagsHelper.Options = {
 				model: balena.models.release.tags,