Merge pull request #214855 from ElazarK/pr-annotations

pr annotation fixes

Author: tamarakhader

articles/defender-for-cloud/media/tutorial-enable-pr-annotations/annotation-on.png

@@ -3,17 +3,17 @@ title: Tutorial Enable pull request annotations in GitHub or in Azure DevOps
 description: Add pull request annotations in GitHub or in Azure DevOps. By adding pull request annotations, your SecOps and developer teams so that they can be on the same page when it comes to mitigating issues.
 ms.topic: overview
 ms.custom: ignite-2022
-ms.date: 09/20/2022
+ms.date: 10/20/2022
 ---
 
 # Tutorial: Enable pull request annotations in GitHub and Azure DevOps
 
-With Microsoft Defender for Cloud, you can configure pull request annotations in Azure DevOps. Pull request annotations are enabled in Microsoft Defender for Cloud by security operators and are sent to the developers who can then take action directly in their pull requests. This allows both security operators and developers to see the same security issue information in the systems they're accustomed to working in. Security operators see unresolved findings in Defender for Cloud and developers see them in their source code management systems. These issues can then be acted upon by developers when they submit their pull requests. This helps prevent and fix potential security vulnerabilities and misconfigurations before they enter the production stage.
+Defender for DevOps exposes security findings as annotations in Pull Requests (PR). Security operators can enable PR annotations in Microsoft Defender for Cloud. Any exposed issues can then be remedied by developers. This process can prevent and fix potential security vulnerabilities and misconfigurations before they enter the production stage. Defender for DevOps annotates the vulnerabilities within the differences in the file rather than all the vulnerabilities detected across the entire file. Developers are able to see annotations in their source code management systems and Security operators can see any unresolved findings in Microsoft Defender for Cloud.  
 
-You can get pull request annotations in GitHub if you're a customer of GitHub Advanced Security.
+With Microsoft Defender for Cloud, you can configure PR annotations in Azure DevOps. You can get PR annotations in GitHub if you're a GitHub Advanced Security customer. 
 
 > [!NOTE]
-> During the Defender for DevOps preview period, GitHub Advanced Security for Azure DevOps (GHAS for AzDO) is also providing a free trial of pull request annotations.
+> GitHub Advanced Security for Azure DevOps (GHAzDO) is providing a free trial of PR annotations during the Defender for DevOps preview. 
 
 In this tutorial you'll learn how to:
 
@@ -27,55 +27,47 @@ Before you can follow the steps in this tutorial, you must:
 
 **For GitHub**:
 
- - Have an Azure subscription, create a [free account](https://azure.microsoft.com/free/) before you begin
- - [Enable Defender for Cloud](get-started.md)
- - Have [enhanced security features](enhanced-security-features-overview.md) enabled on your Azure subscriptions
- - [Connect your GitHub repositories to Microsoft Defender for Cloud](quickstart-onboard-github.md)
- - [Configure the Microsoft Security DevOps GitHub action](github-action.md)
- - Be a [GitHub Advanced Security customer](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security)
+- An Azure account. If you don't already have an Azure account, you can [create your Azure free account today](https://azure.microsoft.com/free/).
+- Be a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) customer. 
+- [Connect your GitHub repositories to Microsoft Defender for Cloud](quickstart-onboard-github.md).
+- [Configure the Microsoft Security DevOps GitHub action](github-action.md).
 
 **For Azure DevOps**:
 
- - Have an Azure subscription, create a [free account](https://azure.microsoft.com/free/) before you begin
- - [Enable Defender for Cloud](get-started.md)
- - Have [enhanced security features](enhanced-security-features-overview.md) enabled on your Azure subscriptions
- - [Connect your Azure DevOps repositories to Microsoft Defender for Cloud](quickstart-onboard-devops.md)
- - [Configure the Microsoft Security DevOps Azure DevOps extension](azure-devops-extension.md)
- - [Setup secret scanning in Azure DevOps](detect-credential-leaks.md#setup-secret-scanning-in-azure-devops)
+- An Azure account. If you don't already have an Azure account, you can [create your Azure free account today](https://azure.microsoft.com/free/).
+- [Connect your Azure DevOps repositories to Microsoft Defender for Cloud](quickstart-onboard-devops.md).
+- [Configure the Microsoft Security DevOps Azure DevOps extension](azure-devops-extension.md).
+- [Setup secret scanning in Azure DevOps](detect-credential-leaks.md#setup-secret-scanning-in-azure-devops).
 
 ## Enable pull request annotations in GitHub
 
-By enabling pull request annotations in GitHub, your developers gain the ability to see their security issues when they submit their pull requests directly to the main branch.
+By enabling pull request annotations in GitHub, your developers gain the ability to see their security issues when they create a PR directly to the main branch.
 
 **To enable pull request annotations in GitHub**:
 
-1. Sign in to [GitHub](https://github.com/).
+1. Navigate to [GitHub](https://github.com/) and sign in.
 
-1. Select the relevant repository.
+1. Select a repository that you've onboarded to Defender for Cloud.
 
-1. Select **.github/workflows**.
+1. Navigate to **`Your repository's home page`** > **.github/workflows**.
 
-    :::image type="content" source="media/tutorial-enable-pr-annotations/workflow-folder.png" alt-text="Screenshot that shows where to navigate to, to select the GitHub workflow folder.":::
+    :::image type="content" source="media/tutorial-enable-pr-annotations/workflow-folder.png" alt-text="Screenshot that shows where to navigate to, to select the GitHub workflow folder." lightbox="media/tutorial-enable-pr-annotations/workflow-folder.png":::
 
-1. Select **msdevopssec.yml**.
+1. Select **msdevopssec.yml**, which was created in the [prerequisites](#prerequisites).
 
-    :::image type="content" source="media/tutorial-enable-pr-annotations/devopssec.png" alt-text="Screenshot that shows you where on the screen to select the msdevopssec.yml file.":::
+    :::image type="content" source="media/tutorial-enable-pr-annotations/devopssec.png" alt-text="Screenshot that shows you where on the screen to select the msdevopssec.yml file." lightbox="media/tutorial-enable-pr-annotations/devopssec.png":::
 
 1. Select **edit**.
 
-    :::image type="content" source="media/tutorial-enable-pr-annotations/edit-button.png" alt-text="Screenshot that shows you what the edit button looks like.":::
+    :::image type="content" source="media/tutorial-enable-pr-annotations/edit-button.png" alt-text="Screenshot that shows you what the edit button looks like." lightbox="media/tutorial-enable-pr-annotations/edit-button.png":::
 
 1. Locate and update the trigger section to include:
 
     ```yml
     # Triggers the workflow on push or pull request events but only for the main branch
-    push: 
-      branches: [ main ]
     pull_request:
-      branches: [ main ]
+      branches: ["main"]
     ```
-    
-    By adding these lines to your yaml file, you'll configure the action to run when either a push or pull request event occurs on the designated repository.  
 
     You can also view a [sample repository](https://github.com/microsoft/security-devops-action/tree/main/samples).
 
@@ -85,19 +77,15 @@ By enabling pull request annotations in GitHub, your developers gain the ability
 
 1. Select **Commit changes**.
 
-1. Select **Files changed**.
+Any issues that are discovered by the scanner will be viewable in the Files changed section of your pull request.
 
-You'll now be able to see all the issues that were discovered by the scanner.
+### Resolve security issues in GitHub
 
-### Mitigate GitHub issues found by the scanner
-
-Once you've configured the scanner, you'll be able to view all issues that were detected.
-
-**To mitigate GitHub issues found by the scanner**:
+**To resolve security issues in GitHub**:
 
 1. Navigate through the page and locate an affected file with an annotation.
 
-1. Select **Dismiss alert**.
+1. Follow the remediation steps in the annotation. If you choose not remediate the annotation, select **Dismiss alert**.
 
 1. Select a reason to dismiss:
 
@@ -107,7 +95,7 @@ Once you've configured the scanner, you'll be able to view all issues that were
 
 ## Enable pull request annotations in Azure DevOps
 
-By enabling pull request annotations in Azure DevOps, your developers gain the ability to see their security issues when they submit their pull requests directly to the main branch.
+By enabling pull request annotations in Azure DevOps, your developers gain the ability to see their security issues when they create PRs directly to the main branch.
 
 ### Enable Build Validation policy for the CI Build
 
@@ -119,13 +107,27 @@ Before you can enable pull request annotations, your main branch must have enabl
 
 1. Navigate to **Project settings** > **Repositories**.
 
+    :::image type="content" source="media/tutorial-enable-pr-annotations/project-settings.png" alt-text="Screenshot that shows you where to navigate to, to select repositories.":::
+
 1. Select the repository to enable pull requests on.
 
 1. Select **Policies**.
 
-1. Navigate to **Branch Policies** > **Build Validation**. 
+1. Navigate to **Branch Policies** > **Main branch**.
+
+    :::image type="content" source="media/tutorial-enable-pr-annotations/branch-policies.png" alt-text="Screenshot that shows where to locate the branch policies." lightbox="media/tutorial-enable-pr-annotations/branch-policies.png":::
+
+1. Locate the Build Validation section. 
+
+1. Ensure the CI Build is toggled to **On**.
+
+    :::image type="content" source="media/tutorial-enable-pr-annotations/build-validation.png" alt-text="Screenshot that shows where the CI Build toggle is located.":::
+
+1. Select **Save**. 
 
-1. Toggle the CI Build to **On**.
+    :::image type="content" source="media/tutorial-enable-pr-annotations/validation-policy.png" alt-text="Screenshot that shows the build validation.":::
+
+Once you have completed these steps you can select the build pipeline you created previously and customize it's settings to suit your needs.  
 
 ### Enable pull request annotations
 
@@ -143,48 +145,59 @@ Before you can enable pull request annotations, your main branch must have enabl
 
 1. Toggle Pull request annotations to **On**.
 
-1. Select a category from the drop-down menu. 
+    :::image type="content" source="media/tutorial-enable-pr-annotations/annotation-on.png" alt-text="Screenshot that shows the toggle switched to on.":::
+
+1. (Optional) Select a category from the drop-down menu. 
 
     > [!NOTE]
-    > Only secret scan results is currently supported.
+    > Only secret scan results are currently supported.
 
-1. Select a severity level from the drop-down menu.
+1. (Optional) Select a severity level from the drop-down menu.
+
+    > [!NOTE]
+    > Only high-level severity findings are currently supported.
 
 1. Select **Save**.
 
-All annotations will now be displayed based on your configurations with the relevant line of code.
+All annotations on your main branch will be displayed from now on based on your configurations with the relevant line of code.
 
-### Mitigate Azure DevOps issues found by the scanner
+### Resolve security issues in Azure DevOps
 
 Once you've configured the scanner, you'll be able to view all issues that were detected.
 
-**To mitigate Azure DevOps issues found by the scanner**:
+**To resolve security issues in Azure DevOps**:
 
-1. Sign in to the [Azure portal](https://portal.azure.com).
+1. Sign in to the [Azure DevOps](https://azure.microsoft.com/products/devops).
 
 1. Navigate to **Pull requests**.
 
-1. Scroll through the Overview page and locate an affected line with an annotation.
+    :::image type="content" source="media/tutorial-enable-pr-annotations/pull-requests.png" alt-text="Screenshot showing where to go to navigate to pull requests.":::
+
+1. On the Overview, or files page, locate an affected line with an annotation.
 
-1. Select **Active**.
+1. Follow the remediation steps in the annotation.
 
-1. Select action to take:
+1. Select **Active** to change the status of the annotation and access the dropdown menu. 
+
+1. Select an action to take:
 
     - **Active** - The default status for new annotations.    
     - **Pending** - The finding is being worked on.
     - **Resolved** - The finding has been addressed.
     - **Won't fix** - The finding is noted but won't be fixed.
     - **Closed** - The discussion in this annotation is closed.
 
+Defender for DevOps will re-activate an annotation if the security issue is not fixed in a new iteration.
+
 ## Learn more
 
 In this tutorial, you learned how to enable pull request annotations in GitHub and Azure DevOps.
 
 Learn more about [Defender for DevOps](defender-for-devops-introduction.md).
 
-Learn how to [connect your GitHub](quickstart-onboard-github.md) to Defender for Cloud.
+Learn how to [Discover misconfigurations in Infrastructure as Code](iac-vulnerabilities.md).
 
-Learn how to [connect your Azure DevOps](quickstart-onboard-devops.md) to Defender for Cloud.
+Learn how to [detect exposed secrets in code](detect-credential-leaks.md).
 
 ## Next steps