EDI-ify artifact attestations content (#56801)

sabrowning1 · web-flow · commit 45c42cfb3417 · 2025-07-23T15:31:20.000Z
diff --git a/content/actions/concepts/security/artifact-attestations.md b/content/actions/concepts/security/artifact-attestations.md
@@ -0,0 +1,55 @@
+---
+title: Artifact attestations
+intro: 'Understand the usage and security benefits of artifact attestations.'
+shortTitle: Artifact attestations
+topics:
+  - Actions
+  - Security
+versions:
+  fpt: '*'
+  ghec: '*'
+---
+
+## Overview
+
+{% data reusables.actions.about-artifact-attestations %}
+
+## SLSA levels for artifact attestations
+
+The SLSA framework is an industry standard used to evaluate supply chain security. It is organized into levels. Each level represents an increasing degree of security and trustworthiness for a software supply chain. Artifact attestations by itself provides SLSA v1.0 Build Level 2.
+
+This provides a link between your artifact and its build instructions, but you can take this a step further by requiring builds make use of known, vetted build instructions. A great way to do this is to have your build take place in a reusable workflow that many repositories across your organization share. Reusable workflows can provide isolation between the build process and the calling workflow, to meet SLSA v1.0 Build Level 3. For more information, see [AUTOTITLE](/actions/security-guides/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3).
+
+For more information on SLSA levels, see [SLSA Security Levels](https://slsa.dev/spec/v1.0/levels).
+
+## How {% data variables.product.github %} generates artifact attestations
+
+To generate artifact attestations, {% data variables.product.prodname_dotcom %} uses Sigstore, which is an open source project that offers a comprehensive solution for signing and verifying software artifacts via attestations.
+
+**Public repositories** that generate artifact attestations use the [Sigstore Public Good Instance](https://openssf.org/blog/2023/10/03/running-sigstore-as-a-managed-service-a-tour-of-sigstores-public-good-instance/). A copy of the generated Sigstore bundle is stored with GitHub and is also written to an immutable transparency log that is publicly readable on the internet.
+
+**Private repositories** that generate artifact attestations use GitHub's Sigstore instance. GitHub's Sigstore instance uses the same codebase as the Sigstore Public Good Instance, but it does not have a transparency log and only federates with {% data variables.product.prodname_actions %}.
+
+## When to generate attestations
+
+Generating attestations alone doesn't provide any security benefit, the attestations must be verified for the benefit to be realized. Here are some guidelines for how to think about what to sign and how often:
+
+You should sign:
+
+* Software you are releasing that you expect people to run `gh attestation verify ...` on.
+* Binaries people will run, packages people will download, or manifests that include hashes of detailed contents.
+
+You should **not** sign:
+
+* Frequent builds that are just for automated testing.
+* Individual files like source code, documentation files, or embedded images.
+
+## Verifying artifact attestations
+
+If you consume software that publishes artifact attestations, you can use the {% data variables.product.prodname_cli %} to verify those attestations. Because the attestations give you information about where and how software was built, you can use that information to create and enforce security policies that elevate your supply chain security.
+
+>[!WARNING] It is important to remember that artifact attestations are _not_ a guarantee that an artifact is secure. Instead, artifact attestations link you to the source code and the build instructions that produced them. It is up to you to define your policy criteria, evaluate that policy by evaluating the content, and make an informed risk decision when you are consuming software.
+
+## Next steps
+
+To start generating and verifying artifact attestations for your builds, see [AUTOTITLE](/actions/how-tos/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds).
diff --git a/content/actions/concepts/security/index.md b/content/actions/concepts/security/index.md
@@ -10,8 +10,8 @@ children:
   - /secrets
   - /github_token
   - /openid-connect
+  - /artifact-attestations
   - /script-injections
   - /compromised-runners
   - /kubernetes-admissions-controller
 ---
-
diff --git a/content/actions/how-tos/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3.md b/content/actions/how-tos/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3.md
@@ -1,8 +1,7 @@
 ---
 title: Using artifact attestations and reusable workflows to achieve SLSA v1 Build Level 3
-shortTitle: Attest with reusable workflows
+shortTitle: Increase security rating
 intro: Building software with reusable workflows and artifact attestations can streamline your supply chain security and help you achieve SLSA v1.0 Build Level 3.
-type: quick_start
 topics:
   - Actions
   - Security
@@ -15,15 +14,10 @@ redirect_from:
   - /actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3
 ---
 
-## Introduction
-
-Artifact attestations are a great way to create unfalsifiable provenance and integrity guarantees for the software you build.
-
-But remember that by itself, artifact attestations provides links, like the build instructions an artifact was built with, which meets SLSA v1.0 Build Level 2. To make an informed risk decision, it's up to you to follow those links and evaluate those build instructions.
-
-You can take this a step further by requiring builds make use of known, vetted build instructions. A great way to do this is to have your build take place in a reusable workflow that many repositories across your organization share. Reusable workflows can provide isolation between the build process and the calling workflow, to meet SLSA v1.0 Build Level 3.
+## Prerequisites
 
 Before starting this guide, you should be familiar with:
+* The usage and security benefits of artifact attestations. See [AUTOTITLE](/actions/concepts/security/artifact-attestations).
 * Generating artifact attestations. See [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
 * Writing and using reusable workflows. See [AUTOTITLE](/actions/using-workflows/reusing-workflows).
 
@@ -33,11 +27,11 @@ First, we need to build with both artifact attestations and a reusable workflow.
 
 ### Building with a reusable workflow
 
-If you aren't already using reusable workflows to build your software, you'll need to take your build steps and move them into a reusable workflow. For more information on how to write and call a reusable workflow, see [AUTOTITLE](/actions/using-workflows/reusing-workflows).
+If you aren't already using reusable workflows to build your software, you'll need to take your build steps and move them into a reusable workflow.
 
 ### Building with artifact attestations
 
-The reusable workflow you use to build your software must also generate artifact attestations to establish build provenance. For more information, see [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
+The reusable workflow you use to build your software must also generate artifact attestations to establish build provenance.
 
 When you use a reusable workflow to generate artifact attestations, both the calling workflow and the reusable workflow need to have the following permissions.
 
@@ -75,7 +69,3 @@ Or if you want to specify the exact workflow:
 ```bash copy
 gh attestation verify -o ORGANIZATION_NAME --signer-workflow REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME/.github/workflows/reusable.yml PATH/TO/YOUR/BUILD/ARTIFACT-BINARY
 ```
-
-## Conclusion
-
-You are now building and signing your artifacts in a reusable workflow, which can provide the isolation required by SLSA v1.0 Build Level 3. You can verify artifacts are built with known, vetted build instructions by requiring your artifact was built with a specific workflow, reusable or not.
diff --git a/content/actions/how-tos/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds.md b/content/actions/how-tos/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds.md
@@ -5,51 +5,15 @@ product: '{% data reusables.gated-features.attestations %}'
 versions:
   fpt: '*'
   ghec: '*'
-shortTitle: Artifact attestations
+shortTitle: Use artifact attestations
 redirect_from:
   - /actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds
   - /actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds
 ---
 
-## About artifact attestations
+## Prerequisites
 
-{% data reusables.actions.about-artifact-attestations %}
-
-### About SLSA levels for artifact attestations
-
-The SLSA framework is an industry standard used to evaluate supply chain security. It is organized into levels. Each level represents an increasing degree of security and trustworthiness for a software supply chain. Artifact attestations by itself provides SLSA v1.0 Build Level 2.
-
-This provides a link between your artifact and its build instructions, but you can take this a step further by requiring builds make use of known, vetted build instructions. A great way to do this is to have your build take place in a reusable workflow that many repositories across your organization share. Reusable workflows can provide isolation between the build process and the calling workflow, to meet SLSA v1.0 Build Level 3. For more information, see [AUTOTITLE](/actions/security-guides/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3).
-
-For more information on SLSA levels, see [SLSA Security Levels](https://slsa.dev/spec/v1.0/levels).
-
-### About using Sigstore for artifact attestations
-
-To generate artifact attestations, {% data variables.product.prodname_dotcom %} uses Sigstore, which is an open source project that offers a comprehensive solution for signing and verifying software artifacts via attestations.
-
-**Public repositories** that generate artifact attestations use the [Sigstore Public Good Instance](https://openssf.org/blog/2023/10/03/running-sigstore-as-a-managed-service-a-tour-of-sigstores-public-good-instance/). A copy of the generated Sigstore bundle is stored with GitHub and is also written to an immutable transparency log that is publicly readable on the internet.
-
-**Private repositories** that generate artifact attestations use GitHub's Sigstore instance. GitHub's Sigstore instance uses the same codebase as the Sigstore Public Good Instance, but it does not have a transparency log and only federates with {% data variables.product.prodname_actions %}.
-
-### What to attest
-
-Generating attestations alone doesn't provide any security benefit, the attestations must be verified for the benefit to be realized. Here are some guidelines for how to think about what to sign and how often:
-
-You should sign:
-
-* Software you are releasing that you expect people to run `gh attestation verify ...` on.
-* Binaries people will run, packages people will download, or manifests that include hashes of detailed contents.
-
-You should **not** sign:
-
-* Frequent builds that are just for automated testing.
-* Individual files like source code, documentation files, or embedded images.
-
-### About verifying artifact attestations
-
-If you consume software that publishes artifact attestations, you can use the {% data variables.product.prodname_cli %} to verify those attestations. Because the attestations give you information about where and how software was built, you can use that information to create and enforce security policies that elevate your supply chain security. For more information, see [Verifying artifact attestations with the {% data variables.product.prodname_cli %}](#verifying-artifact-attestations-with-the-github-cli).
-
->[!WARNING]It is important to remember that artifact attestations are _not_ a guarantee that an artifact is secure. Instead, artifact attestations link you to the source code and the build instructions that produced them. It is up to you to define your policy criteria, evaluate that policy by evaluating the content, and make an informed risk decision when you are consuming software.
+Before you start generating artifact attestations, you need to understand what they are and when you should use them. See [AUTOTITLE](/actions/concepts/security/artifact-attestations).
 
 ## Generating artifact attestations for your builds
 
@@ -222,8 +186,6 @@ gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
   --jq '.[].verificationResult.statement.predicate'
 ```
 
-## Managing the lifecycle of attestations
-
-{% data reusables.actions.lifecycle-of-attestations %}
+## Next steps
 
-To find and delete attestations, see [AUTOTITLE](/actions/how-tos/security-for-github-actions/using-artifact-attestations/managing-the-lifecycle-of-artifact-attestations).
+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).
diff --git a/content/actions/how-tos/security-for-github-actions/using-artifact-attestations/verifying-attestations-offline.md b/content/actions/how-tos/security-for-github-actions/using-artifact-attestations/verifying-attestations-offline.md
@@ -1,8 +1,7 @@
 ---
 title: Verifying attestations offline
-shortTitle: Verifying attestations offline
+shortTitle: Verify attestations offline
 intro: Artifact attestations can be verified without an internet connection.
-type: quick_start
 topics:
   - Actions
   - Security
@@ -15,15 +14,9 @@ redirect_from:
   - /actions/security-for-github-actions/using-artifact-attestations/verifying-attestations-offline
 ---
 
-## Introduction
+## Prerequisites
 
-Artifact attestations are a great way to create unfalsifiable provenance and integrity guarantees for the software you build.
-
-By default, attestations are stored in GitHub's attestation API, which `gh attestation verify` will query when you go to verify your attestation. That command will also contact GitHub's servers to check for updated key material to use to verify the attestation.
-
-This command can work without internet connectivity, but you need to supply the attestation bundle and the key material in the trusted root manually.
-
-Before starting this guide, you should be building with generating artifact attestations. See [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
+Before starting this guide, you should be generating artifact attestations for your builds. See [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
 
 ## Step 1: Download attestation bundle
 
@@ -75,7 +68,3 @@ You can then perform offline verification with the following command:
 ```bash copy
 gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME --bundle sha256:ae57936def59bc4c75edd3a837d89bcefc6d3a5e31d55a6fa7a71624f92c3c3b.jsonl --custom-trusted-root trusted_root.jsonl
 ```
-
-## Conclusion
-
-You are now verifying artifact attestations in an offline environment. We recommend importing a new trusted root whenever you are introducing new signed artifacts to your offline environment.
diff --git a/data/reusables/actions/about-artifact-attestations.md b/data/reusables/actions/about-artifact-attestations.md
@@ -2,8 +2,8 @@ Artifact attestations enable you to create unfalsifiable provenance and integrit
 
 When you generate artifact attestations with your software, you create cryptographically signed claims that establish your build's provenance and include the following information:
 
-* A link to the workflow associated with the artifact.
-* The repository, organization, environment, commit SHA, and triggering event for the artifact.
+* A link to the workflow associated with the artifact
+* The repository, organization, environment, commit SHA, and triggering event for the artifact
 * Other information from the OIDC token used to establish provenance. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect).
 
 You can also generate artifact attestations that include an associated software bill of materials (SBOM). Associating your builds with a list of the open source dependencies used in them provides transparency and enables consumers to comply with data protection standards.
