Add --draft option to balena push

This change will allow to build releases as draft and have them being
set as final at a later stage. This change is part of a larger feature towards
using the builder as part of CI/CD pipelines.

Depends-on: https://github.com/balena-io/balena-builder/pull/868
Change-type: minor

doc/cli.markdown

@@ -2938,6 +2938,13 @@ Set release tags if the image build is successful (balenaCloud only). Multiple
 arguments may be provided, alternating tag keys and values (see examples).
 Hint: Empty values may be specified with "" (bash, cmd.exe) or '""' (PowerShell).
 
+#### --draft
+
+Instruct the builder to create the release as a draft. Draft releases are ignored
+by the 'track latest' release policy but can be used through release pinning.
+Draft releases can be marked as final through the API. Releases are created
+as final by default unless this option is given.
+
 # Settings
 
 ## settings

lib/commands/push.ts

@@ -58,6 +58,7 @@ interface FlagsDef {
 	'noconvert-eol': boolean;
 	'multi-dockerignore': boolean;
 	'release-tag'?: string[];
+	draft: boolean;
 	help: void;
 }
 
@@ -267,6 +268,14 @@ export default class PushCmd extends Command {
 			multiple: true,
 			exclusive: ['detached'],
 		}),
+		draft: flags.boolean({
+			description: stripIndent`
+				Instruct the builder to create the release as a draft. Draft releases are ignored
+				by the 'track latest' release policy but can be used through release pinning.
+				Draft releases can be marked as final through the API. Releases are created
+				as final by default unless this option is given.`,
+			default: false,
+		}),
 		help: cf.help,
 	};
 
@@ -362,6 +371,7 @@ export default class PushCmd extends Command {
 			registrySecrets,
 			headless: options.detached,
 			convertEol: !options['noconvert-eol'],
+			isDraft: options.draft,
 		};
 		const args = {
 			appSlug: application.slug,
@@ -394,7 +404,7 @@ export default class PushCmd extends Command {
 		registrySecrets: RegistrySecrets,
 	) {
 		// Check for invalid options
-		const remoteOnlyOptions: Array<keyof FlagsDef> = ['release-tag'];
+		const remoteOnlyOptions: Array<keyof FlagsDef> = ['release-tag', 'draft'];
 		this.checkInvalidOptions(
 			remoteOnlyOptions,
 			options,

lib/utils/remote-build.ts

@@ -42,6 +42,7 @@ export interface BuildOpts {
 	headless: boolean;
 	convertEol: boolean;
 	multiDockerignore: boolean;
+	isDraft: boolean;
 }
 
 export interface RemoteBuild {
@@ -92,6 +93,7 @@ async function getBuilderEndpoint(
 		emulated: opts.emulated,
 		nocache: opts.nocache,
 		headless: opts.headless,
+		isdraft: opts.isDraft,
 	});
 	// Note that using https (rather than http) is a requirement when using the
 	// --registry-secrets feature, as the secrets are not otherwise encrypted.

tests/commands/push.spec.ts

@@ -73,6 +73,7 @@ const commonQueryParams = [
 	['emulated', 'false'],
 	['nocache', 'false'],
 	['headless', 'false'],
+	['isdraft', 'false'],
 ];
 
 const hr =