Example mock testing

completion/_balena

@@ -22,7 +22,7 @@ _balena() {
   key_cmds=( add rm )
   local_cmds=( configure flash )
   os_cmds=( build-config configure download initialize versions )
-  release_cmds=( finalize invalidate validate )
+  release_cmds=( export finalize import invalidate validate )
   tag_cmds=( rm set )
 
 

completion/balena-completion.bash

@@ -21,7 +21,7 @@ _balena_complete()
   key_cmds="add rm"
   local_cmds="configure flash"
   os_cmds="build-config configure download initialize versions"
-  release_cmds="finalize invalidate validate"
+  release_cmds="export finalize import invalidate validate"
   tag_cmds="rm set"
 
 

docs/balena-cli.md

@@ -282,7 +282,9 @@ are encouraged to regularly update the balena CLI to the latest version.
 
 - Releases
 
+	- [release export <commitorid>](#release-export-commitorid)
 	- [release finalize <commitorid>](#release-finalize-commitorid)
+	- [release import <file> <fleet>](#release-import-file-fleet)
 	- [release <commitorid>](#release-commitorid)
 	- [release invalidate <commitorid>](#release-invalidate-commitorid)
 	- [release validate <commitorid>](#release-validate-commitorid)
@@ -3345,6 +3347,37 @@ The notes for this release
 
 # Releases
 
+## release export <commitOrId>
+
+Exporting a release to a file allows you to import an exact 
+copy of the original release into another app.
+
+If the SemVer of a release is provided using the --version option,
+the first argument is assumed to be the fleet's slug.
+
+Only successful releases can be exported.
+
+Examples:
+
+	$ balena release export a777f7345fe3d655c1c981aa642e5555 -o ../path/to/release.tar
+	$ balena release export myOrg/myFleet --version 1.2.3 -o ../path/to/release.tar
+
+### Arguments
+
+#### COMMITORID
+
+commit, ID, or version of the release to export
+
+### Options
+
+#### -o, --output OUTPUT
+
+output path
+
+#### --version VERSION
+
+version of the release to export from the specified fleet
+
 ## release finalize <commitOrId>
 
 Finalize a release. Releases can be "draft" or "final", and this command
@@ -3371,6 +3404,40 @@ the commit or ID of the release to finalize
 
 ### Options
 
+## release import <file> <fleet>
+
+is automatically omitted when importing a release. The backend will auto-increment
+the revision field of the imported release if a release exists with the same semver.
+A release will not be imported if a successful release with the same commit already
+exists.
+
+To export a release to a file, use 'balena release export'.
+
+Use the --override-version option to specify the version 
+of the imported release, overriding the one saved in the file.
+
+Examples:
+
+	$ balena release import ../path/to/release.tar myFleet
+	$ balena release import ../path/to/release.tar myOrg/myFleet
+	$ balena release import ../path/to/release.tar myOrg/myFleet --override-version 1.2.3
+
+### Arguments
+
+#### BUNDLE
+
+path to a file, e.g. "./release.tar"
+
+#### FLEET
+
+fleet that the release will be imported to, e.g. "myOrg/myFleet"
+
+### Options
+
+#### --override-version OVERRIDE-VERSION
+
+Imports this release with the specified version overriding the version in the file.
+
 ## release <commitOrId>
 
 The --json option is recommended when scripting the output of this command,

package.json

@@ -196,6 +196,7 @@
     "@balena/dockerignore": "^1.0.2",
     "@balena/env-parsing": "^1.1.8",
     "@balena/es-version": "^1.0.1",
+    "@balena/release-bundle": "^0.5.2",
     "@oclif/core": "^4.0.8",
     "@resin.io/valid-email": "^0.1.0",
     "@sentry/node": "^6.16.1",

src/commands/release/export.ts

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2016-2024 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { commitOrIdArg } from '.';
+import { Flags } from '@oclif/core';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { create } from '@balena/release-bundle';
+import * as fs from 'fs/promises';
+import * as semver from 'balena-semver';
+import { ExpectedError } from '../../errors';
+
+export default class ReleaseExportCmd extends Command {
+	public static description = stripIndent`
+		Exports a release into a file.
+
+        Exporting a release to a file allows you to import an exact 
+		copy of the original release into another app.
+
+		If the SemVer of a release is provided using the --version option,
+		the first argument is assumed to be the fleet's slug.
+
+		Only successful releases can be exported.
+`;
+	public static examples = [
+		'$ balena release export a777f7345fe3d655c1c981aa642e5555 -o ../path/to/release.tar',
+		'$ balena release export myOrg/myFleet --version 1.2.3 -o ../path/to/release.tar',
+	];
+
+	public static usage = 'release export <commitOrId>';
+
+	public static flags = {
+		output: Flags.string({
+			description: 'output path',
+			char: 'o',
+			required: true,
+		}),
+		version: Flags.string({
+			description: 'version of the release to export from the specified fleet',
+		}),
+		help: cf.help,
+	};
+
+	public static args = {
+		commitOrId: commitOrIdArg({
+			description: 'commit, ID, or version of the release to export',
+			required: true,
+		}),
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params, flags: options } = await this.parse(ReleaseExportCmd);
+
+		const balena = getBalenaSdk();
+
+		let release: balenaSdk.Release;
+		if (typeof options.version === 'string') {
+			const application = params.commitOrId;
+			const parsedVersion = semver.parse(options.version);
+			if (parsedVersion == null) {
+				throw new ExpectedError(
+					`Release of ${application} with version ${options.version} could not be exported; version must be valid SemVer.`,
+				);
+			} else {
+				const rawVersion =
+					parsedVersion.build.length === 0
+						? parsedVersion.version
+						: `${parsedVersion.version}+${parsedVersion.build[0]}`;
+				release = await balena.models.release.get(
+					{ application, rawVersion },
+					{ $select: ['id'] },
+				);
+			}
+		} else {
+			release = await balena.models.release.get(params.commitOrId, {
+				$select: ['id'],
+			});
+		}
+
+		try {
+			const releaseBundle = await create({
+				sdk: balena,
+				releaseId: release.id,
+			});
+			await fs.writeFile(options.output, releaseBundle);
+			const versionInfo =
+				typeof options.version === 'string'
+					? ` version ${options.version}`
+					: '';
+			console.log(
+				`Release ${params.commitOrId}${versionInfo} has been exported to ${options.output}.`,
+			);
+		} catch (error) {
+			throw new ExpectedError(
+				`Release ${params.commitOrId} could not be exported: ${error.message}`,
+			);
+		}
+	}
+}