[Code Quality] Document org-level repo targeting for enablement (#62063)

Co-authored-by: carogalvin <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>

Author: 3 people

content/code-security/concepts/about-code-quality.md

@@ -7,6 +7,8 @@ product: '{% data reusables.gated-features.code-quality-availability %}'
 versions:
   feature: code-quality
 contentType: concepts
+audience:
+  - driver
 redirect_from:
   - /code-security/code-quality/concepts/about-code-quality
   - /code-security/code-quality/concepts
@@ -83,6 +85,65 @@ If you have set up code coverage, the `{% data variables.code-quality.pr_comment
 
 Each {% data variables.product.prodname_codeql %} analysis will use {% data variables.product.prodname_actions %} minutes and can be seen on the **Actions** tab of the repository as a run of the dynamic "{% data variables.code-quality.workflow_name_actions %}" workflow.
 
+## How enablement works across your enterprise
+
+{% data variables.product.prodname_code_quality_short %} is controlled at three levels, so you can decide how much autonomy to give organizations and repositories:
+
+* **Enterprise:** An enterprise owner must first allow {% data variables.product.prodname_code_quality_short %} for the enterprise. Until they do, organization owners cannot enable it.
+* **Organization:** Organization owners control which repositories have {% data variables.product.prodname_code_quality_short %} enabled or disabled, by granting access to all repositories, a selected list, or repositories that match a filter. They can also enforce these settings so that repository administrators cannot change them.
+* **Repository:** Repository administrators can enable or disable {% data variables.product.prodname_code_quality_short %} for individual repositories, unless organization-level enforcement applies.
+
+When {% data variables.product.prodname_code_quality_short %} is enabled on a repository, {% data variables.product.prodname_codeql %} analysis runs via {% data variables.product.prodname_actions %} and surfaces findings in pull requests and on the default branch. Developers see quality checks and annotations on their pull requests.
+
+## Organization-level repository access
+
+At the organization level, you control {% data variables.product.prodname_code_quality_short %} with a single **Repository access** setting. This setting determines which repositories have {% data variables.product.prodname_code_quality_short %} enabled and which have it disabled: repositories within your selection are enabled, and repositories outside your selection are disabled.
+
+> [!IMPORTANT]
+> Changing the **Repository access** setting can both enable **and** disable {% data variables.product.prodname_code_quality_short %} across many repositories at once. For example, if you enable {% data variables.product.prodname_code_quality_short %} for repositories matching a filter, any repository that does not match the filter is disabled. Before your change is applied, a dialog shows the total number of enabled and disabled repositories, along with the billing impact.
+
+### Repository access options
+
+You can apply one of the following options at a time.
+
+| Option | Behavior |
+| ------ | -------- |
+| **No repositories** | Disables {% data variables.product.prodname_code_quality_short %} for all current and future repositories in the organization. |
+| **Let repositories decide** | The organization neither enables nor disables {% data variables.product.prodname_code_quality_short %}. Repository administrators choose whether to enable it for their own repositories. This option cannot be enforced. |
+| **All repositories** | Enables {% data variables.product.prodname_code_quality_short %} for all current and future repositories. |
+| **Selected repositories** | Enables {% data variables.product.prodname_code_quality_short %} for a specific list of repositories that you choose. Repositories you do not select are disabled, and new repositories are not enabled automatically. Best for pilots or exceptions. |
+| **Matching a filter** | Enables {% data variables.product.prodname_code_quality_short %} for repositories that match a filter you define, now and in the future. Repositories that do not match are disabled. See [Filtering repositories](#filtering-repositories). |
+
+### Filtering repositories
+
+When you choose **Matching a filter**, you create a dynamic filter that automatically enables {% data variables.product.prodname_code_quality_short %} for existing and future repositories that match your criteria. This is useful for ongoing governance at scale.
+
+You can filter on any combination of the following criteria:
+
+* **Visibility:** Whether repositories are public, private, or internal. Useful for broad policies, such as enabling {% data variables.product.prodname_code_quality_short %} for all private repositories.
+* **Fork status:** Whether repositories are forks. Useful when forks should not consume analysis resources.
+* **Custom property:** Whether repositories have a specific custom property value. For example, you could target repositories with a `team:platform` property.
+
+All conditions in a filter are combined with `AND`, so a repository must match every condition to be enabled. You can also exclude repositories that match specific conditions.
+
+### Enforcing access
+
+By default, repository administrators can change {% data variables.product.prodname_code_quality_short %} settings for their own repositories. To prevent this, enable **Enforce access**.
+
+Enforcement locks in both the enabled and disabled states set by your **Repository access** option, so repository administrators cannot override them. This improves consistency across your organization, but reduces flexibility for individual repository administrators.
+
+* Enforcement applies to most **Repository access** options you select, including **No repositories**, which enforces {% data variables.product.prodname_code_quality_short %} as disabled.
+* Enforcement is not available with **Let repositories decide**, which intentionally leaves the choice to repository administrators.
+
+## Planning your rollout
+
+Because enabling {% data variables.product.prodname_code_quality_short %} can affect many repositories at once and each analysis consumes {% data variables.product.prodname_actions %} minutes, plan how you roll it out across your organization:
+
+* **Start with a pilot group.** Enable a small, representative set of repositories first—for example, by selecting them individually or matching a custom property—so you can validate results before expanding.
+* **Check your {% data variables.product.prodname_actions %} capacity.** Confirm your runners can absorb the additional load before you enable {% data variables.product.prodname_code_quality_short %} broadly.
+* **Decide whether to enforce enablement.** Enforcement gives you consistent coverage and prevents repository administrators from opting out, but it removes their flexibility. Leaving enforcement off during a pilot lets teams opt in and out as they learn.
+* **Expand once results are trusted.** After you've confirmed that analysis runs smoothly and developers understand the findings, widen your selection or filter to cover more repositories.
+
 ## Next steps
 
 * **For your repository or organization:** Turn on {% data variables.product.prodname_code_quality_short %} to start generating results. See [AUTOTITLE](/code-security/how-tos/maintain-quality-code/enable-code-quality).

content/code-security/how-tos/maintain-quality-code/enable-code-quality.md

@@ -1,11 +1,13 @@
 ---
 title: Enabling {% data variables.product.prodname_code_quality %}
 shortTitle: Enable Code Quality
-intro: Use {% data variables.product.prodname_code_quality_short %} to automatically catch, fix, and report on code quality issues in pull requests and on your default branch.
+intro: Enable {% data variables.product.prodname_code_quality_short %} across your organization's repositories to automatically identify and remediate code quality issues at scale, helping you maintain consistency and reduce operational risk.
 versions:
   feature: code-quality
 product: '{% data reusables.gated-features.code-quality-availability %}'
 permissions: '{% data reusables.permissions.code-quality-repo-enable %}'
+audience:
+  - driver
 contentType: how-tos
 redirect_from:
   - /code-security/code-quality/how-tos/enable-code-quality
@@ -37,17 +39,27 @@ category:
 > [!TIP]
 > If your organization has configured caching of private registries, these will be available for code quality analysis to use to resolve dependencies. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries#code-quality-access-to-private-registries).
 
-## Enabling {% data variables.product.prodname_code_quality_short %} for an organization
+## Enabling {% data variables.product.prodname_code_quality_short %} for your organization
 
-You can enable or disable {% data variables.product.prodname_code_quality_short %} for all repositories in an organization at once.
+{% data reusables.code-quality.code-quality-org-targeting-preview-note %}
+
+At the organization level, you control {% data variables.product.prodname_code_quality_short %} with a single **Repository access** setting. This gives you granular options, from enabling every repository to targeting a specific list or a dynamic filter, so you can pilot {% data variables.product.prodname_code_quality_short %} intentionally and roll it out at your own pace. Repositories within your selection are enabled, and repositories outside your selection are disabled.
+
+For the available access options, and how filtering and enforcement work, see [AUTOTITLE](/code-security/code-quality/concepts/about-code-quality#organization-level-repository-access).
 
 {% data reusables.organizations.navigate-to-org %}
 {% data reusables.organizations.org_settings %}
 1. In the sidebar, under "Security", click **{% data variables.code-quality.code_quality_ui_settings %}**.
-1. Next to "Enable Code Quality", use the toggle to enable {% data variables.product.prodname_code_quality_short %} for all repositories.
+1. Under "Repository access", select an option from the dropdown menu.
+   * If you selected **Selected repositories...**, choose the repositories you want to enable.
+   * If you selected **Matching a filter...**, define your filter.
+1. Optionally, to prevent repository administrators from changing these settings, enable **Enforce access**.
+1. If your change enables or disables {% data variables.product.prodname_code_quality_short %} on any repositories, a "Review enablement and billing changes" dialog appears, showing the total number of enabled and disabled repositories and the associated costs. Review the details, then click **Confirm**.
+
+Your changes are saved automatically and begin to propagate immediately. In large organizations, it can take several minutes for the changes to apply across all repositories.
 
 ## Next steps
 
 * **For your repository:** Explore your code quality findings and merge your first fix. See [AUTOTITLE](/code-security/tutorials/improve-code-quality/quickstart).
 * **Add code coverage:** Upload test coverage reports to see coverage results directly on pull requests. See [AUTOTITLE](/code-security/how-tos/maintain-quality-code/set-up-code-coverage).
-* **For your organization:** Understand the code health of your repositories at a glance. See [AUTOTITLE](/code-security/how-tos/view-and-interpret-data/analyze-organization-data/explore-code-quality).
+* **For your organization:** Understand the code health of your repositories at a glance. See [AUTOTITLE](/code-security/how-tos/view-and-interpret-data/analyze-organization-data/explore-code-quality).

data/reusables/code-quality/code-quality-org-targeting-preview-note.md

@@ -0,0 +1,2 @@
+> [!NOTE]
+> Organization-level repository targeting for {% data variables.product.prodname_code_quality %} is in {% data variables.release-phases.public_preview %} and subject to change.