chore: promote Secure to top-level Antora module (JTBD Phase 2) (#3134) (#3156)

mkuznyetsov · gtrivedi88 · cursoragent · web-flow · commit cf3a5226ba8a · 2026-07-06T13:38:28.000+03:00
* chore: promote Secure to top-level Antora module (JTBD Phase 2)

Move security content from Administration Guide into a new
modules/secure/ Antora module, following the CCS 'Secure' category:
'Implement security controls and ensure compliance.'

- Create modules/secure/ with nav and 12 pages
- Move security-best-practices, OAuth provider pages (6), identity
  management, authorization, GDPR compliance from admin-guide
- Add page-aliases for backward-compatible redirects
- Apply JTBD titles from downstream audit:
  "Protect your deployment", "Give developers credential-free Git
  access", "Control who can access {prod-short}", etc.
- Update cross-module xrefs in install, end-user-guide, discover
- Remove security sections from admin-guide nav
- Add modules/secure/nav.adoc to antora.yml

Mirrors downstream devspaces-documentation Secure guide structure.



* fix: move OAuth for Git providers back to Administration Guide

SME feedback: OAuth configuration is a day-1 admin setup task,
not a security hardening concern. Keep it in the Administration
Guide where admins expect to find it.

Moved 7 OAuth pages from modules/secure/pages/ back to
modules/administration-guide/pages/. Updated nav.adoc for both
modules and 3 cross-module xrefs (secure: -&gt; administration-guide:).

Secure module retains: security best practices, identity management,
cluster roles, advanced authorization, GDPR compliance.



* fix: replace pass:[] Vale pragmas with passthrough blocks to fix RedHat.Spacing errors

* fix: remove self-referencing page-aliases from OAuth files

* fix: remove self-referencing page-aliases from GitLab OAuth file

* fix: remove self-referencing page-aliases from Azure DevOps OAuth file

* fix: add cross-module prefixes for includes and xrefs in secure module pages

* fix: add cross-module xref prefix in configuring-advanced-authorization

* fix: add cross-module xref prefixes in GDPR compliance page

* fix: add cross-module prefixes for includes and xrefs in security-best-practices

* feat: add persona callouts to Secure module using partials

- Per-page admin persona callout via discover:partial$snip_persona-admin.adoc
  in all 5 secure pages



* fix: use local secure partial instead of cross-module discover:partial



* fix: remove persona partial from thin wrapper page (level-0 heading conflict)

configuring-cluster-roles-for-users.adoc is a thin wrapper that includes
the full page content from administration-guide example snippet. Adding
a persona partial before that creates two level-0 headings, which breaks
Antora. The guide-level callout in the nav/master provides the persona
signal for this page.



* fix: revert OAuth title to factual 'Configuring OAuth for Git providers'

SME feedback: JTBD title 'Give developers credential-free Git access'
is inaccurate (OAuth still uses credentials) and not findable for
admins searching for 'OAuth' or 'GitHub configuration'.



* fix: apply JTBD navtitle for cluster roles page

Change navtitle from "Configuring cluster roles for users" to
"Grant additional permissions to users" to match downstream JTBD title.



* fix: sync navtitle attributes with JTBD page titles in Secure



---------

Co-authored-by: Gaurav Trivedi &lt;90042568+gtrivedi88@users.noreply.github.com&gt;
Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/antora.yml b/antora.yml
@@ -9,6 +9,7 @@ nav:
   - modules/install/nav.adoc
   - modules/end-user-guide/nav.adoc
   - modules/upgrade/nav.adoc
+  - modules/secure/nav.adoc
   - modules/optimize/nav.adoc
   - modules/administration-guide/nav.adoc
   - modules/extensions/nav.adoc
diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc
@@ -1,6 +1,5 @@
 .Administration Guide
 
-* xref:security-best-practices.adoc[]
 * xref:configuring-che.adoc[]
 ** xref:understanding-the-checluster-custom-resource.adoc[]
 *** xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[]
@@ -52,17 +51,13 @@
 *** xref:configuring-ai-providers.adoc[]
 **** xref:ai-provider-api-key-secret-reference.adoc[]
 *** xref:customizing-openshift-che-branding-images.adoc[]
-** xref:managing-identities-and-authorizations.adoc[]
-*** xref:configuring-oauth-for-git-providers.adoc[]
-**** xref:configuring-oauth-2-for-github.adoc[]
-**** xref:configuring-oauth-2-for-gitlab.adoc[]
-**** xref:configuring-oauth-2-for-a-bitbucket-server.adoc[]
-**** xref:configuring-oauth-2-for-the-bitbucket-cloud.adoc[]
-**** xref:configuring-oauth-1-for-a-bitbucket-server.adoc[]
-**** xref:configuring-oauth-2-for-microsoft-azure-devops-services.adoc[]
-*** xref:configuring-cluster-roles-for-users.adoc[]
-*** xref:configuring-advanced-authorization.adoc[]
-*** xref:removing-user-data-in-compliance-with-the-gdpr.adoc[]
+** xref:configuring-oauth-for-git-providers.adoc[]
+*** xref:configuring-oauth-2-for-github.adoc[]
+*** xref:configuring-oauth-2-for-gitlab.adoc[]
+*** xref:configuring-oauth-2-for-a-bitbucket-server.adoc[]
+*** xref:configuring-oauth-2-for-the-bitbucket-cloud.adoc[]
+*** xref:configuring-oauth-1-for-a-bitbucket-server.adoc[]
+*** xref:configuring-oauth-2-for-microsoft-azure-devops-services.adoc[]
 ** xref:configuring-fuse.adoc[]
 *** xref:enabling-access-to-dev-fuse-for-openshift.adoc[]
 *** xref:enabling-fuse-for-all-workspaces.adoc[]
diff --git a/modules/administration-guide/pages/configuring-cluster-roles-for-users.adoc b/modules/administration-guide/pages/configuring-cluster-roles-for-users.adoc
diff --git a/modules/administration-guide/pages/configuring-oauth-2-for-microsoft-azure-devops-services.adoc b/modules/administration-guide/pages/configuring-oauth-2-for-microsoft-azure-devops-services.adoc
@@ -7,11 +7,15 @@
 [id="configuring-oauth-2-for-microsoft-azure-devops-services"]
 = Configuring OAuth 2.0 for Microsoft Azure DevOps Services
 
-pass:[<!-- vale RedHat.Spelling = NO -->]
+++++
+<!-- vale RedHat.Spelling = NO -->
+++++
 
 To enable users to work with a remote Git repository that is hosted on Microsoft Azure Repos:
 
-pass:[<!-- vale RedHat.Spelling = YES -->]
+++++
+<!-- vale RedHat.Spelling = YES -->
+++++
 
 . Set up an application in Microsoft Entra ID.
 . Apply the Microsoft Entra ID App Secret.
diff --git a/modules/administration-guide/pages/managing-identities-and-authorizations.adoc b/modules/administration-guide/pages/managing-identities-and-authorizations.adoc
diff --git a/modules/discover/pages/gateway.adoc b/modules/discover/pages/gateway.adoc
@@ -34,4 +34,4 @@ image::architecture/{project-context}-gateway-interactions.png[{prod-short} gate
     
 .Additional resources
 
-* xref:administration-guide:managing-identities-and-authorizations.adoc[]
+* xref:secure:managing-identities-and-authorizations.adoc[]
diff --git a/modules/secure/nav.adoc b/modules/secure/nav.adoc
@@ -0,0 +1,6 @@
+.Secure
+* xref:security-best-practices.adoc[]
+* xref:managing-identities-and-authorizations.adoc[]
+** xref:configuring-cluster-roles-for-users.adoc[]
+** xref:configuring-advanced-authorization.adoc[]
+** xref:removing-user-data-in-compliance-with-the-gdpr.adoc[]
diff --git a/modules/secure/pages/configuring-advanced-authorization.adoc b/modules/secure/pages/configuring-advanced-authorization.adoc
@@ -1,21 +1,23 @@
 :_content-type: PROCEDURE
 :description: Configuring advanced authorization
 :keywords: authorization, user, group
-:navtitle: Configuring advanced authorization
+:navtitle: Restrict access to specific users and groups
 // :page-aliases:
 
 [id="configuring-advanced-authorization"]
-= Configuring advanced authorization
+= Restrict access to specific users and groups
 
 You can determine which users and groups are allowed to access {prod-short}.
 
+include::partial$snip_persona-admin.adoc[]
+
 .Prerequisites
 
 * An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
 
 .Procedure
 
-. Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
+. Configure the `CheCluster` Custom Resource. See xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
 +
 [source,yaml,subs="+quotes,+attributes"]
 ----
diff --git a/modules/secure/pages/configuring-cluster-roles-for-users.adoc b/modules/secure/pages/configuring-cluster-roles-for-users.adoc
@@ -0,0 +1,8 @@
+:_content-type: PROCEDURE
+:description: Configuring cluster roles for {prod-short} users
+:keywords: administration-guide, user, roles, permissions
+:navtitle: Grant additional permissions to users
+:page-aliases: administration-guide:configuring-cluster-roles-for-users.adoc
+
+
+include::administration-guide:example$snip_{project-context}-configuring-cluster-roles-for-users.adoc[]
diff --git a/modules/secure/pages/managing-identities-and-authorizations.adoc b/modules/secure/pages/managing-identities-and-authorizations.adoc
@@ -0,0 +1,12 @@
+:_content-type: ASSEMBLY
+:description: Managing identities and authorizations
+:keywords: administration-guide, managing-identities-and-authorizations
+:navtitle: Control who can access {prod-short}
+:page-aliases: administration-guide:managing-identities-and-authorizations.adoc, .:managing-identities-and-authorizations.adoc, authenticating-users.adoc, authorizing-users.adoc, configuring-authorization.adoc, configuring-openshift-oauth.adoc, configuring-minikube-github-authentication.adoc
+
+[id="managing-identities-and-authorizations"]
+= Control who can access {prod-short}
+
+This section describes different aspects of managing identities and authorizations of {prod}.
+
+include::partial$snip_persona-admin.adoc[]
diff --git a/modules/secure/pages/removing-user-data-in-compliance-with-the-gdpr.adoc b/modules/secure/pages/removing-user-data-in-compliance-with-the-gdpr.adoc
@@ -1,14 +1,16 @@
 :_content-type: PROCEDURE
 :description: Removing user data in compliance with the GDPR
 :keywords: administration-guide, user-data, gdpr, remove-data
-:navtitle: Removing user data in compliance with the GDPR
-:page-aliases: .:removing-user-data.adoc, removing-user-data.adoc
+:navtitle: Remove user data for GDPR compliance
+:page-aliases: administration-guide:removing-user-data-in-compliance-with-the-gdpr.adoc, .:removing-user-data.adoc, removing-user-data.adoc
 
 [id="removing-user-data-in-compliance-with-the-gdpr"]
-= Removing user data in compliance with the GDPR
+= Remove user data for GDPR compliance
 
 You can remove a user’s data on {ocp} in compliance with the link:https://gdpr.eu/[General Data Protection Regulation (GDPR)] that enforces the right of individuals to have their personal data erased. The process for other {kubernetes} infrastructures might vary. Follow the user management best practices of the provider you are using for the {prod} installation.
 
+include::partial$snip_persona-admin.adoc[]
+
 WARNING: Removing user data as follows is irreversible! All removed data is deleted and unrecoverable!
 
 .Prerequisites
@@ -34,6 +36,6 @@ $ oc delete user <username>
 
 .Additional resources
 
-* xref:managing-workloads-using-the-che-server-api.adoc[]
-* xref:configuring-workspace-target-namespace.adoc[]
+* xref:administration-guide:managing-workloads-using-the-che-server-api.adoc[]
+* xref:administration-guide:configuring-workspace-target-namespace.adoc[]
 * xref:install:proc_uninstalling-che.adoc[]
diff --git a/modules/secure/pages/security-best-practices.adoc b/modules/secure/pages/security-best-practices.adoc
@@ -1,15 +1,17 @@
 :_content-type: CONCEPT
 :description: Security best practices
 :keywords: security, best practices
-:navtitle: Security best practices
+:navtitle: Protect your deployment
 //:page-aliases:
 
 [id="security-best-practices"]
-= Security best practices for {prod}
+= Protect your deployment
 
 Get an overview of key best security practices for {prod} that can help you
 foster a more resilient development environment.
 
+include::partial$snip_persona-admin.adoc[]
+
 {prod} runs on top of OpenShift, which provides the platform, and the foundation for the products functioning on top of it. OpenShift documentation is the entry point for security hardening.
 
 .Project isolation in OpenShift
@@ -24,7 +26,7 @@ devEnvironments:
   defaultNamespace:
     autoProvision: false
 ----
-include::example$snip_che-curated-access.adoc[]
+include::administration-guide:example$snip_che-curated-access.adoc[]
 
 .Role-based access control (RBAC)
 
@@ -96,7 +98,7 @@ All resources and actions you can grant users permission to use in their {namesp
 |"get", "create", "delete", "list", "update", "patch", "watch"
 |===
 
-include::example$snip_che-user-granted-permission.adoc[]
+include::administration-guide:example$snip_che-user-granted-permission.adoc[]
 
 
 .Dev environment isolation
@@ -238,7 +240,7 @@ When configuring network policies for {prod},
 ensure that pods in the {prod-short} namespace can still communicate with pods in user namespaces,
 as this is required for proper functionality.
 
-For detailed instructions on implementing network policies with {prod}, see xref:configuring-network-policies.adoc[].
+For detailed instructions on implementing network policies with {prod}, see xref:administration-guide:configuring-network-policies.adoc[].
 
 .Disconnected environment
 
@@ -260,7 +262,7 @@ Open Source editor.
 Alternatively, cluster administrators can specify a different plugin registry in the Custom Resource, for example
 https://open-vsx.org that contains thousands of extensions.
 They can also build a custom Open VSX registry.
-include::example$snip_che-managing-extensions.adoc[]
+include::administration-guide:example$snip_che-managing-extensions.adoc[]
 
 [IMPORTANT]
 ====
diff --git a/modules/secure/partials/snip_persona-admin.adoc b/modules/secure/partials/snip_persona-admin.adoc
@@ -0,0 +1 @@
+This page is for platform administrators who install, configure, and manage {prod-short} on {orch-name} clusters. To learn more about common roles and example tasks referenced in {prod-short} documentation, see xref:discover:roles-and-tasks.adoc[].

Original file line number	Diff line number	Diff line change
`@@ -34,4 +34,4 @@ image::architecture/{project-context}-gateway-interactions.png[{prod-short} gate`
`34`	`34`
`35`	`35`	`.Additional resources`
`36`	`36`
`37`		`-* xref:administration-guide:managing-identities-and-authorizations.adoc[]`
	`37`	`+* xref:secure:managing-identities-and-authorizations.adoc[]`