Updates to dependency graph documentation with information about recent changes (#55449)

Co-authored-by: Lewis Jones <[email protected]>
Co-authored-by: Felicity Chapman <[email protected]>
Co-authored-by: mc <[email protected]>

Author: 4 people

content/code-security/dependabot/maintain-dependencies/best-practices-for-maintaining-dependencies.md

@@ -79,7 +79,7 @@ By following these practices, you can significantly reduce the risk posed by out
 
 {% data variables.product.github %} offers several security features that can help maintain the security of your codebases:
 
-**Dependency Graph**
+**Dependency graph**
 
    * Provides a tabular representation of your project's dependencies.
    * The graph helps you understand the dependencies of your project and {% data variables.product.github %} uses this to identify vulnerable dependencies.

content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository.md

@@ -85,6 +85,8 @@ Automatic dependency submission makes a best effort to cache package downloads b
 
 If your repository's dependencies seem inaccurate, check that the timestamp of the last dependency graph build matches the last change to your `pom.xml` file. The timestamp is visible on the table of alerts in the repository's {% data variables.product.prodname_dependabot_alerts %} tab. Pushing a commit which updates `pom.xml` will trigger a new run of the Dependency Tree Submission action and force a rebuild of that repository's dependency graph.
 
+{% data reusables.dependency-graph.deduplication %}
+
 ## Further reading
 
 * [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security)

content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph.md

@@ -45,10 +45,6 @@ To generate a dependency graph, {% data variables.product.github %} needs read-o
 
 When the dependency graph is first enabled, any manifest and lock files for supported ecosystems are parsed immediately. The graph is usually populated within minutes but this may take longer for repositories with many dependencies. Once enabled, the graph is automatically updated with every push to the repository{% ifversion fpt or ghec %} and every push to other repositories in the graph{% endif %}.
 
-{% ifversion ghes %}
-{% data reusables.dependency-submission.dependency-submission-link %}
-{% endif %}
-
 ## Further reading
 
 {%- ifversion maven-transitive-dependencies %}

content/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems.md

@@ -20,11 +20,11 @@ versions:
 
 {% data reusables.dependabot.about-the-dependency-graph %} For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).
 
-In this article, you can see what the supported ecosystems are.
-
 ## Supported package ecosystems
 
-The recommended formats explicitly define which versions are used for all direct and all indirect dependencies. If you use these formats, your dependency graph is more accurate. It also reflects the current build set up and enables the dependency graph to report vulnerabilities in both direct and indirect dependencies.{% ifversion fpt or ghec %} Indirect dependencies that are inferred from a manifest file (or equivalent) are excluded from the checks for insecure dependencies.{% endif %}
+If dependency graph is enabled, it will scan your repository for manifest files used by many commonly-used programming language package ecosystems. When it finds one of the supported manifest files, it will parse the file's contents and build a representation of its contents, including each package's name and version.
+
+Some files explicitly define which versions are used for all direct and all indirect dependencies. They lock the package versions to those included in the build and enable Dependabot to find vulnerable versions in both direct and indirect dependencies. If you use these formats, your dependency graph is more accurate, so they're listed under the "Recommended files" column in this table.{% ifversion fpt or ghec %} Indirect dependencies that are inferred from a manifest file (or equivalent) are excluded from the checks for insecure dependencies.{% endif %}
 
 {% data reusables.dependency-graph.supported-package-ecosystems %}
 
@@ -36,7 +36,7 @@ For ecosystems that resolve transitive dependencies at build-time, we recommend
 
 ## Package ecosystems supported via dependency submission actions
 
-You can use the {% data variables.dependency-submission-api.name %} to add build-time dependencies to the dependency graph, or to add dependencies from package managers and ecosystems of your choice to the dependency graph, even if the ecosystem is not in the supported ecosystem list above. Dependency information from these submitted dependencies will, in turn, flow into {% data variables.product.prodname_dependabot_updates %} and {% data variables.product.prodname_dependabot_alerts %}.
+In addition to dependency graph's static analysis and auto-submission, you can use the {% data variables.dependency-submission-api.name %} to add build-time dependencies to the dependency graph, or to add dependencies from package managers and ecosystems of your choice to the dependency graph, even if the ecosystem is not in the supported ecosystem list above. Dependency information from these submitted dependencies will, in turn, flow into {% data variables.product.prodname_dependabot_updates %} and {% data variables.product.prodname_dependabot_alerts %}.
 
 {% data reusables.dependency-graph.dependency-submission-API-short %} For more information on the {% data variables.dependency-submission-api.name %}, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api).
 
@@ -45,3 +45,7 @@ You typically use the {% data variables.dependency-submission-api.name %} in a {
 {% data reusables.dependency-submission.premade-action-table %}
 
 You can also create your own action. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api#creating-your-own-action).
+
+## Deduplication of manifests
+
+{% data reusables.dependency-graph.deduplication %}

content/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization.md

@@ -22,7 +22,7 @@ permissions: '{% data reusables.permissions.dependency-graph-view-org-insights %
 Dependency insights can help you track, report, and act on your organization's open source usage.
 
 > [!NOTE]
-> Please make sure you have enabled the [Dependency Graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph).
+> Please make sure you have enabled the [dependency graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph).
 
 With dependency insights you can view vulnerabilities, licenses, and other important information for the open source projects your organization depends on.
 

content/rest/dependency-graph/dependency-submission.md

@@ -18,4 +18,6 @@ You can submit dependencies in the form of a snapshot. A snapshot is a set of de
 
 You can submit multiple sets of dependencies to be included in your dependency graph. The REST API uses the `job.correlator` property and the `detector.name` category of the snapshot to ensure the latest submissions for each workflow get shown. The `correlator` property itself is the primary field you will use to keep independent submissions distinct. An example `correlator` could be a simple combination of two variables available in actions runs: `<GITHUB_WORKFLOW> <GITHUB_JOB>`.
 
+{% data reusables.dependency-graph.deduplication %}
+
 <!-- Content after this section is automatically generated -->

data/reusables/dependabot/pull-request-security-vs-version-updates.md

@@ -1,4 +1,4 @@
 When {% data variables.product.prodname_dependabot %} raises pull requests, these pull requests could be for _security_ or _version_ updates:
 
 * _{% data variables.product.prodname_dependabot_security_updates %}_ are automated pull requests that help you update dependencies with known vulnerabilities.
-* _{% data variables.product.prodname_dependabot_version_updates %}_ are automated pull requests that keep your dependencies updated, even when they don’t have any vulnerabilities. To check the status of version updates, navigate to the Insights tab of your repository, then Dependency Graph, and {% data variables.product.prodname_dependabot %}.
+* _{% data variables.product.prodname_dependabot_version_updates %}_ are automated pull requests that keep your dependencies updated, even when they don’t have any vulnerabilities. To check the status of version updates, navigate to the **Insights** tab of your repository, then select **Dependency Graph**, and {% data variables.product.prodname_dependabot %}.

data/reusables/dependency-graph/deduplication.md

@@ -0,0 +1,9 @@
+Dependency graph can learn about dependencies in three different ways: static analysis, automatic submission, and user submission. A repository can have multiple methods configured, causing the same package manifest to be scanned multiple times, potentially with different outputs from each scan. Dependency graph uses deduplication logic to parse the outputs, prioritizing the most accurate information for each manifest file.
+
+Dependency graph displays only one instance of each manifest file using the following precedence rules.
+
+1. **User submissions** take the highest priority, because they are usually created during artifact builds they have the most complete information.
+   * If there are multiple manual snapshots from different detectors, they are sorted alphabetically by correlator and the first one used.
+   * If there are two correlators with the same detector, the resolved dependencies are merged. For more information about correlators and detectors, see [AUTOTITLE](/rest/dependency-graph/dependency-submission).
+1. **Automatic submissions** have the second-highest priority since they are also created during artifact builds, but are not submitted by users.
+1. **Static analysis results** are used when no other data is available.

data/reusables/dependency-graph/supported-package-ecosystems.md

@@ -1,22 +1,22 @@
-| Package manager | Languages | Transitive dependencies | Recommended formats | All supported formats |
+| Package manager | Languages | Transitive dependencies | Recommended files | Additional files |
 | --- | --- | --- | --- | ---|
-| Cargo | Rust | {% octicon "x" aria-label="Not supported" %} | `Cargo.lock` | `Cargo.toml`, `Cargo.lock` |
-| Composer             | PHP           | {% octicon "x" aria-label="Not supported" %} | `composer.lock` | `composer.json`, `composer.lock` |
-| NuGet | .NET languages (C#, F#, VB), C++  | {% octicon "x" aria-label="Not supported" %} |  `.csproj`, `.vbproj`, `.nuspec`, `.vcxproj`, `.fsproj` |  `.csproj`, `.vbproj`, `.nuspec`, `.vcxproj`, `.fsproj`, `packages.config` |
-| {% data variables.product.prodname_actions %} workflows | YAML | {% octicon "x" aria-label="Not supported" %} | `.yml`, `.yaml` | `.yml`, `.yaml` |
-| Go modules | Go | {% octicon "x" aria-label="Not supported" %} | `go.mod`| `go.mod` |
-| Maven | Java, Scala | {% octicon "check" aria-label="Supported" %} |  `pom.xml`  | `pom.xml`  |
-| npm | JavaScript | {% octicon "check" aria-label="Supported" %} |          `package-lock.json` | `package-lock.json`, `package.json`|
-| pip             | Python                    | {% octicon "x" aria-label="Not supported" %} | `requirements.txt`, `pipfile.lock` | `requirements.txt`, `pipfile`, `pipfile.lock`, `setup.py` |
-| pnpm             | JavaScript                    | {% octicon "x" aria-label="Not supported" %} | `pnpm-lock.yaml` | `package.json`, `pnpm-lock.yaml` |
-| pub             | Dart                    | {% octicon "x" aria-label="Not supported" %} | `pubspec.lock` | `pubspec.yaml`, `pubspec.lock` |
-| Python Poetry | Python                    | {% octicon "x" aria-label="Not supported" %} | `poetry.lock` | `poetry.lock`, `pyproject.toml` |
-| RubyGems             | Ruby           | {% octicon "x" aria-label="Not supported" %} | `Gemfile.lock` | `Gemfile.lock`, `Gemfile`, `*.gemspec` |
-| Swift Package Manager | Swift | {% octicon "x" aria-label="Not supported" %} | `Package.resolved` | `Package.resolved` |
-| Yarn | JavaScript | {% octicon "x" aria-label="Not supported" %} | `yarn.lock` | `package.json`, `yarn.lock` |
+| Cargo | Rust | {% octicon "x" aria-label="Not supported" %} | `Cargo.lock` | `Cargo.toml` |
+| Composer             | PHP           | {% octicon "x" aria-label="Not supported" %} | `composer.lock` | `composer.json` |
+| NuGet | .NET languages (C#, F#, VB), C++  | {% octicon "x" aria-label="Not supported" %} |  `.csproj`, `.vbproj`, `.nuspec`, `.vcxproj`, `.fsproj` | `packages.config` |
+| {% data variables.product.prodname_actions %} workflows | YAML | {% octicon "x" aria-label="Not supported" %} | `.yml`, `.yaml` | {% octicon "x" aria-label="None" %} |
+| Go modules | Go | {% octicon "x" aria-label="Not supported" %} | `go.mod`| {% octicon "x" aria-label="None" %} |
+| Maven | Java, Scala | {% octicon "check" aria-label="Supported" %} |  `pom.xml`  | {% octicon "x" aria-label="None" %}  |
+| npm | JavaScript | {% octicon "check" aria-label="Supported" %} |          `package-lock.json` | `package.json`|
+| pip             | Python                    | {% octicon "x" aria-label="Not supported" %} | `requirements.txt`, `pipfile.lock` | `pipfile`, `setup.py` |
+| pnpm             | JavaScript                    | {% octicon "check" aria-label="Supported" %} | `pnpm-lock.yaml` | `package.json` |
+| pub             | Dart                    | {% octicon "x" aria-label="Not supported" %} | `pubspec.lock` | `pubspec.yaml` |
+| Python Poetry | Python                    | {% octicon "x" aria-label="Not supported" %} | `poetry.lock` | `pyproject.toml` |
+| RubyGems             | Ruby           | {% octicon "x" aria-label="Not supported" %} | `Gemfile.lock` | `Gemfile`, `*.gemspec` |
+| Swift Package Manager | Swift | {% octicon "x" aria-label="Not supported" %} | `Package.resolved` | {% octicon "x" aria-label="None" %} |
+| Yarn | JavaScript | {% octicon "check" aria-label="Supported" %} | `yarn.lock` | `package.json` |
 
 > [!NOTE]{% ifversion transitive-dependency-labeling-npm %}
-> * The **Transitive dependencies** column indicates whether the dependency graph labels dependent packages in that ecosystem as direct or transitive on the dependency graph view, {% data variables.product.prodname_dependabot_alerts %}, the GraphQL API, and exported SBOMs. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#dependencies-view).{% endif %}
+> * The **Transitive dependencies** column indicates whether static analysis will add `direct` and `transitive` labels for dependent packages in that ecosystem. Labels will appear on the dependency graph view, {% data variables.product.prodname_dependabot_alerts %}, the GraphQL API, and exported SBOMs. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#dependencies-view).{% endif %}
 > * If you list your Python dependencies within a `setup.py` file, we may not be able to parse and list every dependency in your project.
 > * {% data variables.product.prodname_actions %} workflows must be located in the `.github/workflows/` directory of a repository to be recognized as manifests. Any actions or workflows referenced using the syntax `jobs[*].steps[*].uses` or `jobs.<job_id>.uses` will be parsed as dependencies. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions).
 > * {% data reusables.dependabot.dependabot-alert-actions-semver %} For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) and [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates).