[EDI] How the dependency graph recognizes dependencies (#59506)

Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com>
Co-authored-by: Eric Sorenson <ahpook@github.com>

Author: 3 people

content/code-security/concepts/supply-chain-security/about-the-dependency-graph.md

@@ -23,14 +23,14 @@ contentType: concepts
 
 {% data reusables.dependabot.about-the-dependency-graph %}
 
-When you push a commit to {% data variables.product.github %} that changes or adds a supported manifest or lock file to the default branch, the dependency graph is automatically updated.{% ifversion fpt or ghec %} In addition, the graph is updated when anyone pushes a change to the repository of one of your dependencies.{% endif %}
-
 For information on the supported ecosystems and manifest files, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#supported-package-ecosystems).
 
-{% data reusables.dependency-submission.dependency-submission-link %}
-
 When you create a pull request containing changes to dependencies that targets the default branch, {% data variables.product.prodname_dotcom %} uses the dependency graph to add dependency reviews to the pull request. These indicate whether the dependencies contain vulnerabilities and, if so, the version of the dependency in which the vulnerability was fixed. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review).
 
+## How the dependency graph is built
+
+The dependency graph automatically parses dependencies by analyzing manifests and lock files in your repository. You can also submit data yourself. For more information, see [AUTOTITLE](/code-security/concepts/supply-chain-security/dependency-graph-data).
+
 ## Dependency graph availability
 
 {% ifversion fpt or ghec %}
@@ -45,17 +45,6 @@ When you create a pull request containing changes to dependencies that targets t
 {% ifversion ghes %}
 For more information about configuration of the dependency graph, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph).{% endif %}
 
-## Dependencies included
-
-The dependency graph includes all the dependencies of a repository that are detailed in the manifest and lock files, or their equivalent, for supported ecosystems, as well as any dependencies that are submitted using the {% data variables.dependency-submission-api.name %}. This includes:
-
-* Direct dependencies, that are explicitly defined in a manifest or lock file or have been submitted using the {% data variables.dependency-submission-api.name %}
-* Indirect dependencies of these direct dependencies, also known as transitive dependencies or sub-dependencies
-
-The dependency graph identifies indirect dependencies{% ifversion fpt or ghec %} only if they are defined in a lock file or have been submitted using the {% data variables.dependency-submission-api.name %}. For the most reliable graph, you should use lock files (or their equivalent) because they define exactly which versions of the direct and indirect dependencies you currently use. If you use lock files, you also ensure that all contributors to the repository are using the same versions, which will make it easier for you to test and debug code{% else %} from the lock files{% endif %}. If your ecosystem does not have lock files, you can use pre-made actions that resolve transitive dependencies for many ecosystems. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api#using-pre-made-actions).
-
-For more information on how {% data variables.product.github %} helps you understand the dependencies in your environment, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security).
-
 {% ifversion fpt or ghec %}
 
 ## Dependents and "used by" data

content/code-security/concepts/supply-chain-security/dependency-graph-data.md

@@ -0,0 +1,82 @@
+---
+title: How the dependency graph recognizes dependencies
+intro: 'The dependency graph automatically analyzes manifest files. You can submit data for dependencies that cannot be detected automatically.'
+product: '{% data reusables.gated-features.dependency-graph %}'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+topics:
+  - Dependency graph
+  - Dependencies
+  - Repositories
+shortTitle: Dependency graph data
+contentType: concepts
+---
+
+The dependency graph can identify your project's dependencies using the following methods.
+
+| Method | How it works |
+| ------ | ------------ |
+| **Static analysis** | Parses manifest and lock files in your repository |
+| {% ifversion fpt or ghec %} |
+| **{% data variables.product.prodname_dependabot %} graph jobs** | Uses a {% data variables.product.prodname_dependabot %} {% data variables.product.prodname_actions %} workflow to generate dependency snapshots |
+| {% endif %} |
+| {% ifversion maven-transitive-dependencies %} |
+| **Automatic submission** | Runs a built-in {% data variables.product.prodname_actions %} workflow to resolve build-time dependencies |
+| {% endif %}
+| **{% data variables.dependency-submission-api.name_caps %}** | Accepts dependency data you submit programmatically |
+
+Once dependencies are in the graph, you can receive {% data variables.product.prodname_dependabot_alerts %} and {% data variables.product.prodname_dependabot_security_updates %} for any known vulnerabilities.
+
+## Static analysis
+
+When you enable the dependency graph, {% data variables.product.github %} scans your repository for supported manifest files and parses each package's name and version. The graph updates when you change a supported manifest or lock file on your default branch{% ifversion fpt or ghec %}, or when a dependency changes in its own repository{% endif %}.
+
+Static analysis can identify:
+
+* **Direct dependencies** explicitly defined in a manifest or lock file
+* **Indirect dependencies**—dependencies of these direct dependencies, also called "transitive dependencies"—but only if they are defined in a manifest or lock file, not if they are resolved at build time
+
+For the most reliable graph, you should use lock files (or their equivalent), because they define exactly which versions of the direct and indirect dependencies you currently use. Lock files also ensure that all contributors to the repository are using the same versions, which will make it easier for you to test and debug code.{% ifversion fpt or ghec %} In addition, indirect dependencies inferred from manifest files (rather than lock files) are excluded from vulnerability checks.{% endif %}
+
+{% ifversion maven-transitive-dependencies %}
+
+## Automatic dependency submission
+
+Some ecosystems resolve indirect dependencies at build time, so static analysis can't see the full dependency tree. When you enable automatic dependency submission for a repository, {% data variables.product.company_short %} automatically identifies the transitive dependencies in the repository for supported ecosystems. See [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems).
+
+In the background, automatic dependency submission runs a {% data variables.product.prodname_actions %} workflow that generates the complete tree and uploads it using the {% data variables.dependency-submission-api.name %}.{% ifversion fpt or ghec %} Automatic dependency submission runs on {% data variables.product.github %}-hosted runners by default and counts toward your {% data variables.product.prodname_actions %} minutes. Optionally, you can choose to run it on self-hosted runners or {% data variables.actions.hosted_runners %}.{% endif %}
+
+To enable automatic dependency submission, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository).
+
+{% endif %}
+
+{% ifversion fpt or ghec %}
+
+## {% data variables.product.prodname_dependabot %} graph jobs
+
+This method uses a special type of {% data variables.product.prodname_dependabot %} job that builds a dependency snapshot and uploads it to the dependency submission API. This is currently only supported for **Go** dependencies.
+
+This approach is similar to automatic dependency submission, but does not incur charges for {% data variables.product.prodname_actions %} minutes. It can also access organization-wide configurations for private registries you've set up for {% data variables.product.prodname_dependabot %}.
+
+{% endif %}
+
+## The {% data variables.dependency-submission-api.name %}
+
+You can call the {% data variables.dependency-submission-api.name %} in your own script or workflow. This is useful if:
+
+* You need to submit transitive dependencies that cannot be detected from lock files.
+* You need to create custom logic or are using an external CI/CD system.
+
+Dependencies are submitted to the {% data variables.dependency-submission-api.name %} in the form of a snapshot. This is a list of dependencies associated with a commit SHA and other metadata, reflecting the current state of your repository.
+
+If you are calling the API in a {% data variables.product.prodname_actions %} workflow, you can use a pre-made action for your ecosystem that automatically gathers the dependencies and submits them to the API. Otherwise, you can write your own action or call the API from an external system.
+
+{% data reusables.dependency-submission.about-dependency-submission %}
+
+For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api).
+
+## Prioritization
+
+{% data reusables.dependency-graph.deduplication %}

content/code-security/concepts/supply-chain-security/index.md

@@ -12,6 +12,7 @@ children:
   - about-supply-chain-security
   - best-practices-for-maintaining-dependencies
   - about-the-dependency-graph
+  - dependency-graph-data
   - about-dependency-review
   - about-dependabot-alerts
   - about-metrics-for-dependabot-alerts

content/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configuring-automatic-dependency-submission-for-your-repository.md

@@ -15,19 +15,7 @@ topics:
 contentType: how-tos
 ---
 
-## About automatic dependency submission
-
-> [!NOTE]
-> Automatic dependency submission does not support all package ecosystems. For the current list of supported ecosystems, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems).
-
-Dependency graph analyzes the manifest and lock files in a repository, in order to help users understand the upstream packages that their software project depends on. However, in some ecosystems, the resolution of transitive dependencies occurs at build-time and {% data variables.product.company_short %} isn't able to automatically discover all dependencies based on the contents of the repository alone.
-
-When you enable automatic dependency submission for a repository, {% data variables.product.company_short %} automatically identifies the transitive dependencies in the repository and will submit these dependencies to {% data variables.product.company_short %} using the {% data variables.dependency-submission-api.name %}. You can then explore these dependencies using the dependency graph. {% data variables.product.prodname_dependabot %} will notify you about security updates for these dependencies by generating {% data variables.product.prodname_dependabot_alerts %} .
-
-Using automatic dependency submission counts toward your {% data variables.product.prodname_actions %} minutes. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions).
-
-Optionally, you can choose to configure self-hosted runners or {% data variables.product.company_short %}-hosted {% data variables.actions.hosted_runners %} for automatic dependency submission. For more information, see [Accessing private registries with self-hosted runners](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository#accessing-private-registries-with-self-hosted-runners) and [Using GitHub-hosted larger runners for automatic dependency submission](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository#using-github-hosted-larger-runners-for-automatic-dependency-submission
-).
+Automatic dependency submission is a method of submitting data to the dependency graph. It allows you to automatically resolve and submit indirect dependencies that are not captured by static analysis. For more information, see [AUTOTITLE](/code-security/concepts/supply-chain-security/dependency-graph-data).
 
 ## Prerequisites
 

content/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/using-the-dependency-submission-api.md

@@ -16,11 +16,7 @@ redirect_from:
 contentType: how-tos
 ---
 
-## About the {% data variables.dependency-submission-api.name %}
-
-{% data reusables.dependency-submission.about-dependency-submission %}
-
-Dependencies are submitted to the {% data variables.dependency-submission-api.name %} in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit. Snapshots can be generated from the dependencies detected at build time. For technical details on using the {% data variables.dependency-submission-api.name %} over the network, see [AUTOTITLE](/rest/dependency-graph/dependency-submission).
+The {% data variables.dependency-submission-api.name %} is a method of submitting data to the dependency graph. It allows you to submit dependencies that are not captured by static analysis. For more information, see [AUTOTITLE](/code-security/concepts/supply-chain-security/dependency-graph-data).
 
 ## Submitting dependencies at build-time