diff --git a/automation/capitanodoc/capitanodoc.ts b/automation/capitanodoc/capitanodoc.ts index ed0e2334..d4b21244 100644 --- a/automation/capitanodoc/capitanodoc.ts +++ b/automation/capitanodoc/capitanodoc.ts @@ -82,6 +82,14 @@ const capitanoDoc = { 'build/commands/device/shutdown.js', ], }, + { + title: 'Releases', + files: [ + 'build/commands/releases.js', + 'build/commands/release/index.js', + 'build/commands/release/finalize.js', + ], + }, { title: 'Environment Variables', files: [ diff --git a/doc/cli.markdown b/doc/cli.markdown index 8ee515c3..9e8380c1 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -207,6 +207,12 @@ are encouraged to regularly update the balena CLI to the latest version. - [device rm <uuid(s)>](#device-rm-uuid-s) - [device shutdown <uuid>](#device-shutdown-uuid) +- Releases + + - [releases <fleet>](#releases-fleet) + - [release <commitorid>](#release-commitorid) + - [release finalize <commitorid>](#release-finalize-commitorid) + - Environment Variables - [envs](#envs) @@ -1294,6 +1300,80 @@ the uuid of the device to shutdown force action if the update lock is set +# Releases + +## releases <fleet> + +List all releases of the given fleet. + +Fleets may be specified by fleet name or slug. Slugs are recommended because +they are unique and unambiguous. Slugs can be listed with the `balena fleets` +command. Note that slugs may change if the fleet is renamed. Fleet names are +not unique and may result in "Fleet is ambiguous" errors at any time (even if +"it used to work in the past"), for example if the name clashes with a newly +created public/open fleet, or with fleets from other balena accounts that you +may be invited to join under any role. For this reason, fleet names are +especially discouraged in scripts (e.g. CI environments). + +Examples: + + $ balena releases myorg/myfleet + +### Arguments + +#### FLEET + +fleet name or slug + +### Options + +## release <commitOrId> + + + +Examples: + + $ balena release a777f7345fe3d655c1c981aa642e5555 + $ balena release 1234567 + +### Arguments + +#### COMMITORID + +the commit or ID of the release to get information + +### Options + +#### -c, --composition + +Return the release composition + +## release finalize <commitOrId> + +Finalize a release. Releases can be "draft" or "final", and this command +changes a draft release into a final release. Draft releases can be created +with the `--draft` option of the `balena build` or `balena deploy` +commands. + +Draft releases are not automatically deployed to devices tracking the latest +release. For a draft release to be deployed to a device, the device should be +explicity pinned to that release. Conversely, final releases may trigger immediate +deployment to unpinned devices (subject to a device's polling period) and, for +this reason, final releases cannot be changed back to draft status. + +Examples: + + $ balena release finalize a777f7345fe3d655c1c981aa642e5555 + $ balena release finalize 1234567 + +### Arguments + +#### COMMITORID + +the commit or ID of the release to finalize + +### Options + # Environment Variables ## envs diff --git a/lib/commands/release/finalize.ts b/lib/commands/release/finalize.ts index 53c09846..6cd09f7d 100644 --- a/lib/commands/release/finalize.ts +++ b/lib/commands/release/finalize.ts @@ -38,7 +38,7 @@ export default class ReleaseFinalizeCmd extends Command { with the \`--draft\` option of the \`balena build\` or \`balena deploy\` commands. - Draft releases are not automatically deployed to devices tracking the latest application + Draft releases are not automatically deployed to devices tracking the latest release. For a draft release to be deployed to a device, the device should be explicity pinned to that release. Conversely, final releases may trigger immediate deployment to unpinned devices (subject to a device's polling period) and, for @@ -49,7 +49,7 @@ export default class ReleaseFinalizeCmd extends Command { '$ balena release finalize 1234567', ]; - public static usage = 'finalize '; + public static usage = 'release finalize '; public static flags: flags.Input = { help: cf.help,