docs(enterprise): consolidate governance into a 5-phase ramp + surface lifecycle scripts#1951
Merged
Merged
Conversation
The enterprise/lifecycle-scripts page existed and was cross-linked from security and the CLI reference, but was missing from the Enterprise sidebar group so it had no nav entry. Add it after security-and-supply-chain. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The enterprise section had sprawled to 16 pages with two contradictory order-1 entry maps (index + governance-overview), duplicate security pages, and split policy-intro pages. Reshape into a single Overview map plus Decide/Secure/Author/Enforce/Operate sub-groups (16 -> 13 pages): - Rewrite index.md as the sole canonical map; retire governance-overview - Merge security-and-supply-chain into security; merge apm-policy-getting-started into apm-policy - Retitle governance-guide -> Governance deep-dive (Operate) - Lifecycle scripts now lives under Secure - Add 3 redirects + rewrite internal xrefs and labels Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR consolidates and simplifies the Enterprise/Governance documentation IA by removing duplicate entry points, merging redundant pages into canonical equivalents, updating cross-references across the docs corpus, and wiring the new structure into the Starlight sidebar and legacy redirects.
Changes:
- Reorganizes the Enterprise section into a single Overview journey map with five phase groupings (Decide / Secure / Author policy / Enforce / Operate).
- Merges and retires duplicated pages (notably
security-and-supply-chain->security, andapm-policy-getting-started-> a “Get started in 20 minutes” section withinapm-policy), and removes the redundant Governance overview page. - Updates internal links and adds Astro redirects + sidebar structure to keep legacy URLs functional and to surface the lifecycle scripts page in navigation.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/troubleshooting/ssl-issues.md | Updates references from the retired security page to the new canonical security model page. |
| docs/src/content/docs/troubleshooting/policy-debugging.md | Updates enterprise/governance cross-links to the new “deep-dive” and consolidated policy page. |
| docs/src/content/docs/reference/policy-schema.md | Retargets “workflow/governance context” links to the consolidated enterprise pages. |
| docs/src/content/docs/reference/environment-variables.md | Updates security guidance cross-links to the canonical security model page. |
| docs/src/content/docs/reference/cli/policy.md | Retargets “Governance” and “getting started” references to the consolidated enterprise pages. |
| docs/src/content/docs/reference/cli/lock.md | Updates SBOM model links to the new canonical SBOM section on the security model page. |
| docs/src/content/docs/reference/cli/lifecycle.md | Updates security-model cross-link label/target for lifecycle script security context. |
| docs/src/content/docs/producer/publish-to-a-marketplace.md | Updates governance cross-link to the renamed “Governance deep-dive” page. |
| docs/src/content/docs/enterprise/security.md | Pulls in/extends threat model + SBOM + hardening content as the canonical security page. |
| docs/src/content/docs/enterprise/security-and-supply-chain.md | Removes the redundant page (now merged into enterprise/security.md). |
| docs/src/content/docs/enterprise/registry-proxy.md | Updates governance deep-dive references after IA consolidation. |
| docs/src/content/docs/enterprise/policy-pilot.md | Updates governance deep-dive references after IA consolidation. |
| docs/src/content/docs/enterprise/index.md | Rewrites the Enterprise entry page into the single canonical journey map with 5 phases. |
| docs/src/content/docs/enterprise/governance-overview.md | Removes the redundant overview/map page (entry map now lives in enterprise/index.md). |
| docs/src/content/docs/enterprise/governance-guide.md | Retitles the governance guide to “Governance deep-dive” and relies on sidebar grouping for nav. |
| docs/src/content/docs/enterprise/github-rulesets.md | Updates governance references to the new “deep-dive” page. |
| docs/src/content/docs/enterprise/enforce-in-ci.md | Updates cross-links to the new governance/policy canonical pages. |
| docs/src/content/docs/enterprise/drift-detection.md | Updates security model references after the security-page merge. |
| docs/src/content/docs/enterprise/apm-policy.md | Absorbs “getting started” content into the canonical Policy Files page. |
| docs/src/content/docs/enterprise/apm-policy-getting-started.md | Removes the standalone getting-started page (content moved into enterprise/apm-policy.md). |
| docs/src/content/docs/enterprise/adoption-playbook.md | Updates governance/security/policy references to canonical pages. |
| docs/src/content/docs/consumer/governance-on-the-consumer-ramp.md | Updates governance deep-dive reference for policy authors. |
| docs/src/content/docs/consumer/drift-and-secure-by-default.md | Updates security model reference after the security-page merge. |
| docs/src/content/docs/concepts/what-is-apm.md | Updates enterprise governance cross-link to the new canonical governance deep-dive page. |
| docs/astro.config.mjs | Adds redirects for retired enterprise pages and updates the Enterprise sidebar into 5 grouped phases. |
Review details
- Files reviewed: 25/25 changed files
- Comments generated: 6
- Review effort level: Low
| see [Governance overview](../enterprise/governance-overview/) and | ||
| [APM policy: getting started](../enterprise/apm-policy-getting-started/). | ||
| see [Governance deep-dive](../enterprise/governance-guide/) and | ||
| [APM policy: getting started](../enterprise/apm-policy/). |
| - [Governance deep-dive](../../../enterprise/governance-guide/) -- | ||
| how policy fits the broader enterprise governance model. | ||
| - [APM policy: getting started](../../../enterprise/apm-policy-getting-started/) | ||
| - [APM policy: getting started](../../../enterprise/apm-policy/) |
Comment on lines
+14
to
+15
| playbook, see [Governance deep-dive](./governance-guide/) and | ||
| [apm-policy getting started](./apm-policy/). |
Comment on lines
+76
to
77
| `enforcement: warn`. See [Get started with apm-policy.yml](./apm-policy/) for the mental | ||
| model and [Policy Reference](./policy-reference/) for fields. |
Comment on lines
+209
to
210
| - [Get started with apm-policy.yml](./apm-policy/) and [Policy Reference](./policy-reference/) | ||
| -- what to put in `apm-policy.yml` for Phase 2 and Phase 3. |
|
|
||
| ## Policy gates that block install | ||
|
|
||
| `apm-policy.yml` is evaluated before any download or write. The install preflight walks the resolved dependency graph -- including transitive MCP servers -- and fails the install if a dep is not in the allow list, falls under a deny rule, uses a forbidden source/scope, or violates a configured trust rule. In CI, `apm audit --ci` runs the same baseline plus policy checks (allow/deny lists, target restrictions, MCP transport restrictions). Tighten-only inheritance (enterprise -> org -> repo) is enforced so a downstream layer can never loosen an upstream rule. See [Get started with apm-policy.yml](./apm-policy/) and [Policy Reference](./policy-reference/). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
The enterprise/governance docs had sprawled to 16 pages with two contradictory entry maps, duplicate security pages, and split policy intros. This reshapes them into a single Overview plus five sub-groups (Decide / Secure / Author policy / Enforce / Operate), 16 -> 13 pages, and adds the previously orphaned lifecycle-scripts page to the sidebar.
Problem
sidebar order: 1entry pages (index.md+governance-overview.md) with disjoint, contradictory section maps.security+security-and-supply-chain;apm-policy+apm-policy-getting-started.enterprise/lifecycle-scripts.mdexisted and was cross-linked but had no sidebar entry.Changes
security-and-supply-chain->security(471 lines, SBOM anchor preserved);apm-policy-getting-started->apm-policy(275 lines, "Get started in 20 minutes" section).governance-overview;index.mdrewritten as the single canonical journey map.governance-guide-> "Governance deep-dive" (Operate).Validation
Starlight build passes: 121 pages, all internal links + anchors valid. ASCII-only additions.
Test
cd docs && npm run build-- expect "All internal links are valid."