Merge pull request #3790 from replicatedhq/alicenstar/sc-133212/release-create-command-should-also-support

update docs with release create --required flag in CLI

Author: alicenstar

docs/reference/replicated-cli-release-create.mdx

@@ -26,6 +26,19 @@ Create a new release by providing application manifests for the next release in
 replicated release create [flags]
 ```
 
+### Examples
+
+```
+# Create and promote a release to the Unstable channel
+replicated release create --yaml-dir ./manifests --promote Unstable --version 1.0.0
+
+# Create and promote a required release (users cannot skip this upgrade)
+replicated release create --yaml-dir ./manifests --promote Unstable --version 1.0.0 --required
+
+# Create a release with auto-generated values (useful in CI/CD)
+replicated release create --auto --confirm-auto
+```
+
 ### Options
 
 ```
@@ -38,6 +51,7 @@ replicated release create [flags]
   -o, --output string          The output format to use. One of: json|table (default "table")
       --promote string         Channel name (case sensitive) or id to promote this release to
       --release-notes string   When used with --promote <channel>, sets the **markdown** release notes
+      --required               When used with --promote <channel>, marks this release as required during upgrades.
       --version string         When used with --promote <channel>, sets the version label for the release in this channel
       --yaml-dir string        The directory containing multiple yamls for a Kots release. Cannot be used with the --yaml flag.
 ```

docs/vendor/ci-workflows.mdx

@@ -289,12 +289,14 @@ Add a job that promotes the release to a shared internal-only or customer-facing
 
 Consider the following requirements and recommendations:
 
-* Replicated recommends that you include the `--version` flag with the `release promote` command to explicitly declare the version label for the release. Use the same version label that was used when the release was created as part of [Create a release and promote to a temporary channel](#rel-release) above. Although the `--version` flag is not required, declaring the same release version label during promotion provides additional consistency that makes the releases easier to track. 
+* Replicated recommends that you include the `--version` flag with the `release promote` command to explicitly declare the version label for the release. Use the same version label that was used when the release was created as part of [Create a release and promote to a temporary channel](#rel-release) above. Although the `--version` flag is not required, declaring the same release version label during promotion provides additional consistency that makes the releases easier to track.
 
 * The channel to which the release is promoted depends on the event triggers that you defined for the workflow. For example, if the workflow runs on every commit to the `main` branch, then promote the release to an internal-only channel, such as Unstable. For more information, see [Define Workflow Triggers](#rel-triggers) above.
 
 * Use the `--release-notes` flag to include detailed release notes in markdown.
 
+* For release versions that must not be skipped during upgrades (such as versions that include a required database migration), use the `--required` flag to mark the release as required. This flag can be used with both `release create --promote` and `release promote` commands. For more information about required releases, see [Required Releases](/vendor/releases-about#required-releases) in _About Channels and Releases_.
+
 ### Archive the temporary channel and customer {#rel-cleanup}
 
 Finally, add a job to archive the temporary channel and customer that you created. This ensures that these artifacts are removed from your Replicated team and that they do not have to be manually archived after the release is promoted.

docs/vendor/releases-creating-cli.mdx

@@ -70,6 +70,8 @@ To create and promote a release:
       * `PATH_TO_RELEASE_DIR` is the path to the directory with the release files.
       * `CHANNEL` is the channel ID or the case sensitive name of the channel.
 
+      For a complete list of options for the command, see [release create](/reference/replicated-cli-release-create).
+
    * **Create and edit the release before promoting**:
 
       1. Create the release: