diff --git a/content/actions/how-tos/create-and-publish-actions/manage-custom-actions.md b/content/actions/how-tos/create-and-publish-actions/manage-custom-actions.md index c5f98529a4..3033c6b737 100644 --- a/content/actions/how-tos/create-and-publish-actions/manage-custom-actions.md +++ b/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: diff --git a/content/actions/how-tos/create-and-publish-actions/release-and-maintain-actions.md b/content/actions/how-tos/create-and-publish-actions/release-and-maintain-actions.md index eb87fdb749..4cbd102e9c 100644 --- a/content/actions/how-tos/create-and-publish-actions/release-and-maintain-actions.md +++ b/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 diff --git a/content/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations.md b/content/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations.md index d929b81f04..6548c4b827 100644 --- a/content/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations.md +++ b/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). diff --git a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds.md b/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds.md index e9fafe2ba9..7415cbdd0f 100644 --- a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds.md +++ b/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. diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases.md new file mode 100644 index 0000000000..e0c5a5c255 --- /dev/null +++ b/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). diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md index 191fd095c0..10402c12f2 100644 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md +++ b/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 --- diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/preventing-changes-to-your-releases.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/preventing-changes-to-your-releases.md new file mode 100644 index 0000000000..0e9df8a3a3 --- /dev/null +++ b/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**. diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/verifying-the-integrity-of-a-release.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/verifying-the-integrity-of-a-release.md new file mode 100644 index 0000000000..2062defa2c --- /dev/null +++ b/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 %} diff --git a/content/repositories/releasing-projects-on-github/managing-releases-in-a-repository.md b/content/repositories/releasing-projects-on-github/managing-releases-in-a-repository.md index 74311dfa2b..d623c388f6 100644 --- a/content/repositories/releasing-projects-on-github/managing-releases-in-a-repository.md +++ b/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 %} diff --git a/data/features/immutable-releases-preview.yml b/data/features/immutable-releases-preview.yml new file mode 100644 index 0000000000..50885a08f8 --- /dev/null +++ b/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' diff --git a/data/reusables/releases/immutable-releases-preview-note.md b/data/reusables/releases/immutable-releases-preview-note.md new file mode 100644 index 0000000000..9b5712d664 --- /dev/null +++ b/data/reusables/releases/immutable-releases-preview-note.md @@ -0,0 +1,2 @@ +> [!NOTE] +> Immutable releases are currently in {% data variables.release-phases.public_preview %} and subject to change.