Merge pull request #44291 from github/repo-sync

Repo sync

Author: docs-bot

content/code-security/concepts/security-at-scale/about-enabling-security-features-at-scale.md

@@ -45,6 +45,12 @@ For more information on purchasing {% data variables.product.prodname_GH_cs_or_s
 To learn how to create {% data variables.product.prodname_custom_security_configurations %}, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration).
 {% endif %}
 
+### After you apply a configuration
+
+When you apply a {% data variables.product.prodname_security_configuration %} to repositories, each repository enters a managed relationship with that configuration. That relationship can change over time. For example, if a repository admin overrides a security setting on an unenforced configuration, if an organization or enterprise admin detaches the configuration, if enforcement is enabled, or if the initial attachment fails. Each change is reflected in the repository's configuration status.
+
+For the full list of configuration statuses and recommended actions, see [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-statuses).
+
 ## About {% data variables.product.prodname_global_settings %}
 
 While {% data variables.product.prodname_security_configurations %} determine repository-level security settings, {% data variables.product.prodname_global_settings %} determine your organization-level security settings, which are then inherited by all repositories. With {% data variables.product.prodname_global_settings %}, you can customize how security features analyze your organization.

content/code-security/how-tos/secure-at-scale/configure-enterprise-security/establish-complete-coverage/applying-a-custom-security-configuration-to-your-enterprise.md

@@ -16,6 +16,8 @@ category:
 
 After you create a {% data variables.product.prodname_custom_security_configuration %}, you need to apply it to repositories in your enterprise to enable the configuration's settings on those repositories.
 
+The repository list displays each repository's configuration status. For the full list of statuses and recommended actions, see [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-statuses).
+
 {% data reusables.security-configurations.security-features-use-actions %}
 
 ## Applying your {% data variables.product.prodname_custom_security_configuration %} to repositories in your enterprise

content/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/applying-a-custom-security-configuration.md

@@ -15,9 +15,7 @@ category:
   - Secure at scale
 ---
 
-## About applying a {% data variables.product.prodname_custom_security_configuration %}
-
-After you create a {% data variables.product.prodname_custom_security_configuration %}, you need to apply it to repositories in your organization to enable the configuration's settings on those repositories. To learn how to create a {% data variables.product.prodname_custom_security_configuration %}, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration).
+To learn how to create a {% data variables.product.prodname_custom_security_configuration %}, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration).
 
 ## Applying your {% data variables.product.prodname_custom_security_configuration %} to repositories in your organization
 
@@ -36,6 +34,8 @@ After you create a {% data variables.product.prodname_custom_security_configurat
 >[!NOTE]
 > If you apply an enforced configuration, this information is reported in the list of repositories. An enforced configuration means that repository owners are blocked from changing features that have been enabled or disabled in the configuration, but features that are not set aren't enforced.
 
+After you apply a configuration, each repository's configuration status reflects the result of the operation—for example, `attached`, `attaching`, or `failed`. For the full list of statuses and recommended actions, see [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-statuses).
+
 ## Next steps
 
 To learn how to monitor security alerts in your organization, see [AUTOTITLE](/code-security/how-tos/view-and-interpret-data/analyze-organization-data/find-insecure-repositories).

content/code-security/how-tos/secure-at-scale/configure-organization-security/manage-your-coverage/detaching-repositories-from-their-security-configurations.md

@@ -22,6 +22,8 @@ Alternatively, if you want to apply a {% data variables.product.prodname_securit
 
 ## Detaching repositories from linked {% data variables.product.prodname_security_configurations %}
 
+Detached repositories show a status of "No configuration" in the repository table on the {% data variables.product.prodname_security_configurations %} settings page. For more information about all configuration statuses, see [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-statuses).
+
 {% data reusables.profile.access_org %}
 {% data reusables.organizations.org_settings %}
 {% data reusables.security-configurations.view-configurations-page %}

content/code-security/reference/security-at-scale/index.md

@@ -11,5 +11,6 @@ children:
   - /security-overview-dashboard-metrics
   - /available-filters-for-security-overview
   - /security-configuration-enforcement
+  - /security-configuration-statuses
   - /troubleshoot-security-configurations
 ---

content/code-security/reference/security-at-scale/security-configuration-statuses.md

@@ -0,0 +1,52 @@
+---
+title: Security configuration statuses
+shortTitle: Configuration statuses
+intro: 'Each repository that has a {% data variables.product.prodname_security_configuration %} applied to it has a configuration status that reflects the current state of the relationship between the repository and the configuration.'
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '*'
+contentType: reference
+category:
+  - Secure at scale
+---
+
+A repository's configuration status tells you the current state of its relationship with the applied {% data variables.product.prodname_security_configuration %}. That relationship can change over time—for example, when a repository admin overrides a setting, an admin enables enforcement, or an attachment fails. For more about how configurations and repositories interact, see [AUTOTITLE](/code-security/concepts/security-at-scale/about-enabling-security-features-at-scale).
+
+You can view configuration statuses in the repository table on your organization's {% data variables.product.prodname_security_configurations %} settings page, or retrieve them with the REST API. For more information, see [AUTOTITLE](/code-security/how-tos/secure-at-scale/configure-organization-security/manage-your-coverage/filtering-repositories-in-your-organization-using-the-repository-table) and [AUTOTITLE](/rest/code-security/configurations).
+
+## Configuration status reference
+
+The following table describes all configuration statuses, what causes each status, how each appears in the organization settings repository table, and the recommended action.
+
+In the repository table, the "Configuration status" filter supports "Attached," "Removed," "Failed," "Enforced," and "Removed by enterprise." Repositories with a `detached` status appear as "No configuration" and are not filterable by configuration status in the UI. However, the REST API's `status` parameter does accept `detached` when listing repositories for an organization-level configuration.
+
+| Status | Description | Cause | UI display | Recommended action |
+|---|---|---|---|---|
+| `attached` | The configuration is actively applied. The repository inherits all settings from the configuration. | An organization or enterprise admin applied the configuration to the repository. | The configuration name (for example, "My config") | No action needed. |
+| `attaching` | The configuration is being applied. This is a transient state. | An organization or enterprise admin just applied the configuration. | {% octicon "clock" aria-label="Applying" %} Applying CONFIGURATION-NAME | Wait for the operation to complete. If the status does not change, check for attachment failures. |
+| `updating` | The configuration is being updated on the repository. | An organization or enterprise admin changed a setting in the configuration. | {% octicon "clock" aria-label="Updating" %} Updating CONFIGURATION-NAME | Wait for the update to complete. |
+| `enforced` | The configuration is actively applied and enforced. Repository admins cannot change the enablement status of features controlled by the configuration. | An organization or enterprise admin enabled enforcement on the configuration. | {% octicon "shield" aria-label="Enforced" %} Enforced CONFIGURATION-NAME | No action needed. For more information, see [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-enforcement). |
+| `removed` | A repository-level setting was changed that conflicts with the configuration. The configuration is still associated with the repository, but the repository no longer inherits all settings. | A repository admin changed a security setting on an unenforced configuration. | {% octicon "alert" aria-label="Removed" %} Removed CONFIGURATION-NAME | To restore the intended settings, re-apply the configuration in the "{% data variables.product.prodname_AS %}" page of the repository. To prevent future overrides, consider enabling enforcement. |
+| `removed_by_enterprise` | An enterprise-level configuration change caused a conflict with the repository's settings. | An enterprise admin changed a setting that conflicts with the organization-level configuration applied to the repository. | {% octicon "alert" aria-label="Removed" %} Removed CONFIGURATION-NAME | Coordinate with your enterprise admin to resolve the conflict. Re-apply the configuration at the organization or enterprise level. |
+| `failed` | The configuration could not be attached to the repository. | A conflict between existing repository settings and the configuration prevented attachment. | {% octicon "alert" aria-label="Failed" %} Failed REASON | Filter by `config-status:failed` in the repository table, then follow the remediation guidance for the specific repository. For more information, see [AUTOTITLE](/code-security/reference/security-at-scale/troubleshoot-security-configurations/diagnosing-security-configuration-issues). |
+| `detached` | No configuration is applied. The repository's security settings are managed individually. | An organization admin detached the configuration, or the repository was never attached to a configuration. | No configuration | Apply a configuration if you want the repository to inherit centrally managed settings. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). |
+
+## Understanding `removed` vs. `detached`
+
+These statuses reflect different situations:
+
+* **`removed`**: A repository admin changed a security setting that conflicts with an unenforced configuration. The configuration is still associated with the repository, but the repository no longer counts toward your organization's coverage metrics for that configuration. Re-applying the configuration restores the relationship.
+* **`detached`**: The configuration is fully disconnected from the repository. The repository's existing security settings are unchanged, but no configuration manages them. To restore centrally managed settings, apply a new configuration.
+
+To prevent repositories from reaching a `removed` status, enable enforcement on the configuration. For more information, see [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-enforcement).
+
+## Tracking configuration status changes with the audit log
+
+Your organization's audit log records `repository_security_configuration` events whenever a configuration status changes. You can search for these events using the `action:repository_security_configuration` filter. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization#repository_security_configuration){% ifversion ghec or ghes %} and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise){% endif %}.
+
+## Further reading
+
+* [AUTOTITLE](/code-security/concepts/security-at-scale/about-enabling-security-features-at-scale)
+* [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-enforcement)
+* [AUTOTITLE](/code-security/reference/security-at-scale/troubleshoot-security-configurations/diagnosing-security-configuration-issues)

content/code-security/reference/security-at-scale/troubleshoot-security-configurations/diagnosing-security-configuration-issues.md

@@ -0,0 +1,60 @@
+---
+title: Diagnosing security configuration issues
+shortTitle: Diagnose configuration issues
+intro: Identify repositories where the security configuration could not be attached, or where the configuration relationship has changed, and follow guidance to remediate the problem.
+permissions: '{% data reusables.permissions.security-org-enable %}'
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '*'
+redirect_from:
+  - /code-security/securing-your-organization/managing-the-security-of-your-organization/finding-repositories-with-attachment-failures
+  - /code-security/how-tos/secure-at-scale/troubleshoot-security-configurations/finding-repositories-with-attachment-failures
+  - /code-security/reference/security-at-scale/troubleshoot-security-configurations/finding-repositories-with-attachment-failures
+contentType: reference
+category:
+  - Troubleshoot security tools
+---
+
+## Finding and remediating attachment failures
+
+When you apply a configuration to a group of repositories, some repositories may fail to attach, typically because of a conflict between existing repository settings and the configuration you applied. When this happens, only some settings are applied to the affected repositories, and those repositories won't inherit future changes to the configuration.
+
+On the security configuration settings page, in the **Repositories** tab under "Apply configurations", a banner shows how many repositories have an attachment failure and summarizes the reason. Click the link in the banner, or filter the repository list by `config-status:failed`, to see affected repositories and guidance on how to remediate each failure.
+
+{% data reusables.profile.access_org %}
+{% data reusables.organizations.org_settings %}
+{% data reusables.security-configurations.view-configurations-page %}
+1. Click the **Repositories** tab.
+1. In the "Apply configurations" section, filter by `config-status:failed`.
+1. From the results list, for the repository you're interested in, click **{% octicon "alert" aria-hidden="true" aria-label="alert" %} Failed REASON**.
+1. In the dialog box, review the information and follow the remediation guidance.
+
+## Finding and remediating removed configurations
+
+A repository's configuration status changes to `removed` when a repository admin changes a security setting that conflicts with the applied configuration. The configuration is still associated with the repository, but the repository no longer inherits all settings from the configuration.
+
+To find and remediate repositories with a `removed` status:
+
+{% data reusables.profile.access_org %}
+{% data reusables.organizations.org_settings %}
+{% data reusables.security-configurations.view-configurations-page %}
+1. Filter the repository list using the "Configuration status" filter and select "Removed."
+1. To restore the intended settings, re-apply the configuration to the affected repositories.
+1. To prevent future overrides, consider enabling enforcement on the configuration. See [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-enforcement).
+
+## Finding and remediating enterprise-removed configurations
+
+A repository's configuration status changes to `removed_by_enterprise` when an enterprise-level change conflicts with the organization-level configuration applied to the repository.
+
+To find and remediate repositories with a `removed_by_enterprise` status:
+
+{% data reusables.profile.access_org %}
+{% data reusables.organizations.org_settings %}
+{% data reusables.security-configurations.view-configurations-page %}
+1. Filter the repository list using the "Configuration status" filter and select "Removed by enterprise."
+1. Coordinate with your enterprise admin to resolve the conflict between the enterprise-level and organization-level configurations.
+1. Re-apply the configuration at the organization or enterprise level.
+
+For more information about all configuration statuses, see [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-statuses).
+

content/code-security/reference/security-at-scale/troubleshoot-security-configurations/finding-repositories-with-attachment-failures.md

@@ -10,7 +10,7 @@ children:
   - /a-repository-is-using-advanced-setup-for-code-scanning
   - /feature-disappears
   - /unexpected-default-setup
-  - /finding-repositories-with-attachment-failures
+  - /diagnosing-security-configuration-issues
   - /not-enough-github-advanced-security-licenses
 redirect_from:
   - /code-security/securing-your-organization/troubleshooting-security-configurations

content/code-security/reference/security-at-scale/troubleshoot-security-configurations/index.md

@@ -67,6 +67,8 @@ You may find it helpful to apply an enterprise security configuration to all rep
 
 For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration).
 
+After you apply a configuration, each repository's configuration status reflects the result. For example, a repository may show as `attached`, `attaching`, or `failed`. For a full list of statuses and recommended actions, see [AUTOTITLE](/code-security/reference/security-at-scale/security-configuration-statuses).
+
 ## Next steps
 
 Now that you have enabled the security features you want to test, you are ready to look more deeply into how {% data variables.product.prodname_GH_secret_protection %} and {% data variables.product.prodname_GH_code_security %} protect your code.