Add content on immutable releases (#57225)

Co-authored-by: Laura Coursen <[email protected]>
Co-authored-by: Kyle Kelly <[email protected]>

Author: 3 people

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

@@ -56,11 +56,16 @@ To use a specific action version, users can configure their {% data variables.pr
 
 We recommend using tags for actions release management. Using this approach, your users can easily distinguish between major and minor versions:
 
-* Create and validate a release on a release branch (such as `release/v1`) before creating the release tag (for example, `v1.0.2`).
-* Create a release using semantic versioning. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository).
-* 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).
-* 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.
-* Major versions can be initially released with a `beta` tag to indicate their status, for example, `v2-beta`. The `-beta` tag can then be removed when ready.
+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).
+
+    {% 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. 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.
 
 This example demonstrates how a user can reference a major release tag:
 

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

@@ -72,7 +72,7 @@ Here is an example process that you can follow to automatically run tests, creat
 
    * When a release is published or edited, your release workflow will automatically take care of compilation and adjusting tags.
 
-   * We recommend creating releases using semantically versioned tags – for example, `v1.1.3` – and keeping major (`v1`) and minor (`v1.1`) tags current to the latest appropriate commit. For more information, see [AUTOTITLE](/actions/creating-actions/about-custom-actions#using-release-management-for-actions) and [About semantic versioning](https://docs.npmjs.com/about-semantic-versioning).
+   * We recommend creating releases using semantically versioned tags – for example, `v1.1.3` – and keeping major (`v1`) and minor (`v1.1`) tags current to the latest appropriate commit. For more information, see [AUTOTITLE](/actions/how-tos/create-and-publish-actions/manage-custom-actions#using-release-management-for-actions) and [About semantic versioning](https://docs.npmjs.com/about-semantic-versioning).
 
 ### Results
 

content/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations.md

@@ -190,3 +190,5 @@ gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
 ## Next steps
 
 To keep your attestations relevant and manageable, you should delete attestations that are no longer needed. See [AUTOTITLE](/actions/how-tos/security-for-github-actions/using-artifact-attestations/managing-the-lifecycle-of-artifact-attestations).
+
+You can also generate release attestations to help consumers verify the integrity and origin of your releases. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases).

content/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds.md

@@ -59,6 +59,13 @@ How exactly you sign your build will depend on what sort of code you're writing,
 
 For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets){% ifversion fpt or ghec %}, [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect),{% endif %} and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners).
 
+{% ifversion immutable-releases-preview %}
+
+## Use immutable releases
+
+If you are using release assets from other projects in your build system, or creating releases for your own work, you should reduce security risk by ensuring those releases are immutable, meaning they cannot be changed after publication. Immutable releases help prevent supply chain attacks and accidental breaking changes. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases).
+{% endif %}
+
 ## Harden security for {% data variables.product.prodname_actions %}
 
 There are many further steps you can take to additionally secure {% data variables.product.prodname_actions %}. In particular, be careful when evaluating third-party workflows, and consider using `CODEOWNERS` to limit who can make changes to your workflows.

content/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases.md

@@ -0,0 +1,27 @@
+---
+title: Immutable releases
+intro: 'Learn about immutable releases and how they can help you maintain the integrity of your software supply chain.'
+versions:
+  feature: immutable-releases-preview
+type: overview
+topics:
+  - Code Security
+  - Vulnerabilities
+  - Dependencies
+---
+
+{% data reusables.releases.immutable-releases-preview-note %}
+
+**Immutable releases** are releases where the assets and associated Git tag cannot be changed after publication. They increase security by blocking:
+* Supply chain attacks where attackers inject vulnerabilities or malware into current project releases
+* Accidental changes to assets and tags that may break developer workflows
+
+Additionally, creating an immutable release automatically generates a **release attestation**, which is a cryptographically verifiable record of a release containing the release tag, commit SHA, and release assets. Consumers can use this attestation to make sure the releases and artifacts they are using exactly match the published {% data variables.product.github %} releases.
+
+If a release is immutable, you will see "{% octicon "lock" aria-hidden="true" %} Immutable"  below the title on the release page.
+
+## Next steps
+
+To learn how to enable immutable releases for your repository or organization, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/preventing-changes-to-your-releases).
+
+To learn how to ensure a release and local assets have not been changed, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/verifying-the-integrity-of-a-release).

content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md

@@ -23,4 +23,7 @@ children:
   - /enforcing-dependency-review-across-an-organization
   - /exploring-the-dependencies-of-a-repository
   - /troubleshooting-the-dependency-graph
+  - /immutable-releases
+  - /preventing-changes-to-your-releases
+  - /verifying-the-integrity-of-a-release
 ---

content/code-security/supply-chain-security/understanding-your-software-supply-chain/preventing-changes-to-your-releases.md

@@ -0,0 +1,28 @@
+---
+title: Preventing changes to your releases
+shortTitle: Prevent release changes
+intro: 'You can enforce immutable releases for a repository or organization to prevent potential vulnerabilities.'
+versions:
+  feature: immutable-releases-preview
+type: overview
+topics:
+  - Code Security
+  - Vulnerabilities
+  - Dependencies
+---
+
+{% data reusables.releases.immutable-releases-preview-note %}
+
+## Enforcing immutable releases for your repository
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+1. Scroll down to the "Releases" section, then select **Enable release immutability**. Be aware that immutability will only apply to future releases.
+
+## Enforcing immutable releases for your organization
+
+{% data reusables.organizations.navigate-to-org %}
+{% data reusables.organizations.org_settings %}
+1. In the "Code, planning, and automation" section of the sidebar, select the {% octicon "repo" aria-hidden="true" %} **Repository** dropdown menu, then click **General**.
+1. In the "Releases" section of the page, select the **No policy** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click either **All repositories** or **Selected repositories**. Be aware that immutability will only apply to future releases.
+1. If you chose **Selected repositories**, to the right of the dropdown menu, click {% octicon "gear" aria-label="Select repositories" %}. Select the repositories you want to include, then click **Select repositories**.

content/code-security/supply-chain-security/understanding-your-software-supply-chain/verifying-the-integrity-of-a-release.md

@@ -0,0 +1,48 @@
+---
+title: Verifying the integrity of a release
+shortTitle: Verify release integrity
+intro: 'You can avoid tampering and accidental changes by ensuring the releases you use have not been modified after publication.'
+versions:
+  feature: immutable-releases-preview
+type: overview
+topics:
+  - Code Security
+  - Vulnerabilities
+  - Dependencies
+defaultTool: cli
+---
+
+{% data reusables.releases.immutable-releases-preview-note %}
+
+{% cli %}
+
+## Prerequisites
+
+Before you can validate the authenticity of a release and its assets on the command line, you need to [install the {% data variables.product.prodname_cli %}](https://github.com/cli/cli?tab=readme-ov-file#installation).
+
+## Verifying immutable releases and local artifacts
+
+1. On the command line, open the repository containing the release you want to verify.
+1. To verify a release exists and is immutable, run the following command:
+
+    ```bash copy
+    gh release verify RELEASE-TAG
+    ```
+
+1. To verify a local artifact is an exact match for a release asset, run the following command:
+
+    ```bash copy
+    gh release verify-asset RELEASE-TAG ARTIFACT-PATH
+    ```
+
+    > [!NOTE]
+    > This command cannot be used to verify the source code zip file or tarball for a release, since these assets are only created when a download is requested.
+
+{% endcli %}
+{% webui %}
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.releases %}
+1. To the left of the release you want to verify, below the release author, confirm that "{% octicon "lock" aria-hidden="true" %} Immutable" is present.
+
+{% endwebui %}

content/repositories/releasing-projects-on-github/managing-releases-in-a-repository.md

@@ -67,6 +67,11 @@ If you @mention any {% data variables.product.github %} users in the notes, the
 
 ## Editing a release
 
+{% ifversion immutable-releases-preview %}
+> [!NOTE]
+> If you have enabled immutable releases for your repository, you can only edit the title and release notes after a release is published. See [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases).
+{% endif %}
+
 {% webui %}
 
 {% data reusables.repositories.navigate-to-repo %}

data/features/immutable-releases-preview.yml

@@ -0,0 +1,7 @@
+# Reference: #18409
+# Documentation for the immutable releases public preview
+
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>3.18'