"Linked artifacts" for organizations [GA] (#59099)

Co-authored-by: Meredith Lancaster <malancas@users.noreply.github.com>
Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com>

Author: 3 people

assets/images/help/security/virtual-registry-decommissioned.png

@@ -128,6 +128,12 @@ For guidance on writing deployment-specific steps, see [Finding deployment examp
 
 When a {% data variables.product.prodname_actions %} workflow deploys to an environment, the environment is displayed on the main page of the repository. For more information about viewing deployments to environments, see [AUTOTITLE](/actions/deployment/managing-your-deployments/viewing-deployment-history).
 
+{% ifversion virtual-registry %}
+
+Your organization can collect deployment records for all your builds in a single place by uploading data to the {% data variables.product.virtual_registry %}. See [AUTOTITLE](/code-security/concepts/supply-chain-security/linked-artifacts).
+
+{% endif %}
+
 ## Monitoring workflow runs
 
 Every workflow run generates a real-time graph that illustrates the run progress. You can use this graph to monitor and debug deployments. For more information see, [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-the-visualization-graph).

assets/images/help/security/virtual-registry-deleted.png

@@ -141,6 +141,14 @@ When you run your updated workflows, they will build your artifacts and generate
 
    The value of the `sbom-path` parameter should be set to the path to the JSON-formatted SBOM file you want to attest.
 
+## Uploading artifacts to the {% data variables.product.virtual_registry %}
+
+We recommend uploading attested assets to your organization's {% data variables.product.virtual_registry %}. This page displays artifacts' build history, deployment records, and storage details. You can use this data to prioritize security alerts or quickly connect vulnerable artifacts to their owning team, source code, and build run. For more information, see [AUTOTITLE](/code-security/concepts/supply-chain-security/linked-artifacts).
+
+{% data reusables.actions.attestation-virtual-registry %}
+
+For an example workflow, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts#generating-an-attestation).
+
 ## Verifying artifact attestations with the {% data variables.product.prodname_cli %}
 
 You can validate artifact attestations for binaries and container images and validate SBOM attestations using the {% data variables.product.prodname_cli %}. For more information, see the [`attestation`](https://cli.github.com/manual/gh_attestation) section of the {% data variables.product.prodname_cli %} manual.

assets/images/help/security/virtual-registry-deployment-record.png

@@ -39,10 +39,14 @@ The supply chain features on {% data variables.product.github %} are:
 * **{% data variables.product.prodname_dependabot_updates %}**
   * **{% data variables.product.prodname_dependabot_security_updates %}**
   * **{% data variables.product.prodname_dependabot_version_updates %}**
+{%- ifversion fpt or ghec %}
+* **Immutable releases**
+* **Artifact attestations**
+{%- endif %}
 
 The dependency graph is central to supply chain security. The dependency graph identifies all upstream dependencies and public downstream dependents of a repository or package. Your repository’s dependency graph tracks and displays its dependencies and some of their properties, like vulnerability information.
 
-Other supply chain features on {% data variables.product.prodname_dotcom %} rely on the information provided by the dependency graph.
+The following supply chain features on {% data variables.product.prodname_dotcom %} rely on the information provided by the dependency graph.
 
 * Dependency review uses the dependency graph to identify dependency changes and help you understand the security impact of these changes when you review pull requests.
 * {% data variables.product.prodname_dependabot %} cross-references dependency data provided by the dependency graph with the list of advisories published in the {% data variables.product.prodname_advisory_database %}, scans your dependencies and generates {% data variables.product.prodname_dependabot_alerts %} when a potential vulnerability is detected.
@@ -136,6 +140,20 @@ There are two types of {% data variables.product.prodname_dependabot_updates %}:
 
 For more information about {% data variables.product.prodname_dependabot_updates %}, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) and [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates).
 
+### What are immutable releases?
+
+Repositories can enable immutable releases to prevent the assets and associated Git tag of a release from being changed after publication. This reduces the risk of supply chain attacks by preventing attackers from injecting vulnerabilities into releases you consume. It also means projects that rely on specific releases are less likely to break.
+
+Creating an immutable release automatically generates an attestation for the release. You can use this attestation to make sure the release and its artifacts match the published information.
+
+### What are artifact attestations?
+
+Software providers can generate attestations for software built with {% data variables.product.prodname_actions %}. Attestations are cryptographically signed claims that establish the build's provenance (the source code and workflow run used to build it) or associated software bill of materials (SBOM).
+
+You can increase supply chain security by verifying attestations for your dependencies. Although attestations do not guarantee security, they give you information about where and how software was built, so you can be more confident that your dependencies haven't been tampered with. You can gate deployments using a tool like the Kubernetes admissions controller to prevent unattested builds from being deployed.
+
+When you use {% data variables.product.prodname_actions %} to generate attestations for your organization's own builds, the built artifacts are automatically uploaded to the {% data variables.product.virtual_registry %}. This platform allows you to view the storage and deployment records of all linked artifacts, so you can find the source code and workflow run used to build an artifact or filter security alerts based on deployment context.
+
 ## Feature availability
 
 {% ifversion fpt or ghec %}
@@ -145,17 +163,19 @@ Public repositories:
 * **Dependency review:** Enabled by default and cannot be disabled.
 * **{% data variables.product.prodname_dependabot_alerts %}:** Not enabled by default. {% data variables.product.prodname_dotcom %} detects insecure dependencies and displays information in the dependency graph, but does not generate {% data variables.product.prodname_dependabot_alerts %} by default. Repository owners or people with admin access can enable {% data variables.product.prodname_dependabot_alerts %}.
   You can also enable or disable Dependabot alerts for all repositories owned by your user account or organization. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-security-and-analysis-settings-for-your-personal-account) or [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization).
+* **Artifact attestations:** Available in all public repositories, but you must explicitly generate attestations in your build workflows. See [AUTOTITLE](/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations).
 
 Private repositories:
 * **Dependency graph:** Not enabled by default. The feature can be enabled by repository administrators. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph).
 * **Dependency review:** Available in private repositories owned by organizations that use {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %} and have a license for {% data variables.product.prodname_GHAS_or_code_security %}. For more information, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security) and [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph).
-
 * **{% data variables.product.prodname_dependabot_alerts %}:** Not enabled by default. Owners of private repositories, or people with admin access, can enable {% data variables.product.prodname_dependabot_alerts %} by enabling the dependency graph and {% data variables.product.prodname_dependabot_alerts %} for their repositories.
   You can also enable or disable Dependabot alerts for all repositories owned by your user account or organization. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-security-and-analysis-settings-for-your-personal-account) or [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization).
+* **Artifact attestations:** Only available in private repositories on {% data variables.product.prodname_ghe_cloud %}.
 
 Any repository type:
 * **{% data variables.product.prodname_dependabot_security_updates %}:** Not enabled by default. You can enable {% data variables.product.prodname_dependabot_security_updates %} for any repository that uses {% data variables.product.prodname_dependabot_alerts %} and the dependency graph. For information about enabling security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates).
 * **{% data variables.product.prodname_dependabot_version_updates %}:** Not enabled by default. People with write permissions to a repository can enable {% data variables.product.prodname_dependabot_version_updates %}. For information about enabling version updates, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates).
+* **Immutable releases*:** Not enabled by default. You can enable release immutability for a repository or organization. See [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/preventing-changes-to-your-releases).
 {% endif %}
 
 {% ifversion ghes %}

assets/images/help/security/virtual-registry-storage-record.png

@@ -19,4 +19,5 @@ children:
   - about-dependabot-auto-triage-rules
   - about-dependabot-on-github-actions-runners
   - immutable-releases
+  - linked-artifacts
 ---

content/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments.md

@@ -0,0 +1,71 @@
+---
+title: About linked artifacts
+intro: "The {% data variables.product.virtual_registry %} helps you audit and prioritize your organization's builds on {% data variables.product.github %}, regardless of where the artifacts are stored."
+versions:
+  feature: virtual-registry
+shortTitle: 'Linked artifacts'
+topics:
+  - Vulnerabilities
+  - Dependencies
+contentType: concepts
+---
+
+The {% data variables.product.virtual_registry %} provides a unified view of software artifacts that your organization builds with {% data variables.product.prodname_actions %}, such as container images, packages, or builds of your production code.
+
+The page shows you how an artifact was built, where it is stored or running, and which compliance and security metadata is associated with the artifact.
+
+Teams in your organization can use the {% data variables.product.virtual_registry %} to:
+
+* Prioritize alerts from {% data variables.product.prodname_GHAS %} features based on whether the detected vulnerabilities are running in production or exposed to the internet
+* Quickly connect artifacts to build details, storage locations, and owning teams
+* Meet compliance by exporting auditable proof of your artifacts' provenance and integrity
+
+## Which artifacts appear on the {% data variables.product.virtual_registry %}?
+
+The {% data variables.product.virtual_registry %} is unique to each organization. It contains metadata for artifacts that have been built with {% data variables.product.prodname_actions %} in your organization's repositories. It does **not** display artifacts your organization consumes from elsewhere, such as open source dependencies.
+
+Artifact records are uploaded by your organization using either a public API or an integration with an external registry. The {% data variables.product.virtual_registry %} does not store the artifact files themselves. It just provides an authoritative source for the metadata associated with each artifact.
+
+Because an artifact does not need to be stored on {% data variables.product.github %} to appear in the {% data variables.product.virtual_registry %}, you can use the {% data variables.product.virtual_registry %} alongside your preferred package registry, such as JFrog Artifactory or {% data variables.product.prodname_registry %}.
+
+## Which metadata is included?
+
+The {% data variables.product.virtual_registry %} combines data from two different types of record: storage records and deployment records. These records are uploaded using different API endpoints or integrations.
+
+### Storage records
+
+Storage records include the repository containing the artifact's source code, the registry where the artifact is stored, and any attestations proving the artifact's integrity and provenance. You can use this data to quickly find an artifact's owning team and build details.
+
+![Screenshot of an artifact page. Highlighted fields: storage registry, artifact repository, source repository.](/assets/images/help/security/virtual-registry-storage-record.png)
+
+For more information about attestations and SLSA levels, see [AUTOTITLE](/actions/concepts/security/artifact-attestations).
+
+### Deployment records
+
+Deployment records include the environment where the artifact is deployed and any runtime risks (such as "sensitive data" or "internet exposed") associated with the artifact. You can use this data to filter security alerts based on the level of threat posed to your organization and consumers.
+
+![Screenshot of an artifact page. Highlighted fields: the "Deployments" list, including tags for "Prod", "sensitive data", and "pacific-east".](/assets/images/help/security/virtual-registry-deployment-record.png)
+
+>[!NOTE] Deployment records do **not** include deployment activity from a repository's deployments dashboard, which comes from a different source. See [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/viewing-deployment-activity-for-your-repository).
+
+## How does the {% data variables.product.virtual_registry %} fit into my processes?
+
+This example workflow shows how the {% data variables.product.virtual_registry %} integrates with other {% data variables.product.github %} features and external systems.
+
+1. A developer commits code to a {% data variables.product.github %} repository where the code for a software package is defined.
+1. A {% data variables.product.prodname_actions %} workflow in the repository automatically:
+
+   1. Builds the package.
+   1. Pushes the package to your chosen registry, such as {% data variables.product.prodname_registry %} or JFrog Artifactory.
+   1. Creates a cryptographically signed provenance attestation, linking the package to the repository, commit, and workflow used to build the package.
+   1. Deploys the package to a staging or production environment. Your deployment system may be gated to ensure that only attested artifacts can be deployed to production, for example using the Kubernetes Admissions Controller.
+
+1. Metadata for the package, such as its linked repository, attestations, and deployment history, is uploaded to the {% data variables.product.virtual_registry %}.
+1. Using the data from the {% data variables.product.virtual_registry %}, a security lead triages code scanning and Dependabot alerts, and creates a campaign to address alerts that affect production environments or have a specific runtime risk.
+1. When an audit is required, a member of the compliance team exports SBOMs, provenance details, and deployment records for all your organization's linked artifacts from a single source.
+
+## Next steps
+
+To add records to your organization's {% data variables.product.virtual_registry %}, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts).
+
+To view the {% data variables.product.virtual_registry %} for your organization, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/view-linked-artifacts).

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

@@ -10,5 +10,8 @@ contentType: how-tos
 children:
   - /preventing-changes-to-your-releases
   - /exporting-a-software-bill-of-materials-for-your-repository
+  - /upload-linked-artifacts
+  - /view-linked-artifacts
+  - /remove-linked-artifacts
 ---