Skip to content

Commit 615040d

Browse files
Laura JiangCopilot
andcommitted
Revise status checks docs: replace verbose callouts with concise inline guidance
Replace [!IMPORTANT], [!WARNING], [!TIP] callout blocks and subsections with inline sentences. Same 5 feedback items addressed, doc is shorter and reads naturally: - Genre/name notation inline in bullet descriptions - Build timing sentence in intro paragraph - Dropdown behavior parenthetical in step 5 - Advanced Options warning inline in step 6 - Enable Wait For Processing sentence before setup steps - Removed 'How status checks work' and 'Prerequisites' subsections Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 7f76b08 commit 615040d

1 file changed

Lines changed: 7 additions & 37 deletions

File tree

docs/repos/security/configure-github-advanced-security-features.md

Lines changed: 7 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -265,59 +265,29 @@ Pull request annotations also require an Advanced Security scan on your default
265265

266266
## Set up pull request status checks
267267

268-
Advanced Security status checks allow you to block pull requests from being merged when security vulnerabilities are detected. These status checks evaluate dependency scanning, code scanning, and secret scanning results and post a status to your pull request based on the findings.
268+
Advanced Security status checks allow you to block pull requests from being merged when security vulnerabilities are detected. These status checks evaluate dependency scanning, code scanning, and secret scanning results and post a status to your pull request based on the findings. Status checks post after the build completes and SARIF results upload successfully.
269269

270-
There are two types of status checks available:
270+
There are two status checks available:
271271

272-
* **Block on all critical and high vulnerabilities (Absolute check)**: This status check (genre: `AdvancedSecurity`, name: `AllHighAndCritical`) fails when the repository has any open critical or high severity vulnerability detected by Advanced Security, whether the vulnerability is pre-existing or newly introduced. Use this check to enforce that all critical and high severity alerts across the repository are resolved before merging.
273-
* **Block on new critical and high vulnerabilities (Delta check)**: This status check (genre: `AdvancedSecurity`, name: `NewHighAndCritical`) fails only when the pull request introduces new critical or high severity vulnerabilities. Pre-existing vulnerabilities in the repository don't cause this check to fail. Use this check to prevent new vulnerabilities from being introduced without requiring all existing vulnerabilities to be fixed first.
274-
275-
> [!NOTE]
276-
> If Advanced Security is not enabled for the repository, status checks use **fail-open** behavior — they won't block the pull request. Status checks only actively gate pull requests when Advanced Security is enabled and configured.
277-
278-
### How status checks work
279-
280-
Status checks are evaluated **after the CI build completes successfully** and the SARIF results are uploaded. Keep the following timing requirements in mind:
281-
282-
* The pipeline containing your Advanced Security tasks (dependency scanning, code scanning) must **succeed** — status checks aren't posted from failed builds.
283-
* The pull request must use the **current pipeline definition** that includes the Advanced Security tasks. If the pipeline definition has been removed or changed to exclude these tasks, status checks won't be posted.
284-
* When new security findings are detected in a pull request, Advanced Security also creates **PR comments** on the relevant code lines. These comments are automatically resolved when the underlying alert is fixed.
285-
286-
### Prerequisites for status checks
287-
288-
> [!IMPORTANT]
289-
> **Enable Wait For Processing**: If your pipeline contains **multiple build tasks** (for example, multiple CodeQL initialization or publish steps), you must set **"Enable Wait For Processing"** to `true` on the CodeQL Build and Publish tasks. This setting ensures that status checks are evaluated synchronously during the build and is **required by design** for multi-task pipelines. Without this setting, status checks may not be posted correctly.
290-
291-
> [!WARNING]
292-
> **Do not modify Advanced Options in the status policy configuration.** The following changes in **Status Policy > Advanced options** will break status check posting:
293-
>
294-
> * **Changing the authorized identity** away from the default Advanced Security identity — the modified identity won't have permission to post status checks.
295-
> * **Requiring an iteration ID** — iteration ID is not available in SARIF data, so status checks will fail to post.
296-
>
297-
> Leave these Advanced Options at their default values.
272+
* **Block on all critical and high vulnerabilities** (`AdvancedSecurity/AllHighAndCritical`): Fails when the repository has any open critical or high severity vulnerability detected by Advanced Security, whether the vulnerability is pre-existing or newly introduced. Use this check to enforce that all critical and high severity alerts across the repository are resolved before merging.
273+
* **Block on new critical and high vulnerabilities** (`AdvancedSecurity/NewHighAndCritical`): Fails only when the pull request introduces new critical or high severity vulnerabilities. Pre-existing vulnerabilities in the repository don't cause this check to fail. Use this check to prevent new vulnerabilities from being introduced without requiring all existing vulnerabilities to be fixed first.
298274

299275
### Configure status checks as branch policies
300276

301-
To require Advanced Security status checks before pull requests can be merged, configure them as branch policies. You can set them per repository or for a project.
277+
To require Advanced Security status checks before pull requests can be merged, configure them as branch policies. You can set them per repository or for a project. If your pipeline has multiple build tasks, set **Enable Wait For Processing** to `true` on CodeQL Build and Publish tasks.
302278

303279
1. Go to **Project settings** > **Repos**.
304280
1. Optionally, select the repository you want to configure.
305281
1. Select **Policies** and then select the branch you want to protect. By default, the default branch of your repositories will be protected.
306282
1. Under **Status checks**, select **+** to add a new status check policy.
307-
1. In the **Status to check** menu, enter **AdvancedSecurity** for the Genre and **AllHighAndCritical** or **NewHighAndCritical** for the Name.
308-
1. Choose the **Policy requirement** (required or optional) and set any other desired options.
283+
1. In the **Status to check** menu, enter **AdvancedSecurity** for the Genre and **AllHighAndCritical** or **NewHighAndCritical** for the Name. (These options appear after the first successful pipeline run with Advanced Security tasks.)
284+
1. Choose the **Policy requirement** (required or optional) and set any other desired options. Leave **Advanced Options** at their defaults — changing the authorized identity or requiring an iteration ID prevents status checks from posting.
309285
1. Select **Save**.
310286

311287
:::image type="content" source="media/adv-sec-status-checks.png" lightbox="media/adv-sec-status-checks.png" alt-text="Screenshot of adding an Advanced Security status check.":::
312288

313289
For more information on configuring status check policies, see [Status checks](../git/branch-policies.md#status-checks).
314290

315-
> [!TIP]
316-
> Advanced Security status checks require Advanced Security to be enabled and an Advanced Security scan to run on your pull request branch. Make sure you have a build validation policy configured with dependency scanning and/or code scanning tasks in your pipeline. For more information, see [Build validation](../git/branch-policies.md#build-validation).
317-
318-
> [!TIP]
319-
> **Status checks only appear in the branch policy dropdown after they have been used at least once.** If you don't see `NewHighAndCritical` in the dropdown, run a pipeline with Advanced Security tasks on a pull request first. The status check will appear in the dropdown after the first successful run.
320-
321291
To disable Advanced Security, any alerts and state of alerts get retained in the Advanced Security tab for the next time you re-enable Advanced Security for your repository.
322292

323293
## Related articles

0 commit comments

Comments
 (0)