Description
Background
During the Docs Sync discussion, we identified recurring documentation updates related to GUID and sensitive identifier compliance.
Microsoft guidance:
The issue currently requires repeated downstream documentation fixes. However, the violations continue to reappear because the source content is not corrected and there is no validation preventing new violations from being introduced.
Evidence
The Docs team has repeatedly submitted SFI remediation pull requests to address the same class of issues.
Historical examples:
As discussed, fixing generated markdown files is only a temporary mitigation because future generations can overwrite those fixes.
Problem Statement
GUIDs, subscription IDs, tenant IDs, object IDs, and other sensitive identifiers are being propagated into documentation from upstream source content.
This results in:
- Recurring SFI remediation work
- Repeated documentation cleanup PRs
- Additional operational overhead for Docs and Engineering teams
- Compliance issues appearing release after release
Proposed Solution
Phase 1: One-time Source Remediation
Perform a repository-wide audit and remediate existing violations at the source.
Review and clean up identifiers in:
- Source code examples
- Help content
- Test assets
- Documentation source files
- Generated content inputs
- Command metadata
Replace non-compliant values with approved identifiers according to Microsoft guidance.
Phase 2: Add CI Guardrails
Introduce automated validation in Azure PowerShell (and other applicable repositories) to detect non-compliant identifiers during pull request validation and CI builds.
Validation should:
- Run on every PR
- Run in official CI pipelines
- Detect unapproved GUIDs and sensitive identifiers
- Fail validation when violations are detected
- Provide actionable remediation guidance
The goal is to ensure that developers cannot merge PRs containing non-compliant identifiers and that the issue is prevented before documentation generation.
Expected Outcome
- Existing violations are removed from source.
- Documentation generation no longer reintroduces known violations.
- Future violations are blocked during PR validation.
- Recurring SFI cleanup effort is significantly reduced.
References
Issue script & Debug output
Environment data
Module versions
Error output
Description
Background
During the Docs Sync discussion, we identified recurring documentation updates related to GUID and sensitive identifier compliance.
Microsoft guidance:
https://learn.microsoft.com/en-us/help/platform/reference-sensitive-identifier
The issue currently requires repeated downstream documentation fixes. However, the violations continue to reappear because the source content is not corrected and there is no validation preventing new violations from being introduced.
Evidence
The Docs team has repeatedly submitted SFI remediation pull requests to address the same class of issues.
Historical examples:
https://github.com/MicrosoftDocs/azure-docs-powershell/pulls?q=is%3Apr+Bundle-Security+is%3Aclosed
As discussed, fixing generated markdown files is only a temporary mitigation because future generations can overwrite those fixes.
Problem Statement
GUIDs, subscription IDs, tenant IDs, object IDs, and other sensitive identifiers are being propagated into documentation from upstream source content.
This results in:
Proposed Solution
Phase 1: One-time Source Remediation
Perform a repository-wide audit and remediate existing violations at the source.
Review and clean up identifiers in:
Replace non-compliant values with approved identifiers according to Microsoft guidance.
Phase 2: Add CI Guardrails
Introduce automated validation in Azure PowerShell (and other applicable repositories) to detect non-compliant identifiers during pull request validation and CI builds.
Validation should:
The goal is to ensure that developers cannot merge PRs containing non-compliant identifiers and that the issue is prevented before documentation generation.
Expected Outcome
References
Sensitive Identifier Reference
https://learn.microsoft.com/en-us/help/platform/reference-sensitive-identifier
Historical SFI Remediation PRs
https://github.com/MicrosoftDocs/azure-docs-powershell/pulls?q=is%3Apr+Bundle-Security+is%3Aclosed
``
Issue script & Debug output
Environment data
PS7.0Module versions
Error output