Add content on using immutable releases in actions release management (#57299)

Author: sabrowning1

content/actions/how-tos/create-and-publish-actions/index.md

@@ -16,5 +16,5 @@ children:
   - /set-exit-codes
   - /publish-in-github-marketplace
   - /release-and-maintain-actions
+  - /using-immutable-releases-and-tags-to-manage-your-actions-releases
 ---
-

content/actions/how-tos/create-and-publish-actions/manage-custom-actions.md

@@ -42,10 +42,6 @@ To ensure that your action is compatible with other platforms, do not use any ha
 
 ## Using release management for actions
 
-This section explains how you can use release management to distribute updates to your actions in a predictable way.
-
-### Good practices for release management
-
 If you're developing an action for other people to use, we recommend using release management to control how you distribute updates. Users can expect an action's patch version to include necessary critical fixes and security patches, while still remaining compatible with their existing workflows. You should consider releasing a new major version whenever your changes affect compatibility.
 
 Under this release management approach, users should not be referencing an action's default branch, as it's likely to contain the latest code and consequently might be unstable. Instead, you can recommend that your users specify a major version when using your action, and only direct them to a more specific version if they encounter issues.
@@ -54,20 +50,20 @@ To use a specific action version, users can configure their {% data variables.pr
 
 ### Using tags for release management
 
-We recommend using tags for actions release management. Using this approach, your users can easily distinguish between major and minor versions:
+{% ifversion immutable-releases-preview %}
+> [!NOTE] If you have enabled immutable releases to help prevent supply chain attacks and accidental changes to your releases, instead see [AUTOTITLE](/actions/how-tos/create-and-publish-actions/using-immutable-releases-and-tags-to-manage-your-actions-releases).
+{% endif %}
 
-1. Create and validate a release on a release branch (such as `release/v1`) before creating the release tag (for example, `v1.0.2`).
-1. Create a release using semantic versioning. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository).
-1. Move the major version tag (such as `v1`, `v2`) to point to the Git ref of the current release. For more information, see [Git basics - tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging).
+We recommend using tags for actions release management. Using this approach, your users can easily distinguish between major and minor versions:
 
-    {% ifversion immutable-releases-preview %}
-    > [!NOTE]
-    > If you enable immutable releases, you can still move Git tags that are not linked to releases on {% data variables.product.github %}.
-    {% endif %}
+1. Develop and validate a release on a release branch (for example, `release/v1`).
+1. Create a release with a release tag using semantic versioning (for example, `v1.0.1`). For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository).
+1. Move the major version tag (for example, `v1`) to point to the Git ref of the current release. For more information, see [Git basics - tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging).
+1. Introduce a new major version tag (for example, `v2`) for changes that will break existing workflows, such as changing an action's inputs.
 
-1. Introduce a new major version tag (`v2`) for changes that will break existing workflows. For example, changing an action's inputs would be a breaking change.
+#### Syntax for referencing tags
 
-This example demonstrates how a user can reference a major release tag:
+This example demonstrates how a user can reference a major version tag:
 
 ```yaml
 steps:

content/actions/how-tos/create-and-publish-actions/release-and-maintain-actions.md

@@ -55,6 +55,11 @@ To support the developer process in the next section, add two {% data variables.
 1. Add a workflow that triggers when a commit is pushed to a feature branch or to `main` or when a pull request is created. Configure the workflow to run your unit and integration tests. For an example, see [this workflow](https://github.com/actions/javascript-action/blob/main/.github/workflows/ci.yml).
 1. Add a workflow that triggers when a release is published or edited. Configure the workflow to ensure semantic tags are in place. You can use an action like [JasonEtco/build-and-tag-action](https://github.com/JasonEtco/build-and-tag-action) to compile and bundle the JavaScript and metadata file and force push semantic major, minor, and patch tags. For more information about semantic tags, see [About semantic versioning](https://docs.npmjs.com/about-semantic-versioning).
 
+    {% ifversion immutable-releases-preview %}
+    > [!NOTE]
+    > If you enable immutable releases for your repository, you cannot use this action to force push tags tied to releases on {% data variables.product.github %}. To learn how to manage your releases with immutable releases, see [AUTOTITLE](/actions/how-tos/create-and-publish-actions/using-immutable-releases-and-tags-to-manage-your-actions-releases).
+    {% endif %}
+
 ### Example developer process
 
 Here is an example process that you can follow to automatically run tests, create a release{% ifversion fpt or ghec %} and publish to {% data variables.product.prodname_marketplace %}{% endif %}, and publish your action.

content/actions/how-tos/create-and-publish-actions/using-immutable-releases-and-tags-to-manage-your-actions-releases.md

@@ -0,0 +1,34 @@
+---
+title: Using immutable releases and tags to manage your action's releases
+shortTitle: Use immutable releases
+intro: 'Learn how you can use a combination of immutable releases on {% data variables.product.github %} and Git tags to manage your action''s releases.'
+versions:
+  feature: immutable-releases-preview
+topics:
+  - Actions
+  - Code Security
+  - Vulnerabilities
+  - Dependencies
+---
+
+{% data reusables.releases.immutable-releases-preview-note %}
+
+If you enable immutable releases on your action's repository, you can manage your action's releases as follows:
+
+1. To start the release cycle, develop and validate a potential release for your action on a release branch.
+1. Determine how you want to share your changes:
+   * If you are ready to share an unchangeable version of your action, create a release on {% data variables.product.github %} with a release-specific tag (for example, `v1.0.0`). See [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release).
+   * If you want to be able to update the Git tag of a release later, do not create a release on {% data variables.product.github %}. Instead, create a tag as follows:
+     * If your release contains breaking changes for existing workflows, create a major version tag (for example, `v1`).
+     * If your release contains new backwards-compatible functionality, create a minor version tag (for example, `v1.1`).
+     * If your release contains backwards-compatible bug fixes, create a patch version tag (for example, `v1.1.1`).
+1. For Git tags that are not tied to a release on {% data variables.product.github %}, ensure users have access to the latest compatible version of your action by updating them as follows:
+   * For a major version, update the tag to point to the Git ref of the latest related minor version or patch version.
+   * For a minor version, update the tag to point to the Git ref of the latest related patch version.
+
+    To move an existing Git tag to the most recent commit, force push the tag with the following commands:
+
+    ```bash copy
+    git tag -f TAG-NAME
+    git push -f --tags
+    ```