Add scenario driven content to the dependency review documentation (#51380)

Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>
Co-authored-by: Jon Janego <jonjanego@github.com>

content/actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions.md

@@ -61,6 +61,10 @@ For more information about dependency review, see "[AUTOTITLE](/code-security/su
 
 {% data reusables.dependency-review.about-dependency-review-action %}
 
+![Screenshot of a workflow run that uses the dependency review action.](/assets/images/help/graphs/dependency-review-action.png)
+
+{% data reusables.dependency-review.about-dependency-review-action2 %}
+
 ## Keeping the actions in your workflows secure and up to date
 
 {% data reusables.actions.dependabot-version-updates-for-actions %}

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

@@ -47,10 +47,16 @@ The dependency review feature becomes available when you enable the dependency g
 
 The action is available for all {% ifversion fpt or ghec %}public repositories, as well as private {% endif %}repositories that have {% data variables.product.prodname_GH_advanced_security %} enabled.
 
+{% data reusables.dependency-review.org-level-enforcement %}
+
 {% data reusables.dependency-review.action-enterprise %}
 
 {% data reusables.dependency-review.about-dependency-review-action %}
 
+![Screenshot of a workflow run that uses the dependency review action.](/assets/images/help/graphs/dependency-review-action.png)
+
+{% data reusables.dependency-review.about-dependency-review-action2 %}
+
 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 dependency-review-submission-api %} The action also considers dependencies submitted via the {% data variables.dependency-submission-api.name %}. For more information about the {% data variables.dependency-submission-api.name %}, 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 %}

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

@@ -51,6 +51,8 @@ Dependency review is available when dependency graph is enabled for {% data vari
 
 {% data reusables.dependency-review.dependency-review-action-overview %}
 
+{% data reusables.dependency-review.org-level-enforcement %}
+
 Here is a list of common configuration options.  For more information, and a full list of options, see [Dependency Review](https://github.com/marketplace/actions/dependency-review) on the {% data variables.product.prodname_marketplace %}.
 
 | Option | Required | Usage |

content/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization.md

@@ -0,0 +1,45 @@
+---
+title: Enforcing dependency review across an organization
+intro: 'Dependency review lets you catch insecure dependencies before you introduce them to your environment. You can enforce the use of the {% data variables.dependency-review.action_name %} across your organization.'
+product: '{% data reusables.gated-features.dependency-review %}'
+shortTitle: Enforce dependency review
+permissions: 'Organization owners can enforce use of the {% data variables.dependency-review.action_name %} in repositories within their organization.'
+versions:
+  feature: repo-rules
+type: overview
+topics:
+  - Advanced Security
+  - Dependency review
+  - Vulnerabilities
+  - Dependencies
+  - Pull requests
+---
+
+## About dependency review enforcement
+
+{% data reusables.dependency-review.action-enterprise %}
+
+{% data reusables.dependency-review.about-dependency-review-action %} For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)."
+
+You can enforce the use of the {% data variables.dependency-review.action_name %} in your organization by setting up a repository ruleset that will require the `dependency-review-action` workflow to pass before pull requests can be merged. Repository rulesets are rule settings that allow you to control how users can interact with selected branches and tags in your repositories. For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)" and "[Require workflows to pass before merging](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging)."
+
+## Prerequisites
+
+You need to add the {% data variables.dependency-review.action_name %} to one of the repositories in your organization, and configure the action. For more information, see "[Configuring the dependency review action](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review#configuring-the-dependency-review-action)."
+
+## Enforcing dependency review for your organization
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+{% data reusables.organizations.access-ruleset-settings %}
+1. Click **New branch ruleset**.
+1. Set **Enforcement status** to {% octicon "play" aria-hidden="true" %} **Active**.
+1. Optionally, you can target specific repositories in your organization. For more information, see "[Choosing which repositories to target in your organization](/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization#choosing-which-repositories-to-target-in-your-organization)."
+1. In the "Rules" section, select the "Require workflows to pass before merging" option.
+1. In "Workflow configurations", click **Add workflow**.
+1. In the dialog, select the repository that you added the {% data variables.dependency-review.action_name %} to. For more information, see "[Prerequisites](#prerequisites)."
+1. Select a branch and the workflow file for dependency review in the enhanced dialog.
+
+   ![Screenshot of the Add required workflow dialog. You need to specify a repository, branch, and workflow.](/assets/images/help/repository/add-required-workflow-dialog.png)
+
+1. Click **Create**.

content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md

@@ -17,6 +17,7 @@ children:
   - /using-the-dependency-submission-api
   - /about-dependency-review
   - /configuring-dependency-review
+  - /enforcing-dependency-review-across-an-organization
   - /exploring-the-dependencies-of-a-repository
   - /troubleshooting-the-dependency-graph
 ---

data/reusables/dependency-review/about-dependency-review-action.md

@@ -1,5 +1 @@
 You can use the [`dependency-review-action`](https://github.com/actions/dependency-review-action) in your repository to enforce dependency reviews on your pull requests. The action scans for vulnerable versions of dependencies introduced by package version changes in pull requests, and warns you about the associated security vulnerabilities. This gives you better visibility of what's changing in a pull request, and helps prevent vulnerabilities being added to your repository.
-
-![Screenshot of a workflow run that uses the Dependency review action.](/assets/images/help/graphs/dependency-review-action.png)
-
-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)."

data/reusables/dependency-review/about-dependency-review-action2.md

@@ -0,0 +1 @@
+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)."

data/reusables/dependency-review/org-level-enforcement.md

@@ -0,0 +1,5 @@
+{% ifversion repo-rules %}
+
+Organization owners can roll out dependency review at scale by enforcing the use of the {% data variables.dependency-review.action_name %} across repositories in the organization. This involves the use of repository rulesets for which you'll set the {% data variables.dependency-review.action_name %} as a required workflow, which means that pull requests can only be merged once the workflow passes all the required checks. For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization)."
+
+{% endif %}