Dependency review works with dependencies submitted with the dependen…

…cy submission API [Public Beta] (#37888)

Co-authored-by: Ben Ahmady <[email protected]>
Co-authored-by: Courtney Claessens <[email protected]>
Co-authored-by: Anne-Marie <[email protected]>
Co-authored-by: Sarah Edwards <[email protected]>

content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review.md

@@ -21,7 +21,7 @@ redirect_from:
 
 ## About dependency review
 
-{% data reusables.dependency-review.feature-overview %}  
+{% data reusables.dependency-review.feature-overview %}
 
 If a pull request targets your repository's default branch and contains changes to package manifests or lock files, you can display a dependency review to see what has changed. The dependency review includes details of changes to indirect dependencies in lock files, and it tells you if any of the added or updated dependencies contain known vulnerabilities.
 
@@ -58,12 +58,44 @@ You can use the {% data variables.dependency-review.action_name %} in your repos
 
 By default, the {% data variables.dependency-review.action_name %} check will fail if it discovers any vulnerable packages. A failed check blocks a pull request from being merged when the repository owner requires the dependency review check to pass. For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging)."
 
-{% ifversion fpt or ghec or ghes %}
-The action uses the Dependency Review REST API to get the diff of dependency changes between the base commit and head commit. You can use the Dependency Review API to get the diff of dependency changes, including vulnerability data, between any two commits on a repository. For more information, see "[AUTOTITLE](/rest/dependency-graph#dependency-review)."
+{% ifversion fpt or ghec or ghes %}The action uses the dependency review REST API to get the diff of dependency changes between the base commit and head commit. You can use the dependency review API to get the diff of dependency changes, including vulnerability data, between any two commits on a repository. For more information, see "[AUTOTITLE](/rest/dependency-graph#dependency-review)."{% endif %}{% ifversion dependency-review-submission-api %} The action also considers dependencies submitted via the dependency submission API. For more information about the dependency submission API, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api)."
+
+{% data reusables.dependency-review.works-with-submission-api-beta %}
+
 {% endif %}
 
 {% ifversion dependency-review-action-configuration %}
 You can configure the {% data variables.dependency-review.action_name %} to better suit your needs. For example, you can specify the severity level that will make the action fail{% ifversion dependency-review-action-licenses %}, or set an allow or deny list for licenses to scan{% endif %}. For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review#configuring-the-dependency-review-github-action)."
 {% endif %}
 
 {% endif %}
+
+{% ifversion dependency-review-submission-api %}
+
+## Best practices for using the dependency review API and the dependency submission API together
+
+The dependency review API and the {% data variables.dependency-review.action_name %} both work by comparing dependency changes in a pull request with the state of your dependencies in the head commit of your target branch, which is usually your default branch.
+
+If your repository only depends on statically defined dependencies in one of {% data variables.product.prodname_dotcom %}’s supported ecosystems, the dependency review API and the {% data variables.dependency-review.action_name %} work consistently.
+
+However, you may want your dependencies to be scanned during a build and then uploaded to the dependency submission API. In this case, there are some best practices you should follow to ensure that you don’t introduce a race condition when running the processes for the dependency review API and the dependency submission API, since it could result in missing data.
+
+The best practices you should take will depend on whether you use {% data variables.product.prodname_actions %} to access the dependency submission API and the dependency review API, or whether you use direct API access.
+
+### Using GitHub Actions to access the dependency submission API and the dependency review API
+
+If you use {% data variables.product.prodname_actions %} to access the dependency submission API or the dependency review API:
+   * Make sure you run all of your dependency submission actions in the same {% data variables.product.prodname_actions %} workflow as your {% data variables.dependency-review.action_name %}. This will give you control over the order of execution, and it will ensure that dependency review will always work.
+   * If you do choose to run the {% data variables.dependency-review.action_name %} separately, for instance, as a required workflow, you should:
+     + Set `retry-on-snapshot-warnings` to `true`.
+     + Set `retry-on-snapshot-warnings-timeout` to slightly exceed the typical run time (in seconds) of your longest-running dependency submission action.
+
+### Using direct API access to the dependency submission API and the dependency review API
+
+If you don’t use {% data variables.product.prodname_actions %}, and your code relies on direct access to the dependency submission API and the dependency review API:
+   * Make sure you run the code that calls the dependency submission API first, and then run the code that calls the dependency review API afterwards.
+   * If you do choose to run the code for the dependency submission API and the dependency review API in parallel, you should implement a retry logic and note the following:
+     + When there are snapshots missing for either side of the comparison, you will see an explanation for that in the `x-github-dependency-graph-snapshot-warnings` header (as a base64-encoded string). Therefore, if the header is non-empty, you should consider retrying.
+     + Implement a retry logic with exponential backoff retries.
+     + Implement a reasonable number of retries to account for the typical runtime of your dependency submission code.
+{% endif %}

data/features/dependency-review-submission-api.yml

@@ -0,0 +1,5 @@
+# Reference: Issue #10333 Dependency review works with dependencies submitted with the dependency submission API [Public Beta]
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>3.10'

data/reusables/dependency-review/works-with-submission-api-beta.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** The dependency review API and the dependency submission API work together. This means that the dependency review API will include dependencies submitted via the dependency submission API. This feature is currently in public beta and subject to change.
+
+{% endnote %}

data/reusables/dependency-submission/about-dependency-submission.md

@@ -2,4 +2,7 @@ You can use the REST API to submit dependencies for a project. This enables you
 
 The dependency graph shows any dependencies you submit using the API in addition to any dependencies that are identified from manifest or lock files in the repository (for example, a `package-lock.json` file in a JavaScript project). For more information about viewing the dependency graph, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#viewing-the-dependency-graph)."
 
-Submitted dependencies will receive {% data variables.product.prodname_dependabot_alerts %} and {% data variables.product.prodname_dependabot_security_updates %} for any known vulnerabilities. You will only get {% data variables.product.prodname_dependabot_alerts %} for dependencies that are from one of the [supported ecosystems](https://github.com/github/advisory-database#supported-ecosystems) of the {% data variables.product.prodname_advisory_database %}. Submitted dependencies will not be surfaced in dependency review or your organization's dependency insights.
+Submitted dependencies will receive {% data variables.product.prodname_dependabot_alerts %} and {% data variables.product.prodname_dependabot_security_updates %} for any known vulnerabilities. You will only get {% data variables.product.prodname_dependabot_alerts %} for dependencies that are from one of the supported ecosystems for the {% data variables.product.prodname_advisory_database %}. For more information about these ecosystems, see "[AUTOTITLE](/code-security/security-advisories/global-security-advisories/about-the-github-advisory-database#github-reviewed-advisories)." {% ifversion dependency-review-submission-api %}Submitted dependencies will be surfaced in dependency review or your organization's dependency insights.
+
+{% data reusables.dependency-review.works-with-submission-api-beta %}
+{% else %}Submitted dependencies will _not_ be surfaced in dependency review or your organization's dependency insights.{% endif %}