From 065aa2c6510f5dc5502305c84a01ef3d3551f612 Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Mon, 24 Aug 2026 19:58:04 +0530 Subject: [PATCH 1/2] chore: promote Develop to top-level Antora module (JTBD Phase 3) Move developer-facing content from end-user-guide to a new top-level modules/develop/ Antora module. Apply JTBD titles, CQA formatting, and zero-content-loss restructuring for Claude Code persistence files. Co-authored-by: Cursor --- .vale/styles/.placeholder | 0 antora.yml | 1 + .../ai-provider-api-key-secret-reference.adoc | 10 +- .../pages/configuring-a-user-namespace.adoc | 12 +-- .../pages/configuring-ai-providers.adoc | 2 +- .../pages/configuring-fuse.adoc | 2 +- .../configuring-the-storage-strategy.adoc | 2 +- .../pages/devworkspace-backup.adoc | 4 +- ...ling-access-to-dev-fuse-for-openshift.adoc | 2 +- ...de-selection-with-the-che-editor-file.adoc | 0 ...che-prod-editor-file-to-select-an-ide.adoc | 0 .../snip_che-ide-default-yaml-file.adoc | 0 .../snip_che-supported-languages.adoc | 0 ...ub-action-yaml-example-activity-types.adoc | 0 .../snip_github-action-yaml-example.adoc | 0 .../images/contribute.svg | 0 .../images/github-action-comment.png | Bin .../images/github-action-status-check.png | Bin .../vscode-remote/cli-create-tunnel.png | Bin .../confirm-opening-vscode-desktop.png | Bin .../vscode-remote/login-with-provider.png | Bin .../images/vscode-remote/login.png | Bin .../vscode-remote/open-visual-studio-code.png | Bin .../images/vscode-remote/select-editor.png | Bin .../vscode-remote/vscode-remote-explorer.png | Bin .../images/workspace-backup/backups_tab.png | Bin .../workspace-backup/restore_section_1.png | Bin .../workspace-backup/restore_section_2.png | Bin modules/develop/nav.adoc | 51 +++++++++ .../pages/accessing-fuse.adoc | 0 ...nefits-of-pull-requests-review-in-che.adoc | 2 +- .../changing-the-ai-tool-on-a-workspace.adoc | 2 +- .../configuring-an-ai-provider-api-key.adoc | 2 +- ...t-visual-studio-code-to-che-workspace.adoc | 1 + .../pages/creating-image-pull-secrets.adoc | 0 .../customizing-workspace-components.adoc | 2 +- .../pages/defining-a-common-ide.adoc | 0 .../pages/devfile-introduction.adoc | 1 + ...stribute-claude-code-skills-with-lola.adoc | 14 +-- .../enabling-overlay-with-a-configmap.adoc | 2 +- .../pages/first-time-contributors.adoc | 2 +- .../pages/ides-in-workspaces.adoc | 0 ...ft-visual-studio-code-open-source-ide.adoc | 2 +- .../pages/mounting-configmaps.adoc | 0 .../pages/mounting-git-configuration.adoc | 4 +- .../pages/mounting-secrets.adoc | 0 .../pages/mounting-ssh-configuration.adoc | 0 ...the-urls-for-starting-a-new-workspace.adoc | 0 .../persist-claude-code-configuration.adoc | 42 +++++++- ...roc-restoring-a-workspace-from-backup.adoc | 0 ...proc-viewing-backups-in-the-dashboard.adoc | 0 ...pace-idling-for-long-running-commands.adoc | 0 ...ing-persistent-storage-for-workspaces.adoc | 0 .../restoring-workspaces-from-backups.adoc | 0 .../running-containers-with-kubedock.adoc | 0 ...claude-code-configuration-with-gitops.adoc | 16 +-- ...e-configuration-with-pvc-direct-mount.adoc | 41 +------- ...-code-configuration-with-pvc-tmp-copy.adoc | 39 +------ ...ng-a-workspace-from-a-raw-devfile-url.adoc | 0 ...claude-code-configuration-persistence.adoc | 99 ++++++++---------- .../pages/try-in-web-ide-github-action.adoc | 0 .../pages/url-parameter-concatenation.adoc | 0 .../url-parameter-for-additional-remotes.adoc | 0 .../url-parameter-for-container-image.adoc | 0 .../pages/url-parameter-for-cpu-limit.adoc | 0 .../pages/url-parameter-for-memory-limit.adoc | 0 ...ter-for-starting-duplicate-workspaces.adoc | 0 .../url-parameter-for-the-ai-provider.adoc | 0 ...l-parameter-for-the-devfile-file-name.adoc | 0 ...l-parameter-for-the-devfile-file-path.adoc | 0 ...meter-for-the-existing-workspace-name.adoc | 0 .../url-parameter-for-the-ide-image.adoc | 0 .../pages/url-parameter-for-the-ide.adoc | 0 ...l-parameter-for-the-workspace-storage.adoc | 0 .../using-ai-assistants-in-workspaces.adoc | 2 +- .../pages/using-che-in-team-workflow.adoc | 0 ...ials-and-configurations-in-workspaces.adoc | 2 +- ...using-the-fuse-overlay-storage-driver.adoc | 0 ...assembly_try-in-web-ide-github-action.adoc | 0 ...ction-to-a-github-repository-workflow.adoc | 0 ...-code-extensions-at-workspace-startup.adoc | 2 +- ...ge-pull-secret-from-a-.dockercfg-file.adoc | 0 ...e-pull-secret-from-a-config.json-file.adoc | 0 ...reating-an-image-pull-secret-with-cli.adoc | 0 .../partials/proc_providing-a-devfile.adoc | 0 ...sting-persistent-storage-in-a-devfile.adoc | 0 ...equesting-persistent-storage-in-a-pvc.adoc | 0 .../proc_setting-up-che-editor-yaml.adoc | 2 +- ...ef_about-try-in-web-ide-github-action.adoc | 0 .../ref_parameters-for-che-editor-yaml.adoc | 0 modules/discover/pages/roles-and-tasks.adoc | 4 +- modules/end-user-guide/nav.adoc | 66 ++---------- ...a-workspace-from-a-git-repository-url.adoc | 6 +- .../using-a-git-provider-access-token.adoc | 4 +- .../secure/pages/security-best-practices.adoc | 10 +- .../pages/troubleshooting-devfile-issues.adoc | 2 +- 96 files changed, 195 insertions(+), 262 deletions(-) delete mode 100644 .vale/styles/.placeholder rename modules/{end-user-guide => develop}/examples/con_customizing-ide-selection-with-the-che-editor-file.adoc (100%) rename modules/{end-user-guide => develop}/examples/proc_using-the-che-prod-editor-file-to-select-an-ide.adoc (100%) rename modules/{end-user-guide => develop}/examples/snip_che-ide-default-yaml-file.adoc (100%) rename modules/{end-user-guide => develop}/examples/snip_che-supported-languages.adoc (100%) rename modules/{end-user-guide => develop}/examples/snip_github-action-yaml-example-activity-types.adoc (100%) rename modules/{end-user-guide => develop}/examples/snip_github-action-yaml-example.adoc (100%) rename modules/{end-user-guide => develop}/images/contribute.svg (100%) rename modules/{end-user-guide => develop}/images/github-action-comment.png (100%) rename modules/{end-user-guide => develop}/images/github-action-status-check.png (100%) rename modules/{end-user-guide => develop}/images/vscode-remote/cli-create-tunnel.png (100%) rename modules/{end-user-guide => develop}/images/vscode-remote/confirm-opening-vscode-desktop.png (100%) rename modules/{end-user-guide => develop}/images/vscode-remote/login-with-provider.png (100%) rename modules/{end-user-guide => develop}/images/vscode-remote/login.png (100%) rename modules/{end-user-guide => develop}/images/vscode-remote/open-visual-studio-code.png (100%) rename modules/{end-user-guide => develop}/images/vscode-remote/select-editor.png (100%) rename modules/{end-user-guide => develop}/images/vscode-remote/vscode-remote-explorer.png (100%) rename modules/{end-user-guide => develop}/images/workspace-backup/backups_tab.png (100%) rename modules/{end-user-guide => develop}/images/workspace-backup/restore_section_1.png (100%) rename modules/{end-user-guide => develop}/images/workspace-backup/restore_section_2.png (100%) create mode 100644 modules/develop/nav.adoc rename modules/{end-user-guide => develop}/pages/accessing-fuse.adoc (100%) rename modules/{end-user-guide => develop}/pages/benefits-of-pull-requests-review-in-che.adoc (95%) rename modules/{end-user-guide => develop}/pages/changing-the-ai-tool-on-a-workspace.adoc (96%) rename modules/{end-user-guide => develop}/pages/configuring-an-ai-provider-api-key.adoc (97%) rename modules/{end-user-guide => develop}/pages/connect-visual-studio-code-to-che-workspace.adoc (98%) rename modules/{end-user-guide => develop}/pages/creating-image-pull-secrets.adoc (100%) rename modules/{end-user-guide => develop}/pages/customizing-workspace-components.adoc (93%) rename modules/{end-user-guide => develop}/pages/defining-a-common-ide.adoc (100%) rename modules/{end-user-guide => develop}/pages/devfile-introduction.adoc (97%) rename modules/{end-user-guide => develop}/pages/distribute-claude-code-skills-with-lola.adoc (92%) rename modules/{end-user-guide => develop}/pages/enabling-overlay-with-a-configmap.adoc (98%) rename modules/{end-user-guide => develop}/pages/first-time-contributors.adoc (91%) rename modules/{end-user-guide => develop}/pages/ides-in-workspaces.adoc (100%) rename modules/{end-user-guide => develop}/pages/microsoft-visual-studio-code-open-source-ide.adoc (97%) rename modules/{end-user-guide => develop}/pages/mounting-configmaps.adoc (100%) rename modules/{end-user-guide => develop}/pages/mounting-git-configuration.adoc (79%) rename modules/{end-user-guide => develop}/pages/mounting-secrets.adoc (100%) rename modules/{end-user-guide => develop}/pages/mounting-ssh-configuration.adoc (100%) rename modules/{end-user-guide => develop}/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc (100%) rename modules/{end-user-guide => develop}/pages/persist-claude-code-configuration.adoc (58%) rename modules/{end-user-guide => develop}/pages/proc-restoring-a-workspace-from-backup.adoc (100%) rename modules/{end-user-guide => develop}/pages/proc-viewing-backups-in-the-dashboard.adoc (100%) rename modules/{end-user-guide => develop}/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc (100%) rename modules/{end-user-guide => develop}/pages/requesting-persistent-storage-for-workspaces.adoc (100%) rename modules/{end-user-guide => develop}/pages/restoring-workspaces-from-backups.adoc (100%) rename modules/{end-user-guide => develop}/pages/running-containers-with-kubedock.adoc (100%) rename modules/{end-user-guide => develop}/pages/share-claude-code-configuration-with-gitops.adoc (91%) rename modules/{end-user-guide => develop}/pages/share-claude-code-configuration-with-pvc-direct-mount.adoc (77%) rename modules/{end-user-guide => develop}/pages/share-claude-code-configuration-with-pvc-tmp-copy.adoc (69%) rename modules/{end-user-guide => develop}/pages/starting-a-workspace-from-a-raw-devfile-url.adoc (100%) rename modules/{end-user-guide => develop}/pages/troubleshoot-claude-code-configuration-persistence.adoc (89%) rename modules/{end-user-guide => develop}/pages/try-in-web-ide-github-action.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-concatenation.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-additional-remotes.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-container-image.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-cpu-limit.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-memory-limit.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-starting-duplicate-workspaces.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-the-ai-provider.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-the-devfile-file-name.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-the-devfile-file-path.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-the-existing-workspace-name.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-the-ide-image.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-the-ide.adoc (100%) rename modules/{end-user-guide => develop}/pages/url-parameter-for-the-workspace-storage.adoc (100%) rename modules/{end-user-guide => develop}/pages/using-ai-assistants-in-workspaces.adoc (97%) rename modules/{end-user-guide => develop}/pages/using-che-in-team-workflow.adoc (100%) rename modules/{end-user-guide => develop}/pages/using-credentials-and-configurations-in-workspaces.adoc (95%) rename modules/{end-user-guide => develop}/pages/using-the-fuse-overlay-storage-driver.adoc (100%) rename modules/{end-user-guide => develop}/partials/assembly_try-in-web-ide-github-action.adoc (100%) rename modules/{end-user-guide => develop}/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc (100%) rename modules/{end-user-guide => develop}/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc (92%) rename modules/{end-user-guide => develop}/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc (100%) rename modules/{end-user-guide => develop}/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc (100%) rename modules/{end-user-guide => develop}/partials/proc_creating-an-image-pull-secret-with-cli.adoc (100%) rename modules/{end-user-guide => develop}/partials/proc_providing-a-devfile.adoc (100%) rename modules/{end-user-guide => develop}/partials/proc_requesting-persistent-storage-in-a-devfile.adoc (100%) rename modules/{end-user-guide => develop}/partials/proc_requesting-persistent-storage-in-a-pvc.adoc (100%) rename modules/{end-user-guide => develop}/partials/proc_setting-up-che-editor-yaml.adoc (83%) rename modules/{end-user-guide => develop}/partials/ref_about-try-in-web-ide-github-action.adoc (100%) rename modules/{end-user-guide => develop}/partials/ref_parameters-for-che-editor-yaml.adoc (100%) diff --git a/.vale/styles/.placeholder b/.vale/styles/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/antora.yml b/antora.yml index f019768006..520b41428a 100644 --- a/antora.yml +++ b/antora.yml @@ -9,6 +9,7 @@ nav: - modules/install/nav.adoc - modules/get-started-admin/nav.adoc - modules/get-started-user/nav.adoc + - modules/develop/nav.adoc - modules/troubleshoot/nav.adoc - modules/end-user-guide/nav.adoc - modules/upgrade/nav.adoc diff --git a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc index c66835c0ba..e23c06f0b0 100644 --- a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc +++ b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc @@ -30,8 +30,8 @@ data: OPENAI_API_KEY: ____ <6> ---- <1> Secret name is derived as `ai-provider-` + `envVarName.toLowerCase().replace(/_/g, '-')`. For `OPENAI_API_KEY` the name is `ai-provider-openai-api-key`. -<2> Instructs the DevWorkspace Controller to mount this Secret into all `DevWorkspace` containers in the namespace. -<3> Instructs the DevWorkspace Controller to watch for Secret changes and re-mount without a workspace restart. +<2> Instructs the {devworkspace} Controller to mount this Secret into all `DevWorkspace` containers in the namespace. +<3> Instructs the {devworkspace} Controller to watch for Secret changes and re-mount without a workspace restart. <4> Sanitized provider ID (characters other than letters, digits, dots, underscores, and dashes are replaced with dashes). Identifies which AI provider this Secret belongs to. Used by the {prod-short} dashboard to detect existing keys. <5> Mounts the Secret data keys as environment variables (not as files). <6> The data key is the environment variable name. The value is base64-encoded. The variable is injected directly into all workspace containers. @@ -44,11 +44,11 @@ data: | `controller.devfile.io/mount-to-devworkspace` | `'true'` -| Causes the DevWorkspace Controller to mount this Secret into every `DevWorkspace` in the namespace. +| Causes the {devworkspace} Controller to mount this Secret into every `DevWorkspace` in the namespace. | `controller.devfile.io/watch-secret` | `'true'` -| The DevWorkspace Controller re-mounts the Secret when its data changes, without requiring a workspace restart. +| The {devworkspace} Controller re-mounts the Secret when its data changes, without requiring a workspace restart. | `controller.devfile.io/mount-as` | `env` @@ -104,5 +104,5 @@ EOF .Additional resources * xref:configuring-ai-providers.adoc[] -* xref:end-user-guide:mounting-secrets.adoc[Mounting secrets (end-user guide)] +* xref:develop:mounting-secrets.adoc[Mounting secrets (end-user guide)] * link:https://devfile.io/docs/2.2.0/what-is-a-devfile[Devfile documentation] diff --git a/modules/administration-guide/pages/configuring-a-user-namespace.adoc b/modules/administration-guide/pages/configuring-a-user-namespace.adoc index a67f0d99cc..5905b6e844 100644 --- a/modules/administration-guide/pages/configuring-a-user-namespace.adoc +++ b/modules/administration-guide/pages/configuring-a-user-namespace.adoc @@ -9,7 +9,7 @@ Learn how to use {prod-short} to synchronize `ConfigMaps`, `Secrets`, `PersistentVolumeClaim` and other {kubernetes} objects -from `{prod-namespace}` namespace to numerous user-specific namespaces. +from `{prod-namespace}` {namespace} to numerous user-specific namespaces. The {prod-short} automates the synchronization of important configuration data, such as shared credentials, configuration files, and certificates to user namespaces. @@ -183,7 +183,7 @@ and `controller.devfile.io/mount-to-devworkspace-exclude` are set, the resource mounted only to workspaces that match the include pattern and do not match the exclude pattern. + For other labels and annotations, see link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Mounting volumes, configmaps, and secrets]. -. To leverage the OpenShift Kubernetes Engine, you can create a `Template` object to replicate all resources defined within the template across each user {orch-namespace}. +. To use the OpenShift {kubernetes} Engine, you can create a `Template` object to replicate all resources defined within the template across each user {orch-namespace}. + Aside from the previously mentioned `ConfigMap`, `Secret`, and `PersistentVolumeClaim`, `Template` objects can include: + @@ -261,13 +261,13 @@ objects: parameters: - name: PROJECT_ADMIN_USER ---- -NOTE: Creating Template Kubernetes resources is supported only on OpenShift. +NOTE: Creating Template {kubernetes} resources is supported only on OpenShift. ==== .Additional resources -* xref:end-user-guide:mounting-configmaps.adoc[] -* xref:end-user-guide:mounting-secrets.adoc[] -* xref:end-user-guide:requesting-persistent-storage-for-workspaces.adoc[] +* xref:develop:mounting-configmaps.adoc[] +* xref:develop:mounting-secrets.adoc[] +* xref:develop:requesting-persistent-storage-for-workspaces.adoc[] * link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Automatically mounting volumes, configmaps, and secrets] * link:https://docs.openshift.com/container-platform/latest/rest_api/template_apis/template-template-openshift-io-v1.html[OpenShift API reference for `Template`] * link:https://docs.openshift.com/container-platform/latest/applications/projects/configuring-project-creation.html[Configuring OpenShift project creation] \ No newline at end of file diff --git a/modules/administration-guide/pages/configuring-ai-providers.adoc b/modules/administration-guide/pages/configuring-ai-providers.adoc index 7eef2df746..dac677592d 100644 --- a/modules/administration-guide/pages/configuring-ai-providers.adoc +++ b/modules/administration-guide/pages/configuring-ai-providers.adoc @@ -162,4 +162,4 @@ When you update the registry (for example, to remove a tool or change the inject .Additional resources * xref:ai-provider-api-key-secret-reference.adoc[] -* xref:end-user-guide:using-ai-assistants-in-workspaces.adoc[] +* xref:develop:using-ai-assistants-in-workspaces.adoc[] diff --git a/modules/administration-guide/pages/configuring-fuse.adoc b/modules/administration-guide/pages/configuring-fuse.adoc index b6da34436e..cfbe23c885 100644 --- a/modules/administration-guide/pages/configuring-fuse.adoc +++ b/modules/administration-guide/pages/configuring-fuse.adoc @@ -18,4 +18,4 @@ This is not necessary for OpenShift versions 4.15 and later, since the `/dev/fus After enabling `/dev/fuse` access, fuse-overlayfs can be enabled in two ways: . For all user workspaces within the cluster. See xref:administration-guide:enabling-fuse-for-all-workspaces.adoc[]. -. For workspaces belonging to certain users. See xref:end-user-guide:using-the-fuse-overlay-storage-driver.adoc[]. +. For workspaces belonging to certain users. See xref:develop:using-the-fuse-overlay-storage-driver.adoc[]. diff --git a/modules/administration-guide/pages/configuring-the-storage-strategy.adoc b/modules/administration-guide/pages/configuring-the-storage-strategy.adoc index dcbc6256b9..ad88d3d4fd 100644 --- a/modules/administration-guide/pages/configuring-the-storage-strategy.adoc +++ b/modules/administration-guide/pages/configuring-the-storage-strategy.adoc @@ -7,7 +7,7 @@ [id="configuring-the-storage-strategy"] = Configuring the storage strategy -{prod-short} can be configured to provide persistent or non-persistent storage to workspaces by selecting a storage strategy. The selected storage strategy will be applied to all newly created workspaces by default. Users can opt for a non-default storage strategy for their workspace in their xref:end-user-guide:requesting-persistent-storage-for-workspaces.adoc[devfile] or through the xref:end-user-guide:url-parameter-for-the-workspace-storage.adoc[URL parameter]. +{prod-short} can be configured to provide persistent or non-persistent storage to workspaces by selecting a storage strategy. The selected storage strategy will be applied to all newly created workspaces by default. Users can opt for a non-default storage strategy for their workspace in their xref:develop:requesting-persistent-storage-for-workspaces.adoc[devfile] or through the xref:develop:url-parameter-for-the-workspace-storage.adoc[URL parameter]. Available storage strategies: diff --git a/modules/administration-guide/pages/devworkspace-backup.adoc b/modules/administration-guide/pages/devworkspace-backup.adoc index c4fc4ef0aa..ffb5c72b57 100644 --- a/modules/administration-guide/pages/devworkspace-backup.adoc +++ b/modules/administration-guide/pages/devworkspace-backup.adoc @@ -14,7 +14,7 @@ integrated registry or link:https://quay.io[Quay.io], to store backup archives a The backup makes a snapshot of *stopped* Workspace PVCs and stores them as tar.gz archives in the specified OCI registry. -Users can restore backups from the {prod-short} dashboard. See xref:end-user-guide:restoring-workspaces-from-backups.adoc[]. +Users can restore backups from the {prod-short} dashboard. See xref:develop:restoring-workspaces-from-backups.adoc[]. NOTE: By default, the {devworkspace} backup job is disabled. @@ -29,7 +29,7 @@ The value for `registry.path` is the first segment of the final location. The fu + `//:latest` -* `registry.authSecret`: (Optional) The name of the Kubernetes secret that contains credentials for the OCI registry. If you do not provide a secret, the system assumes the registry is public or uses the **Red Hat OpenShift** integrated registry. +* `registry.authSecret`: (Optional) The name of the {kubernetes} secret that contains credentials for the OCI registry. If you do not provide a secret, the system assumes the registry is public or uses the **Red Hat OpenShift** integrated registry. * `oras.extraArgs`: (Optional) Additional arguments for to the `oras` CLI tool during push and pull operations. diff --git a/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc b/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc index f0ede58afc..5f7c9875d7 100644 --- a/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc +++ b/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc @@ -139,4 +139,4 @@ sh-4.4# stat /host/etc/crio/crio.conf.d/99-podman-fuse ---- == Using fuse-overlayfs for Podman and Buildah within a workspace -Users can follow xref:end-user-guide:using-the-fuse-overlay-storage-driver.adoc[] to update existing workspaces to use the fuse-overlayfs storage driver for Podman and Buildah. +Users can follow xref:develop:using-the-fuse-overlay-storage-driver.adoc[] to update existing workspaces to use the fuse-overlayfs storage driver for Podman and Buildah. diff --git a/modules/end-user-guide/examples/con_customizing-ide-selection-with-the-che-editor-file.adoc b/modules/develop/examples/con_customizing-ide-selection-with-the-che-editor-file.adoc similarity index 100% rename from modules/end-user-guide/examples/con_customizing-ide-selection-with-the-che-editor-file.adoc rename to modules/develop/examples/con_customizing-ide-selection-with-the-che-editor-file.adoc diff --git a/modules/end-user-guide/examples/proc_using-the-che-prod-editor-file-to-select-an-ide.adoc b/modules/develop/examples/proc_using-the-che-prod-editor-file-to-select-an-ide.adoc similarity index 100% rename from modules/end-user-guide/examples/proc_using-the-che-prod-editor-file-to-select-an-ide.adoc rename to modules/develop/examples/proc_using-the-che-prod-editor-file-to-select-an-ide.adoc diff --git a/modules/end-user-guide/examples/snip_che-ide-default-yaml-file.adoc b/modules/develop/examples/snip_che-ide-default-yaml-file.adoc similarity index 100% rename from modules/end-user-guide/examples/snip_che-ide-default-yaml-file.adoc rename to modules/develop/examples/snip_che-ide-default-yaml-file.adoc diff --git a/modules/end-user-guide/examples/snip_che-supported-languages.adoc b/modules/develop/examples/snip_che-supported-languages.adoc similarity index 100% rename from modules/end-user-guide/examples/snip_che-supported-languages.adoc rename to modules/develop/examples/snip_che-supported-languages.adoc diff --git a/modules/end-user-guide/examples/snip_github-action-yaml-example-activity-types.adoc b/modules/develop/examples/snip_github-action-yaml-example-activity-types.adoc similarity index 100% rename from modules/end-user-guide/examples/snip_github-action-yaml-example-activity-types.adoc rename to modules/develop/examples/snip_github-action-yaml-example-activity-types.adoc diff --git a/modules/end-user-guide/examples/snip_github-action-yaml-example.adoc b/modules/develop/examples/snip_github-action-yaml-example.adoc similarity index 100% rename from modules/end-user-guide/examples/snip_github-action-yaml-example.adoc rename to modules/develop/examples/snip_github-action-yaml-example.adoc diff --git a/modules/end-user-guide/images/contribute.svg b/modules/develop/images/contribute.svg similarity index 100% rename from modules/end-user-guide/images/contribute.svg rename to modules/develop/images/contribute.svg diff --git a/modules/end-user-guide/images/github-action-comment.png b/modules/develop/images/github-action-comment.png similarity index 100% rename from modules/end-user-guide/images/github-action-comment.png rename to modules/develop/images/github-action-comment.png diff --git a/modules/end-user-guide/images/github-action-status-check.png b/modules/develop/images/github-action-status-check.png similarity index 100% rename from modules/end-user-guide/images/github-action-status-check.png rename to modules/develop/images/github-action-status-check.png diff --git a/modules/end-user-guide/images/vscode-remote/cli-create-tunnel.png b/modules/develop/images/vscode-remote/cli-create-tunnel.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/cli-create-tunnel.png rename to modules/develop/images/vscode-remote/cli-create-tunnel.png diff --git a/modules/end-user-guide/images/vscode-remote/confirm-opening-vscode-desktop.png b/modules/develop/images/vscode-remote/confirm-opening-vscode-desktop.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/confirm-opening-vscode-desktop.png rename to modules/develop/images/vscode-remote/confirm-opening-vscode-desktop.png diff --git a/modules/end-user-guide/images/vscode-remote/login-with-provider.png b/modules/develop/images/vscode-remote/login-with-provider.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/login-with-provider.png rename to modules/develop/images/vscode-remote/login-with-provider.png diff --git a/modules/end-user-guide/images/vscode-remote/login.png b/modules/develop/images/vscode-remote/login.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/login.png rename to modules/develop/images/vscode-remote/login.png diff --git a/modules/end-user-guide/images/vscode-remote/open-visual-studio-code.png b/modules/develop/images/vscode-remote/open-visual-studio-code.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/open-visual-studio-code.png rename to modules/develop/images/vscode-remote/open-visual-studio-code.png diff --git a/modules/end-user-guide/images/vscode-remote/select-editor.png b/modules/develop/images/vscode-remote/select-editor.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/select-editor.png rename to modules/develop/images/vscode-remote/select-editor.png diff --git a/modules/end-user-guide/images/vscode-remote/vscode-remote-explorer.png b/modules/develop/images/vscode-remote/vscode-remote-explorer.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/vscode-remote-explorer.png rename to modules/develop/images/vscode-remote/vscode-remote-explorer.png diff --git a/modules/end-user-guide/images/workspace-backup/backups_tab.png b/modules/develop/images/workspace-backup/backups_tab.png similarity index 100% rename from modules/end-user-guide/images/workspace-backup/backups_tab.png rename to modules/develop/images/workspace-backup/backups_tab.png diff --git a/modules/end-user-guide/images/workspace-backup/restore_section_1.png b/modules/develop/images/workspace-backup/restore_section_1.png similarity index 100% rename from modules/end-user-guide/images/workspace-backup/restore_section_1.png rename to modules/develop/images/workspace-backup/restore_section_1.png diff --git a/modules/end-user-guide/images/workspace-backup/restore_section_2.png b/modules/develop/images/workspace-backup/restore_section_2.png similarity index 100% rename from modules/end-user-guide/images/workspace-backup/restore_section_2.png rename to modules/develop/images/workspace-backup/restore_section_2.png diff --git a/modules/develop/nav.adoc b/modules/develop/nav.adoc new file mode 100644 index 0000000000..f6c093f39a --- /dev/null +++ b/modules/develop/nav.adoc @@ -0,0 +1,51 @@ +.Develop +* xref:using-credentials-and-configurations-in-workspaces.adoc[] +** xref:mounting-secrets.adoc[] +*** xref:creating-image-pull-secrets.adoc[] +** xref:mounting-configmaps.adoc[] +*** xref:mounting-git-configuration.adoc[] +*** xref:mounting-ssh-configuration.adoc[] +* xref:using-the-fuse-overlay-storage-driver.adoc[] +** xref:accessing-fuse.adoc[] +** xref:enabling-overlay-with-a-configmap.adoc[] +** xref:running-containers-with-kubedock.adoc[] +* xref:using-che-in-team-workflow.adoc[] +** xref:first-time-contributors.adoc[] +** xref:benefits-of-pull-requests-review-in-che.adoc[] +** xref:try-in-web-ide-github-action.adoc[] +* xref:requesting-persistent-storage-for-workspaces.adoc[] +** xref:restoring-workspaces-from-backups.adoc[] +*** xref:proc-viewing-backups-in-the-dashboard.adoc[] +*** xref:proc-restoring-a-workspace-from-backup.adoc[] +* xref:proc_preventing-workspace-idling-for-long-running-commands.adoc[] +* xref:starting-a-workspace-from-a-raw-devfile-url.adoc[] +* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] +** xref:url-parameter-concatenation.adoc[] +** xref:url-parameter-for-the-ide.adoc[] +** xref:url-parameter-for-the-ide-image.adoc[] +** xref:url-parameter-for-starting-duplicate-workspaces.adoc[] +** xref:url-parameter-for-the-existing-workspace-name.adoc[] +** xref:url-parameter-for-the-devfile-file-name.adoc[] +** xref:url-parameter-for-the-devfile-file-path.adoc[] +** xref:url-parameter-for-the-workspace-storage.adoc[] +** xref:url-parameter-for-additional-remotes.adoc[] +** xref:url-parameter-for-container-image.adoc[] +** xref:url-parameter-for-memory-limit.adoc[] +** xref:url-parameter-for-cpu-limit.adoc[] +** xref:url-parameter-for-the-ai-provider.adoc[] +* Set up your development tools +** xref:customizing-workspace-components.adoc[] +*** xref:devfile-introduction.adoc[] +** xref:ides-in-workspaces.adoc[] +*** xref:microsoft-visual-studio-code-open-source-ide.adoc[] +*** xref:connect-visual-studio-code-to-che-workspace.adoc[] +*** xref:defining-a-common-ide.adoc[] +** xref:using-ai-assistants-in-workspaces.adoc[] +*** xref:configuring-an-ai-provider-api-key.adoc[] +*** xref:changing-the-ai-tool-on-a-workspace.adoc[] +*** xref:persist-claude-code-configuration.adoc[] +**** xref:share-claude-code-configuration-with-pvc-direct-mount.adoc[] +**** xref:share-claude-code-configuration-with-pvc-tmp-copy.adoc[] +**** xref:share-claude-code-configuration-with-gitops.adoc[] +**** xref:troubleshoot-claude-code-configuration-persistence.adoc[] +*** xref:distribute-claude-code-skills-with-lola.adoc[] diff --git a/modules/end-user-guide/pages/accessing-fuse.adoc b/modules/develop/pages/accessing-fuse.adoc similarity index 100% rename from modules/end-user-guide/pages/accessing-fuse.adoc rename to modules/develop/pages/accessing-fuse.adoc diff --git a/modules/end-user-guide/pages/benefits-of-pull-requests-review-in-che.adoc b/modules/develop/pages/benefits-of-pull-requests-review-in-che.adoc similarity index 95% rename from modules/end-user-guide/pages/benefits-of-pull-requests-review-in-che.adoc rename to modules/develop/pages/benefits-of-pull-requests-review-in-che.adoc index e09b1c4fc0..a2de7b4532 100644 --- a/modules/end-user-guide/pages/benefits-of-pull-requests-review-in-che.adoc +++ b/modules/develop/pages/benefits-of-pull-requests-review-in-che.adoc @@ -1,7 +1,7 @@ :_content-type: PROCEDURE :description: {prod} workspace contains all tools you need to review pull and merge requests from start to finish. :keywords: user-guide, reviewing, pull request, merge request -:navtitle: Reviewing pull and merge requests +:navtitle: Benefits of reviewing pull and merge requests in {prod} :page-aliases: [id="title"] diff --git a/modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc b/modules/develop/pages/changing-the-ai-tool-on-a-workspace.adoc similarity index 96% rename from modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc rename to modules/develop/pages/changing-the-ai-tool-on-a-workspace.adoc index af3c933ae3..0f58f87a80 100644 --- a/modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc +++ b/modules/develop/pages/changing-the-ai-tool-on-a-workspace.adoc @@ -1,7 +1,7 @@ :_content-type: PROCEDURE :description: Switch or remove the AI coding assistant on a stopped workspace without recreating it, and optionally choose a specific version. :keywords: user-guide, ai, ai tool, ai provider, workspace, change, update, version -:navtitle: Changing the AI tool on a workspace +:navtitle: Change the AI tool on a workspace :page-aliases: [id="changing-the-ai-tool-on-a-workspace"] diff --git a/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc b/modules/develop/pages/configuring-an-ai-provider-api-key.adoc similarity index 97% rename from modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc rename to modules/develop/pages/configuring-an-ai-provider-api-key.adoc index b0582299d9..7013e4fdb9 100644 --- a/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc +++ b/modules/develop/pages/configuring-an-ai-provider-api-key.adoc @@ -1,7 +1,7 @@ :_content-type: PROCEDURE :description: Store your AI provider API key so that it is automatically available as an environment variable in all your workspaces. :keywords: user-guide, ai, api key, ai provider, environment variable, secret -:navtitle: Configuring an AI provider API key +:navtitle: Configure an AI provider API key :page-aliases: [id="configuring-an-ai-provider-api-key"] diff --git a/modules/end-user-guide/pages/connect-visual-studio-code-to-che-workspace.adoc b/modules/develop/pages/connect-visual-studio-code-to-che-workspace.adoc similarity index 98% rename from modules/end-user-guide/pages/connect-visual-studio-code-to-che-workspace.adoc rename to modules/develop/pages/connect-visual-studio-code-to-che-workspace.adoc index cf16ab617c..c5082ce9f1 100644 --- a/modules/end-user-guide/pages/connect-visual-studio-code-to-che-workspace.adoc +++ b/modules/develop/pages/connect-visual-studio-code-to-che-workspace.adoc @@ -1,3 +1,4 @@ +:page-aliases: end-user-guide:connect-visual-studio-code-to-che-workspace.adoc [id="connect-visual-studio-code-to-che-workspace"] = Connecting Visual Studio Code to a {prod-short} workspace diff --git a/modules/end-user-guide/pages/creating-image-pull-secrets.adoc b/modules/develop/pages/creating-image-pull-secrets.adoc similarity index 100% rename from modules/end-user-guide/pages/creating-image-pull-secrets.adoc rename to modules/develop/pages/creating-image-pull-secrets.adoc diff --git a/modules/end-user-guide/pages/customizing-workspace-components.adoc b/modules/develop/pages/customizing-workspace-components.adoc similarity index 93% rename from modules/end-user-guide/pages/customizing-workspace-components.adoc rename to modules/develop/pages/customizing-workspace-components.adoc index 00ac0c63f0..b81cf6686b 100644 --- a/modules/end-user-guide/pages/customizing-workspace-components.adoc +++ b/modules/develop/pages/customizing-workspace-components.adoc @@ -10,7 +10,7 @@ To customize workspace components: -* xref:starting-a-workspace-from-a-git-repository-url.adoc[Choose a Git repository for your workspace]. +* xref:get-started-user:starting-a-workspace-from-a-git-repository-url.adoc[Choose a Git repository for your workspace]. * xref:devfile-introduction.adoc[Use a devfile]. diff --git a/modules/end-user-guide/pages/defining-a-common-ide.adoc b/modules/develop/pages/defining-a-common-ide.adoc similarity index 100% rename from modules/end-user-guide/pages/defining-a-common-ide.adoc rename to modules/develop/pages/defining-a-common-ide.adoc diff --git a/modules/end-user-guide/pages/devfile-introduction.adoc b/modules/develop/pages/devfile-introduction.adoc similarity index 97% rename from modules/end-user-guide/pages/devfile-introduction.adoc rename to modules/develop/pages/devfile-introduction.adoc index 3400c3cb8d..4d8912ab82 100644 --- a/modules/end-user-guide/pages/devfile-introduction.adoc +++ b/modules/develop/pages/devfile-introduction.adoc @@ -1,3 +1,4 @@ +:page-aliases: end-user-guide:devfile-introduction.adoc [id="introduction-to-devfile"] = Introduction to devfile in {prod-short} diff --git a/modules/end-user-guide/pages/distribute-claude-code-skills-with-lola.adoc b/modules/develop/pages/distribute-claude-code-skills-with-lola.adoc similarity index 92% rename from modules/end-user-guide/pages/distribute-claude-code-skills-with-lola.adoc rename to modules/develop/pages/distribute-claude-code-skills-with-lola.adoc index 1d6ac8ceaa..8686375bcc 100644 --- a/modules/end-user-guide/pages/distribute-claude-code-skills-with-lola.adoc +++ b/modules/develop/pages/distribute-claude-code-skills-with-lola.adoc @@ -8,15 +8,13 @@ Use link:https://github.com/LobsterTrap/lola[Lola] to distribute team-authored skills, commands, and agents from a central Git repository into {prod-short} workspaces. Lola supports multiple AI assistants, including Claude Code, Cursor, Copilot, Gemini CLI, and OpenCode. It translates module content into each assistant's native file structure, so developers receive a consistent set of standards and tools without manual setup. +A team maintains a Lola module in a Git repository containing skills (coding standards, guardrails), commands (on-demand audit macros), and agent definitions. Developers add a `.lola-req` file to their project referencing the module. Running `lola sync` fetches the module and installs it into the target assistant's native directory structure. + [NOTE] ==== -Lola manages skills, commands, and agents — not the full AI assistant configuration. For example, to persist Claude Code settings, MCP servers, and plugins, see xref:persist-claude-code-configuration.adoc[]. +Lola manages skills, commands, and agents only. It does not persist assistant-specific settings, MCP server configurations, or plugin caches. For full Claude Code configuration persistence, see Additional resources. ==== -== How it works - -A team maintains a Lola module in a Git repository containing skills (coding standards, guardrails), commands (on-demand audit macros), and agent definitions. Developers add a `.lola-req` file to their project referencing the module. Running `lola sync` fetches the module and installs it into the target assistant's native directory structure. - .Prerequisites * An AI assistant (Claude Code, Cursor, Copilot, Gemini CLI, or OpenCode) installed in the workspace container image. @@ -40,19 +38,17 @@ module/ AGENTS.md ---- -* Git credentials configured in the workspace if the module repository is private. See xref:authenticating-to-a-git-server-from-a-workspace.adoc[]. +* Git credentials configured in the workspace if the module repository is private. See xref:get-started-user:authenticating-to-a-git-server-from-a-workspace.adoc[]. .Procedure . Create a `.lola-req` file at the root of your project repository with a reference to the module: + -==== [source,text,subs="+quotes"] ---- ____@main#subdirectory=module&assistant=____ # <1> ---- <1> Replace `____` with the URL of your Lola module repository. Replace `____` with the target assistant: `claude-code`, `cursor`, `copilot`, `gemini-cli`, or `opencode`. The `subdirectory` fragment points to the module root inside the repository. -==== . Run `lola sync` to fetch and install the module: + @@ -65,7 +61,6 @@ Lola clones the module, extracts skills and commands, and writes them into the t . Optional: To automate the sync at workspace startup, add a `postStart` command to your devfile: + -==== [source,yaml,subs="+quotes,+attributes"] ---- commands: @@ -80,7 +75,6 @@ events: ---- <1> Replace with the name of your project directory. <2> Replace with the name of a container component from the `components` section of your devfile. -==== .Verification diff --git a/modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc b/modules/develop/pages/enabling-overlay-with-a-configmap.adoc similarity index 98% rename from modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc rename to modules/develop/pages/enabling-overlay-with-a-configmap.adoc index 8726c0853d..8eb2b16bc5 100644 --- a/modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc +++ b/modules/develop/pages/enabling-overlay-with-a-configmap.adoc @@ -1,7 +1,7 @@ :_content-type: PROCEDURE :description: You can enable fuse-overlayfs storage driver for Podman :keywords: overlay, configmap, podman, storage, driver, fuse-overlayfs -:navtitle: Enabling fuse-overlayfs with a ConfigMap +:navtitle: Enabling fuse-overlayfs with a Configmap :page-aliases: [id="enabling-fuse-overlay-with-a-configmap"] diff --git a/modules/end-user-guide/pages/first-time-contributors.adoc b/modules/develop/pages/first-time-contributors.adoc similarity index 91% rename from modules/end-user-guide/pages/first-time-contributors.adoc rename to modules/develop/pages/first-time-contributors.adoc index d537375464..0d703fa2f9 100644 --- a/modules/end-user-guide/pages/first-time-contributors.adoc +++ b/modules/develop/pages/first-time-contributors.adoc @@ -1,7 +1,7 @@ :_content-type: PROCEDURE :description: Badge for first-time contributors :keywords: user-guide, first-time contributor -:navtitle: Badge for first-time contributors +:navtitle: Using a badge with a link to enable a first-time contributor to start a workspace :page-aliases: [id="using-a-badge-with-a-link-to-enable-a-first-time-contributor-to-start-a-workspace"] diff --git a/modules/end-user-guide/pages/ides-in-workspaces.adoc b/modules/develop/pages/ides-in-workspaces.adoc similarity index 100% rename from modules/end-user-guide/pages/ides-in-workspaces.adoc rename to modules/develop/pages/ides-in-workspaces.adoc diff --git a/modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc b/modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc similarity index 97% rename from modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc rename to modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc index 046b3d954c..ba86a31d1b 100644 --- a/modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc +++ b/modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc @@ -1,7 +1,7 @@ :_content-type: CONCEPT :description: Microsoft Visual Studio Code - Open Source IDE :keywords: user-guide, selecting, IDE, select, selecting, editor, ide, vs-code, visual-studio, visual-studio-code, jetbrains, intellij, pycharm, theia, che-theia -:navtitle: Microsoft Visual Studio Code - Open Source +:navtitle: Microsoft Visual Studio Code - Open Source IDE :page-aliases: [id="microsoft-visual-studio-code-open-source-ide"] diff --git a/modules/end-user-guide/pages/mounting-configmaps.adoc b/modules/develop/pages/mounting-configmaps.adoc similarity index 100% rename from modules/end-user-guide/pages/mounting-configmaps.adoc rename to modules/develop/pages/mounting-configmaps.adoc diff --git a/modules/end-user-guide/pages/mounting-git-configuration.adoc b/modules/develop/pages/mounting-git-configuration.adoc similarity index 79% rename from modules/end-user-guide/pages/mounting-git-configuration.adoc rename to modules/develop/pages/mounting-git-configuration.adoc index bfd075b00a..7ec8d96bf4 100644 --- a/modules/end-user-guide/pages/mounting-git-configuration.adoc +++ b/modules/develop/pages/mounting-git-configuration.adoc @@ -9,7 +9,7 @@ [NOTE] ==== -The `user.name` and `user.email` fields will be set automatically to the `gitconfig` content from a git provider, connected to {prod-short} by a xref:using-a-git-provider-access-token.adoc[Git-provider access token] or a token generated via OAuth, if username and email are set on the provider's user profile page. +The `user.name` and `user.email` fields will be set automatically to the `gitconfig` content from a git provider, connected to {prod-short} by a xref:get-started-user:using-a-git-provider-access-token.adoc[Git-provider access token] or a token generated via OAuth, if username and email are set on the provider's user profile page. ==== Follow the instructions below to mount a Git config file in a workspace. @@ -52,7 +52,7 @@ EOF .Verification -. xref:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace by using the URL of a remote Git repository] that the Git provider hosts. +. xref:get-started-user:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace by using the URL of a remote Git repository] that the Git provider hosts. . Once the workspace is started, open a new terminal in the `tools` container and run `git config --get-regexp user.*`. Your Git user name and email should appear in the output. diff --git a/modules/end-user-guide/pages/mounting-secrets.adoc b/modules/develop/pages/mounting-secrets.adoc similarity index 100% rename from modules/end-user-guide/pages/mounting-secrets.adoc rename to modules/develop/pages/mounting-secrets.adoc diff --git a/modules/end-user-guide/pages/mounting-ssh-configuration.adoc b/modules/develop/pages/mounting-ssh-configuration.adoc similarity index 100% rename from modules/end-user-guide/pages/mounting-ssh-configuration.adoc rename to modules/develop/pages/mounting-ssh-configuration.adoc diff --git a/modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc b/modules/develop/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc similarity index 100% rename from modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc rename to modules/develop/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc diff --git a/modules/end-user-guide/pages/persist-claude-code-configuration.adoc b/modules/develop/pages/persist-claude-code-configuration.adoc similarity index 58% rename from modules/end-user-guide/pages/persist-claude-code-configuration.adoc rename to modules/develop/pages/persist-claude-code-configuration.adoc index 82346d815c..4e706f9250 100644 --- a/modules/end-user-guide/pages/persist-claude-code-configuration.adoc +++ b/modules/develop/pages/persist-claude-code-configuration.adoc @@ -5,9 +5,9 @@ :page-aliases: persisting-claude-code-configuration.adoc [id="persist-claude-code-configuration"] -= Persist Claude Code configuration in {prod-short} workspaces += Claude Code configuration persistence -To reuse Claude Code skills, settings, MCP servers, and plugins across {prod-short} workspaces, persist the configuration in a shared volume or a Git repository. Without persistence, each new workspace requires a fresh setup. +Persist Claude Code skills, settings, MCP servers, and plugins across {prod-short} workspaces by storing them in a shared volume or a Git repository. Without persistence, each new workspace requires a fresh setup. == Claude Code configuration files @@ -33,21 +33,53 @@ Claude Code writes runtime state to both paths during every session, including s == Available approaches |=== -| Approach | Summary +| Approach | Summary | Storage requirement | xref:share-claude-code-configuration-with-pvc-direct-mount.adoc[] | Both `{prod-home}/.claude/` and `{prod-home}/.claude.json` are mounted directly from a dedicated PVC. All changes persist automatically. Requires a one-time init pod to pre-create `.claude.json`. +| RWX for concurrent workspaces | xref:share-claude-code-configuration-with-pvc-tmp-copy.adoc[] | A dedicated PVC is mounted at `/tmp/claude`. A `postStart` command copies everything into the home directory. No init pod is required, but changes must be synced back manually before stopping the workspace. +| RWX for concurrent workspaces | xref:share-claude-code-configuration-with-gitops.adoc[] | A Git repository stores the baseline Claude Code configuration. The {devworkspace} Operator clones the repository at startup, and a `postStart` command copies the configuration into the home directory. +| No PVC required |=== -== Distributing skills and commands +== Distribute skills and commands -To distribute team-authored skills, commands, and agents across workspaces without persisting the full configuration, see xref:distribute-claude-code-skills-with-lola.adoc[]. Lola supports Claude Code and other AI assistants. +To distribute team-authored skills, commands, and agents across workspaces without persisting the full configuration, use Lola. Lola supports Claude Code and other AI assistants. For Lola setup instructions, see _Distribute AI assistant skills and commands across workspaces with Lola_ in Additional resources. + +== Filter PVC mounts by workspace name + +Control which workspaces mount the PVC by adding annotations to the PVC metadata: + +* `controller.devfile.io/mount-to-devworkspace-include: '____'` mounts the PVC only to workspaces whose names match the pattern. +* `controller.devfile.io/mount-to-devworkspace-exclude: '____'` mounts the PVC to all workspaces except those whose names match. + +Supported patterns: exact match (`name`), prefix (`name\*`), suffix (`\*name`), contains (`\*name\*`). Matching is on the {devworkspace} resource name. + +== Concurrent workspace access + +|=== +| Access mode | Behavior + +| ReadWriteOnce (RWO) +| One workspace at a time. Two workspaces on different nodes cause a multi-attach error. + +| ReadWriteMany (RWX) +| Concurrent workspaces on different pods work. Requires a storage class that supports RWX, such as AWS EFS or NFS. Standard block storage (gp2, gp3) does not support RWX. +|=== + +== Compatibility with `persistUserHome` + +For the direct mount approach, a dedicated PVC mounted at `{prod-home}/.claude` and the persistent home PVC mounted at `{prod-home}/` coexist correctly as nested mounts. Writes to `{prod-home}/.claude/` go to the dedicated PVC. Writes to other paths under `{prod-home}/` go to the persistent home PVC. + +For the tmp copy approach, the dedicated PVC mounted at `/tmp/claude` and the persistent home PVC mounted at `{prod-home}/` do not conflict because they use different mount points. If the devfile includes a `postStart` command, it copies configuration from the PVC into the home directory at workspace start. Otherwise, you must copy the configuration manually. Changes must be synced back to the PVC manually before stopping the workspace. + +If you only need persistence within a single workspace and not cross-workspace sharing, `persistUserHome` alone is sufficient. == Claude Code file reference diff --git a/modules/end-user-guide/pages/proc-restoring-a-workspace-from-backup.adoc b/modules/develop/pages/proc-restoring-a-workspace-from-backup.adoc similarity index 100% rename from modules/end-user-guide/pages/proc-restoring-a-workspace-from-backup.adoc rename to modules/develop/pages/proc-restoring-a-workspace-from-backup.adoc diff --git a/modules/end-user-guide/pages/proc-viewing-backups-in-the-dashboard.adoc b/modules/develop/pages/proc-viewing-backups-in-the-dashboard.adoc similarity index 100% rename from modules/end-user-guide/pages/proc-viewing-backups-in-the-dashboard.adoc rename to modules/develop/pages/proc-viewing-backups-in-the-dashboard.adoc diff --git a/modules/end-user-guide/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc b/modules/develop/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc similarity index 100% rename from modules/end-user-guide/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc rename to modules/develop/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc diff --git a/modules/end-user-guide/pages/requesting-persistent-storage-for-workspaces.adoc b/modules/develop/pages/requesting-persistent-storage-for-workspaces.adoc similarity index 100% rename from modules/end-user-guide/pages/requesting-persistent-storage-for-workspaces.adoc rename to modules/develop/pages/requesting-persistent-storage-for-workspaces.adoc diff --git a/modules/end-user-guide/pages/restoring-workspaces-from-backups.adoc b/modules/develop/pages/restoring-workspaces-from-backups.adoc similarity index 100% rename from modules/end-user-guide/pages/restoring-workspaces-from-backups.adoc rename to modules/develop/pages/restoring-workspaces-from-backups.adoc diff --git a/modules/end-user-guide/pages/running-containers-with-kubedock.adoc b/modules/develop/pages/running-containers-with-kubedock.adoc similarity index 100% rename from modules/end-user-guide/pages/running-containers-with-kubedock.adoc rename to modules/develop/pages/running-containers-with-kubedock.adoc diff --git a/modules/end-user-guide/pages/share-claude-code-configuration-with-gitops.adoc b/modules/develop/pages/share-claude-code-configuration-with-gitops.adoc similarity index 91% rename from modules/end-user-guide/pages/share-claude-code-configuration-with-gitops.adoc rename to modules/develop/pages/share-claude-code-configuration-with-gitops.adoc index 4c8ac305cc..76b3243785 100644 --- a/modules/end-user-guide/pages/share-claude-code-configuration-with-gitops.adoc +++ b/modules/develop/pages/share-claude-code-configuration-with-gitops.adoc @@ -7,11 +7,7 @@ [id="share-claude-code-configuration-with-gitops"] = Share Claude Code configuration across workspaces with GitOps -Instead of using a shared PVC, you can store Claude Code configuration in a Git repository and pull it into workspaces at startup. Each workspace gets its own isolated, writable copy of the configuration. - -This approach eliminates multi-attach errors and last-write-wins data corruption risks that can occur with shared PVCs on clusters without RWX storage. - -== How it works +Instead of using a shared PVC, you can store Claude Code configuration in a Git repository and pull it into workspaces at startup. Each workspace gets its own isolated, writable copy of the configuration, preventing multi-attach errors and last-write-wins data corruption risks that can occur with shared PVCs on clusters without RWX storage. A central Git repository stores the baseline Claude Code configuration. The repository is listed in the `projects` section of the devfile, and the {devworkspace} Operator's project-clone init container clones it automatically at workspace startup. A `postStart` command then copies the configuration files from the cloned repository into the home directory. @@ -21,7 +17,7 @@ Two usage patterns are possible: * *User-specific persistence* — each developer maintains a private branch or repository with personal configuration. The repository is cloned at startup and copied into the home directory. Optionally, a `preStop` command or manual step commits and pushes changes back before the workspace stops. -For a comparison with other approaches, see xref:persist-claude-code-configuration.adoc[]. +For a comparison with other approaches, see _Claude Code configuration persistence_ in Additional resources. .Prerequisites @@ -38,13 +34,12 @@ For a comparison with other approaches, see xref:persist-claude-code-configurati .claude.json ---- -* Git credentials configured in the workspace if the repository is private. See xref:authenticating-to-a-git-server-from-a-workspace.adoc[]. +* Git credentials configured in the workspace if the repository is private. See xref:get-started-user:authenticating-to-a-git-server-from-a-workspace.adoc[]. .Procedure . Add the configuration repository to the `projects` section of your devfile: + -==== [source,yaml,subs="+quotes,+attributes"] ---- projects: @@ -54,11 +49,9 @@ projects: origin: '____' # <1> ---- <1> Replace with the URL of your Claude Code configuration repository. -==== . Add a `postStart` command to copy the configuration from the cloned repository into the home directory: + -==== [source,yaml,subs="+quotes,+attributes"] ---- commands: @@ -73,7 +66,6 @@ events: - init-claude-config ---- <1> Replace with the name of a container component from the `components` section of your devfile. -==== . Start the workspace. @@ -114,4 +106,4 @@ $ git add -A && git commit -m "Update Claude Code configuration" && git push * xref:share-claude-code-configuration-with-pvc-direct-mount.adoc[] * xref:share-claude-code-configuration-with-pvc-tmp-copy.adoc[] * xref:troubleshoot-claude-code-configuration-persistence.adoc[] -* xref:authenticating-to-a-git-server-from-a-workspace.adoc[] +* xref:get-started-user:authenticating-to-a-git-server-from-a-workspace.adoc[] diff --git a/modules/end-user-guide/pages/share-claude-code-configuration-with-pvc-direct-mount.adoc b/modules/develop/pages/share-claude-code-configuration-with-pvc-direct-mount.adoc similarity index 77% rename from modules/end-user-guide/pages/share-claude-code-configuration-with-pvc-direct-mount.adoc rename to modules/develop/pages/share-claude-code-configuration-with-pvc-direct-mount.adoc index 3cfe7dca35..9b2df6730a 100644 --- a/modules/end-user-guide/pages/share-claude-code-configuration-with-pvc-direct-mount.adoc +++ b/modules/develop/pages/share-claude-code-configuration-with-pvc-direct-mount.adoc @@ -16,7 +16,7 @@ The direct mount flow: . You configure Claude Code — install plugins, add MCP servers, change settings. All writes go directly to the PVC. . The second workspace starts. The same PVC mounts, and all configuration from the previous workspace is available. -For a comparison with other approaches, see xref:persist-claude-code-configuration.adoc[]. +For a comparison with other approaches, see _Claude Code configuration persistence_ in Additional resources. .Prerequisites @@ -32,7 +32,6 @@ For a comparison with other approaches, see xref:persist-claude-code-configurati . Create a file `claude-config-pvc.yaml` with the following PVC definition: + -==== [source,yaml,subs="+quotes,+attributes"] ---- kind: PersistentVolumeClaim @@ -52,7 +51,6 @@ spec: requests: storage: 1Gi ---- -==== . Apply the PVC to your {orch-namespace}: + @@ -67,7 +65,6 @@ The `{prod-home}/.claude.json` subPath target must exist as a *file* on the PVC + Create a file `claude-config-init-pod.yaml`: + -==== [source,yaml,subs="+quotes,+attributes"] ---- apiVersion: v1 @@ -95,7 +92,6 @@ spec: persistentVolumeClaim: claimName: claude-config ---- -==== . Apply the init pod: + @@ -126,7 +122,7 @@ $ {orch-cli} delete pod claude-config-init ---- . Start any workspace. The PVC auto-mounts into every workspace pod. - ++ [WARNING] ==== On multi-AZ clusters using `WaitForFirstConsumer` storage classes (gp2, gp3), the init pod may bind the PV to a different availability zone than workspace pods. See xref:troubleshoot-claude-code-configuration-persistence.adoc#pvc-scheduling-failure-after-init-pod-setup[PVC scheduling failure after init pod setup]. @@ -138,39 +134,6 @@ On multi-AZ clusters using `WaitForFirstConsumer` storage classes (gp2, gp3), th . Stop and restart the workspace. Verify the configuration is preserved. . Start a different workspace. Verify the same configuration is available. -== Filtering by workspace name - -Control which workspaces mount the PVC by adding annotations: - -[source,yaml,subs="+quotes,+attributes"] ----- -annotations: - controller.devfile.io/mount-to-devworkspace-include: '____' # <1> - controller.devfile.io/mount-to-devworkspace-exclude: '____' # <2> ----- -<1> Mount the PVC only to workspaces whose names match the pattern. -<2> Mount the PVC to all workspaces except those whose names match the pattern. - -Supported patterns: exact match (`name`), prefix (`name\*`), suffix (`\*name`), contains (`\*name\*`). Matching is on the {devworkspace} resource name. - -== Concurrent workspaces - -|=== -| Access mode | Behavior - -| ReadWriteOnce (RWO) -| One workspace at a time. Two workspaces on different nodes cause a multi-attach error. - -| ReadWriteMany (RWX) -| Concurrent workspaces on different pods work. Requires a storage class that supports RWX, such as AWS EFS or NFS. Standard block storage (gp2, gp3) does not support RWX. -|=== - -== Compatibility with `persistUserHome` - -A dedicated PVC mounted at `{prod-home}/.claude` and the persistent home PVC mounted at `{prod-home}/` coexist correctly as nested mounts. Writes to `{prod-home}/.claude/` go to the dedicated PVC. Writes to other paths under `{prod-home}/` go to the persistent home PVC. - -If you only need persistence within a single workspace and not cross-workspace sharing, `persistUserHome` alone is sufficient. - == Limitations * Requires manual PVC setup per user {orch-namespace}. diff --git a/modules/end-user-guide/pages/share-claude-code-configuration-with-pvc-tmp-copy.adoc b/modules/develop/pages/share-claude-code-configuration-with-pvc-tmp-copy.adoc similarity index 69% rename from modules/end-user-guide/pages/share-claude-code-configuration-with-pvc-tmp-copy.adoc rename to modules/develop/pages/share-claude-code-configuration-with-pvc-tmp-copy.adoc index 1e29121cc1..27883dd6a4 100644 --- a/modules/end-user-guide/pages/share-claude-code-configuration-with-pvc-tmp-copy.adoc +++ b/modules/develop/pages/share-claude-code-configuration-with-pvc-tmp-copy.adoc @@ -16,7 +16,7 @@ The tmp copy flow: . Before stopping the workspace, you sync changes back to the PVC at `/tmp/claude`. . The second workspace starts. The `postStart` command copies the saved configuration from the PVC into the home directory. -For a comparison with other approaches, see xref:persist-claude-code-configuration.adoc[]. +For a comparison with other approaches, see _Claude Code configuration persistence_ in Additional resources. .Prerequisites @@ -30,7 +30,6 @@ For a comparison with other approaches, see xref:persist-claude-code-configurati . Create a file `claude-config-pvc.yaml` with the following PVC definition: + -==== [source,yaml,subs="+quotes,+attributes"] ---- kind: PersistentVolumeClaim @@ -48,7 +47,6 @@ spec: requests: storage: 1Gi ---- -==== . Apply the PVC to your {orch-namespace}: + @@ -59,7 +57,6 @@ $ {orch-cli} apply -f claude-config-pvc.yaml -n ____ . Add a `postStart` command to your devfile to copy all configuration from the PVC into the home directory: + -==== [source,yaml,subs="+quotes,+attributes"] ---- commands: @@ -75,7 +72,6 @@ events: - init-claude-config ---- <1> Replace with the name of a container component from the `components` section of your devfile. -==== . Start the workspace. @@ -94,39 +90,6 @@ $ cp -a {prod-home}/.claude/. /tmp/claude/.claude/ && \ . Start a different workspace. . Verify that the Claude Code configuration from the first workspace is available. -== Filtering by workspace name - -Control which workspaces mount the PVC by adding annotations: - -[source,yaml,subs="+quotes,+attributes"] ----- -annotations: - controller.devfile.io/mount-to-devworkspace-include: '____' # <1> - controller.devfile.io/mount-to-devworkspace-exclude: '____' # <2> ----- -<1> Mount the PVC only to workspaces whose names match the pattern. -<2> Mount the PVC to all workspaces except those whose names match the pattern. - -Supported patterns: exact match (`name`), prefix (`name\*`), suffix (`\*name`), contains (`\*name\*`). Matching is on the {devworkspace} resource name. - -== Concurrent workspaces - -|=== -| Access mode | Behavior - -| ReadWriteOnce (RWO) -| One workspace at a time. Two workspaces on different nodes cause a multi-attach error. - -| ReadWriteMany (RWX) -| Concurrent workspaces on different pods work. Requires a storage class that supports RWX, such as AWS EFS or NFS. Standard block storage (gp2, gp3) does not support RWX. -|=== - -== Compatibility with `persistUserHome` - -A dedicated PVC mounted at `/tmp/claude` and the persistent home PVC mounted at `{prod-home}/` do not conflict because they use different mount points. If the devfile includes a `postStart` command, it copies configuration from the PVC into the home directory at workspace start. Otherwise, you must copy the configuration manually. Changes must be synced back to the PVC manually before stopping the workspace. - -If you only need persistence within a single workspace and not cross-workspace sharing, `persistUserHome` alone is sufficient. - == Limitations * Requires manual PVC setup per user {orch-namespace}. diff --git a/modules/end-user-guide/pages/starting-a-workspace-from-a-raw-devfile-url.adoc b/modules/develop/pages/starting-a-workspace-from-a-raw-devfile-url.adoc similarity index 100% rename from modules/end-user-guide/pages/starting-a-workspace-from-a-raw-devfile-url.adoc rename to modules/develop/pages/starting-a-workspace-from-a-raw-devfile-url.adoc diff --git a/modules/end-user-guide/pages/troubleshoot-claude-code-configuration-persistence.adoc b/modules/develop/pages/troubleshoot-claude-code-configuration-persistence.adoc similarity index 89% rename from modules/end-user-guide/pages/troubleshoot-claude-code-configuration-persistence.adoc rename to modules/develop/pages/troubleshoot-claude-code-configuration-persistence.adoc index cc06fe2308..c1d863ea09 100644 --- a/modules/end-user-guide/pages/troubleshoot-claude-code-configuration-persistence.adoc +++ b/modules/develop/pages/troubleshoot-claude-code-configuration-persistence.adoc @@ -7,68 +7,61 @@ [id="troubleshoot-claude-code-configuration-persistence"] = Troubleshoot Claude Code configuration persistence -If you encounter issues with Claude Code configuration persistence in {prod-short} workspaces, use the following symptoms and solutions to diagnose and resolve them. +Match the symptoms below to identify the root cause and apply the corresponding solution. == `.claude.json` corrupted on first start -=== Symptom - +Symptom:: ++ ---- Claude configuration file at /home/user/.claude.json is corrupted: JSON Parse error: Unexpected EOF ---- -=== Cause - +Cause:: The `.claude.json` file was pre-created as an empty file, for example with `touch`, instead of valid JSON. -=== Solution - +Solution:: Initialize the file with valid JSON content: - ++ ---- $ echo '{}' > .claude.json ---- - ++ If you already see this error, select *Reset with default configuration* when prompted. This is a one-time prompt that does not recur. == `.claude.json` mounted as a directory -=== Symptom - +Symptom:: Claude Code fails to start or reports that `{prod-home}/.claude.json` is not a valid file. Inspecting the mount shows a directory instead of a file: - ++ ---- $ stat {prod-home}/.claude.json File: {prod-home}/.claude.json Size: 4096 Blocks: 8 IO Block: 4096 directory ---- -=== Cause - +Cause:: When a PVC `subPath` mount target does not exist on the volume, {kubernetes} kubelet creates it as a *directory*, not a file. The mount point is locked and cannot be replaced from inside the container. -=== Solution - +Solution:: Do not mount `{prod-home}/.claude.json` as a direct subPath from a PVC without pre-creating the file. Either use an init pod to pre-create it (xref:share-claude-code-configuration-with-pvc-direct-mount.adoc[direct mount]) or use the xref:share-claude-code-configuration-with-pvc-tmp-copy.adoc[tmp copy] approach. == Permission denied writing to `~/.claude/session-env` -=== Symptom - +Symptom:: ++ ---- The workspace environment blocks write access to /home/user/.claude/session-env ---- -=== Cause - +Cause:: On OpenShift, the Security Context Constraints (SCC) assign a random UID per {orch-namespace}. If the PVC contents were created with a different UID or group, write access fails. -=== Solution - +Solution:: On OpenShift, PVC filesystems typically receive a setgid bit (`drwxrwsr-x`) with group `0`, and workspace containers run with GID `0`. When both conditions are met, writes succeed without manual permission changes. - ++ If you encounter this error, verify that: - ++ * The PVC was created in the same {orch-namespace} as the workspace. * The PVC contents have group `0` ownership: + @@ -80,49 +73,44 @@ If the group is not `0` (root), the PVC contents were likely created by a proces == Multi-attach error when starting a second workspace -=== Symptom - +Symptom:: ++ ---- Multi-Attach error for volume "pvc-xxx": Volume is already exclusively attached to one node ---- -=== Cause - +Cause:: The PVC uses `ReadWriteOnce` (RWO) access mode. RWO volumes can only attach to a single node at a time. When two workspace pods are scheduled on different nodes, the second pod cannot mount the volume. -=== Solution - +Solution:: Choose one of the following: - ++ * Run only one workspace at a time. * Use `ReadWriteMany` (RWX) access mode with a storage class that supports it, such as AWS EFS or NFS. Standard block storage classes (gp2, gp3) do not support RWX. -* Use `controller.devfile.io/mount-to-devworkspace-include` or `controller.devfile.io/mount-to-devworkspace-exclude` annotations on the PVC to control which workspaces mount it. See xref:share-claude-code-configuration-with-pvc-direct-mount.adoc#_filtering_by_workspace_name[Filtering by workspace name]. - +* Use `controller.devfile.io/mount-to-devworkspace-include` or `controller.devfile.io/mount-to-devworkspace-exclude` annotations on the PVC to control which workspaces mount it. See xref:persist-claude-code-configuration.adoc#_filter_pvc_mounts_by_workspace_name[Filter PVC mounts by workspace name]. ++ To check available storage classes: - ++ [subs="+quotes,+attributes"] ---- $ {orch-cli} get storageclasses ---- - ++ Look for classes using EFS (`efs.csi.aws.com`) or NFS provisioners. == Changes to `~/.claude.json` not persisting after restart -=== Symptom - +Symptom:: After restarting a workspace, MCP server configurations added during the previous session are lost. -=== Cause - +Cause:: This applies to the xref:share-claude-code-configuration-with-pvc-tmp-copy.adoc[tmp copy] approach. The `postStart` command copies configurations from the PVC into the home directory. Changes made during the session are written to the home directory, not back to the PVC. - ++ The xref:share-claude-code-configuration-with-pvc-direct-mount.adoc[direct mount] approach does not have this issue because changes are written directly to the PVC. -=== Solution - +Solution:: Sync changes back to the PVC before stopping the workspace: - ++ [subs="+quotes,+attributes"] ---- $ cp -a {prod-home}/.claude/. /tmp/claude/.claude/ && \ @@ -132,29 +120,25 @@ $ cp -a {prod-home}/.claude/. /tmp/claude/.claude/ && \ [id="pvc-scheduling-failure-after-init-pod-setup"] == PVC scheduling failure after init pod setup -=== Symptom - +Symptom:: ++ ---- 0/N nodes are available: X node(s) didn't match PersistentVolume's node affinity ---- - ++ A workspace fails to start after a PVC was initialized using a temporary pod. -=== Cause - -On multi-AZ clusters using RWO block storage (gp2, gp3), the PersistentVolume is provisioned in a single availability zone. - -This issue does not affect single-AZ clusters or clusters using RWX storage (EFS, NFS). - -=== Solution +Cause:: +On multi-AZ clusters using RWO block storage (gp2, gp3), the PersistentVolume is provisioned in a single availability zone. This issue does not affect single-AZ clusters or clusters using RWX storage (EFS, NFS). +Solution:: Do not use a separate init pod to initialize PVC contents on clusters with `WaitForFirstConsumer` storage classes. Instead: - ++ . Let the workspace pod be the first consumer of the PVC. . Handle file initialization with `postStart` commands from inside the workspace. - ++ If you already have a PVC stuck in the wrong availability zone: - ++ . Stop all workspaces using the PVC. . Delete the PVC: + @@ -162,8 +146,9 @@ If you already have a PVC stuck in the wrong availability zone: ---- $ {orch-cli} delete pvc ____ -n __<{orch-namespace}>__ ---- ++ . Recreate the PVC and start a workspace. The PV is provisioned in the correct zone. - ++ For clusters where this is a recurring issue, use the xref:share-claude-code-configuration-with-pvc-tmp-copy.adoc[tmp copy] approach, which does not require an init pod. .Additional resources diff --git a/modules/end-user-guide/pages/try-in-web-ide-github-action.adoc b/modules/develop/pages/try-in-web-ide-github-action.adoc similarity index 100% rename from modules/end-user-guide/pages/try-in-web-ide-github-action.adoc rename to modules/develop/pages/try-in-web-ide-github-action.adoc diff --git a/modules/end-user-guide/pages/url-parameter-concatenation.adoc b/modules/develop/pages/url-parameter-concatenation.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-concatenation.adoc rename to modules/develop/pages/url-parameter-concatenation.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-additional-remotes.adoc b/modules/develop/pages/url-parameter-for-additional-remotes.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-additional-remotes.adoc rename to modules/develop/pages/url-parameter-for-additional-remotes.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-container-image.adoc b/modules/develop/pages/url-parameter-for-container-image.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-container-image.adoc rename to modules/develop/pages/url-parameter-for-container-image.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-cpu-limit.adoc b/modules/develop/pages/url-parameter-for-cpu-limit.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-cpu-limit.adoc rename to modules/develop/pages/url-parameter-for-cpu-limit.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-memory-limit.adoc b/modules/develop/pages/url-parameter-for-memory-limit.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-memory-limit.adoc rename to modules/develop/pages/url-parameter-for-memory-limit.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-starting-duplicate-workspaces.adoc b/modules/develop/pages/url-parameter-for-starting-duplicate-workspaces.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-starting-duplicate-workspaces.adoc rename to modules/develop/pages/url-parameter-for-starting-duplicate-workspaces.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc b/modules/develop/pages/url-parameter-for-the-ai-provider.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc rename to modules/develop/pages/url-parameter-for-the-ai-provider.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-devfile-file-name.adoc b/modules/develop/pages/url-parameter-for-the-devfile-file-name.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-devfile-file-name.adoc rename to modules/develop/pages/url-parameter-for-the-devfile-file-name.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-devfile-file-path.adoc b/modules/develop/pages/url-parameter-for-the-devfile-file-path.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-devfile-file-path.adoc rename to modules/develop/pages/url-parameter-for-the-devfile-file-path.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-existing-workspace-name.adoc b/modules/develop/pages/url-parameter-for-the-existing-workspace-name.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-existing-workspace-name.adoc rename to modules/develop/pages/url-parameter-for-the-existing-workspace-name.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-ide-image.adoc b/modules/develop/pages/url-parameter-for-the-ide-image.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-ide-image.adoc rename to modules/develop/pages/url-parameter-for-the-ide-image.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-ide.adoc b/modules/develop/pages/url-parameter-for-the-ide.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-ide.adoc rename to modules/develop/pages/url-parameter-for-the-ide.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-workspace-storage.adoc b/modules/develop/pages/url-parameter-for-the-workspace-storage.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-workspace-storage.adoc rename to modules/develop/pages/url-parameter-for-the-workspace-storage.adoc diff --git a/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc b/modules/develop/pages/using-ai-assistants-in-workspaces.adoc similarity index 97% rename from modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc rename to modules/develop/pages/using-ai-assistants-in-workspaces.adoc index 2bfa89229d..2780b6226d 100644 --- a/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc +++ b/modules/develop/pages/using-ai-assistants-in-workspaces.adoc @@ -1,7 +1,7 @@ :_content-type: CONCEPT :description: Select and configure AI coding assistants for your workspaces to get AI-powered development help in the terminal. :keywords: user-guide, ai, ai assistant, ai provider, ai selector -:navtitle: Using AI assistants in workspaces +:navtitle: AI assistants in workspaces :page-aliases: [id="using-ai-assistants-in-workspaces"] diff --git a/modules/end-user-guide/pages/using-che-in-team-workflow.adoc b/modules/develop/pages/using-che-in-team-workflow.adoc similarity index 100% rename from modules/end-user-guide/pages/using-che-in-team-workflow.adoc rename to modules/develop/pages/using-che-in-team-workflow.adoc diff --git a/modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc b/modules/develop/pages/using-credentials-and-configurations-in-workspaces.adoc similarity index 95% rename from modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc rename to modules/develop/pages/using-credentials-and-configurations-in-workspaces.adoc index 3e6e5afdfa..7dc64643d9 100644 --- a/modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc +++ b/modules/develop/pages/using-credentials-and-configurations-in-workspaces.adoc @@ -25,7 +25,7 @@ You can create permanent mount points for various components: * Maven configuration, such as the link:https://maven.apache.org/settings.html[user-specific] `settings.xml` file * SSH key pairs -* xref:using-a-git-provider-access-token.adoc[Git-provider access tokens] +* xref:get-started-user:using-a-git-provider-access-token.adoc[Git-provider access tokens] * xref:mounting-git-configuration.adoc[Git configuration] * AWS authorization tokens * Configuration files diff --git a/modules/end-user-guide/pages/using-the-fuse-overlay-storage-driver.adoc b/modules/develop/pages/using-the-fuse-overlay-storage-driver.adoc similarity index 100% rename from modules/end-user-guide/pages/using-the-fuse-overlay-storage-driver.adoc rename to modules/develop/pages/using-the-fuse-overlay-storage-driver.adoc diff --git a/modules/end-user-guide/partials/assembly_try-in-web-ide-github-action.adoc b/modules/develop/partials/assembly_try-in-web-ide-github-action.adoc similarity index 100% rename from modules/end-user-guide/partials/assembly_try-in-web-ide-github-action.adoc rename to modules/develop/partials/assembly_try-in-web-ide-github-action.adoc diff --git a/modules/end-user-guide/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc b/modules/develop/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc similarity index 100% rename from modules/end-user-guide/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc rename to modules/develop/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc diff --git a/modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc b/modules/develop/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc similarity index 92% rename from modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc rename to modules/develop/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc index a00e2c5f11..18c1cca00b 100644 --- a/modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc +++ b/modules/develop/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc @@ -48,7 +48,7 @@ https://www.open-vsx.org/extension/____/____ .Verification -. xref:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace by using the URL of the remote Git repository] that contains the created `extensions.json` file. +. xref:get-started-user:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace by using the URL of the remote Git repository] that contains the created `extensions.json` file. . In the IDE of the workspace, press kbd:[Ctrl+Shift+X] or go to *Extensions* to find each of the extensions listed in the file. . The extension has the label *This extension is enabled globally*. diff --git a/modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc b/modules/develop/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc similarity index 100% rename from modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc rename to modules/develop/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc diff --git a/modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc b/modules/develop/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc similarity index 100% rename from modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc rename to modules/develop/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc diff --git a/modules/end-user-guide/partials/proc_creating-an-image-pull-secret-with-cli.adoc b/modules/develop/partials/proc_creating-an-image-pull-secret-with-cli.adoc similarity index 100% rename from modules/end-user-guide/partials/proc_creating-an-image-pull-secret-with-cli.adoc rename to modules/develop/partials/proc_creating-an-image-pull-secret-with-cli.adoc diff --git a/modules/end-user-guide/partials/proc_providing-a-devfile.adoc b/modules/develop/partials/proc_providing-a-devfile.adoc similarity index 100% rename from modules/end-user-guide/partials/proc_providing-a-devfile.adoc rename to modules/develop/partials/proc_providing-a-devfile.adoc diff --git a/modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-devfile.adoc b/modules/develop/partials/proc_requesting-persistent-storage-in-a-devfile.adoc similarity index 100% rename from modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-devfile.adoc rename to modules/develop/partials/proc_requesting-persistent-storage-in-a-devfile.adoc diff --git a/modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-pvc.adoc b/modules/develop/partials/proc_requesting-persistent-storage-in-a-pvc.adoc similarity index 100% rename from modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-pvc.adoc rename to modules/develop/partials/proc_requesting-persistent-storage-in-a-pvc.adoc diff --git a/modules/end-user-guide/partials/proc_setting-up-che-editor-yaml.adoc b/modules/develop/partials/proc_setting-up-che-editor-yaml.adoc similarity index 83% rename from modules/end-user-guide/partials/proc_setting-up-che-editor-yaml.adoc rename to modules/develop/partials/proc_setting-up-che-editor-yaml.adoc index 375c67a723..a558988ef1 100644 --- a/modules/end-user-guide/partials/proc_setting-up-che-editor-yaml.adoc +++ b/modules/develop/partials/proc_setting-up-che-editor-yaml.adoc @@ -9,6 +9,6 @@ By using the `che-editor.yaml` file, you can set a common default IDE for your t .Verification -. xref:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace with a clone of the Git repository]. +. xref:get-started-user:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace with a clone of the Git repository]. . Verify that the specified IDE loads in the browser tab of the started workspace. diff --git a/modules/end-user-guide/partials/ref_about-try-in-web-ide-github-action.adoc b/modules/develop/partials/ref_about-try-in-web-ide-github-action.adoc similarity index 100% rename from modules/end-user-guide/partials/ref_about-try-in-web-ide-github-action.adoc rename to modules/develop/partials/ref_about-try-in-web-ide-github-action.adoc diff --git a/modules/end-user-guide/partials/ref_parameters-for-che-editor-yaml.adoc b/modules/develop/partials/ref_parameters-for-che-editor-yaml.adoc similarity index 100% rename from modules/end-user-guide/partials/ref_parameters-for-che-editor-yaml.adoc rename to modules/develop/partials/ref_parameters-for-che-editor-yaml.adoc diff --git a/modules/discover/pages/roles-and-tasks.adoc b/modules/discover/pages/roles-and-tasks.adoc index 32d4808276..0452afa22a 100644 --- a/modules/discover/pages/roles-and-tasks.adoc +++ b/modules/discover/pages/roles-and-tasks.adoc @@ -30,5 +30,5 @@ Common tasks include: * Create a workspace from a Git repository. See xref:get-started:starting-a-workspace-from-a-git-repository-url.adoc[]. * Authenticate to Git servers. See xref:get-started:using-a-git-provider-access-token.adoc[]. -* Install and manage IDE extensions. See xref:end-user-guide:microsoft-visual-studio-code-open-source-ide.adoc[]. -* Use devfiles to define workspace configuration. See xref:end-user-guide:devfile-introduction.adoc[]. +* Install and manage IDE extensions. See xref:develop:microsoft-visual-studio-code-open-source-ide.adoc[]. +* Use devfiles to define workspace configuration. See xref:develop:devfile-introduction.adoc[]. diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 5a671cf8c8..fc8550c7db 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -1,63 +1,13 @@ .User Guide -* xref:starting-a-workspace-from-a-raw-devfile-url.adoc[] -* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] -** xref:url-parameter-concatenation.adoc[] -** xref:url-parameter-for-the-ide.adoc[] -** xref:url-parameter-for-the-ide-image.adoc[] -** xref:url-parameter-for-starting-duplicate-workspaces.adoc[] -** xref:url-parameter-for-the-devfile-file-name.adoc[] -** xref:url-parameter-for-the-devfile-file-path.adoc[] -** xref:url-parameter-for-the-workspace-storage.adoc[] -** xref:url-parameter-for-additional-remotes.adoc[] -** xref:url-parameter-for-container-image.adoc[] -** xref:url-parameter-for-memory-limit.adoc[] -** xref:url-parameter-for-cpu-limit.adoc[] -** xref:url-parameter-for-the-existing-workspace-name.adoc[] -** xref:url-parameter-for-the-ai-provider.adoc[] -* xref:restoring-workspaces-from-backups.adoc[] -** xref:proc-restoring-a-workspace-from-backup.adoc[] -** xref:proc-viewing-backups-in-the-dashboard.adoc[] -* xref:using-the-fuse-overlay-storage-driver.adoc[] -** xref:accessing-fuse.adoc[] -** xref:enabling-overlay-with-a-configmap.adoc[] -* xref:running-containers-with-kubedock.adoc[] -* xref:proc_preventing-workspace-idling-for-long-running-commands.adoc[] -* xref:using-che-in-team-workflow.adoc[] -** xref:first-time-contributors.adoc[] -** xref:benefits-of-pull-requests-review-in-che.adoc[] -** xref:try-in-web-ide-github-action.adoc[] -* xref:customizing-workspace-components.adoc[] -* xref:devfile-introduction.adoc[] -* xref:ides-in-workspaces.adoc[] -** xref:microsoft-visual-studio-code-open-source-ide.adoc[] -** xref:connect-visual-studio-code-to-che-workspace.adoc[] -** xref:defining-a-common-ide.adoc[] -* xref:using-ai-assistants-in-workspaces.adoc[] -** xref:configuring-an-ai-provider-api-key.adoc[] -** xref:changing-the-ai-tool-on-a-workspace.adoc[] -** xref:persist-claude-code-configuration.adoc[] -*** xref:share-claude-code-configuration-with-pvc-direct-mount.adoc[] -*** xref:share-claude-code-configuration-with-pvc-tmp-copy.adoc[] -*** xref:share-claude-code-configuration-with-gitops.adoc[] -*** xref:troubleshoot-claude-code-configuration-persistence.adoc[] -** xref:distribute-claude-code-skills-with-lola.adoc[] -* xref:using-credentials-and-configurations-in-workspaces.adoc[] -** xref:mounting-secrets.adoc[] -*** xref:creating-image-pull-secrets.adoc[] -*** xref:get-started-user:using-a-git-provider-access-token.adoc[] -*** xref:connecting-to-github-using-device-authorization.adoc[] -** xref:mounting-configmaps.adoc[] -*** xref:mounting-git-configuration.adoc[] -*** xref:mounting-ssh-configuration.adoc[] -** xref:enabling-artifact-repositories-in-a-restricted-environment.adoc[] -*** xref:enabling-maven-artifact-repositories.adoc[] -*** xref:enabling-gradle-artifact-repositories.adoc[] -*** xref:enabling-npm-artifact-repositories.adoc[] -*** xref:enabling-python-artifact-repositories.adoc[] -*** xref:enabling-go-artifact-repositories.adoc[] -*** xref:enabling-nuget-artifact-repositories.adoc[] -* xref:requesting-persistent-storage-for-workspaces.adoc[] +* xref:connecting-to-github-using-device-authorization.adoc[] +* xref:enabling-artifact-repositories-in-a-restricted-environment.adoc[] +** xref:enabling-maven-artifact-repositories.adoc[] +** xref:enabling-gradle-artifact-repositories.adoc[] +** xref:enabling-npm-artifact-repositories.adoc[] +** xref:enabling-python-artifact-repositories.adoc[] +** xref:enabling-go-artifact-repositories.adoc[] +** xref:enabling-nuget-artifact-repositories.adoc[] * xref:integrating-with-kubernetes.adoc[] ** xref:managing-workspaces-with-apis.adoc[] ** xref:automatic-token-injection.adoc[] diff --git a/modules/get-started-user/pages/starting-a-workspace-from-a-git-repository-url.adoc b/modules/get-started-user/pages/starting-a-workspace-from-a-git-repository-url.adoc index 9a8c76b353..7a388a294a 100644 --- a/modules/get-started-user/pages/starting-a-workspace-from-a-git-repository-url.adoc +++ b/modules/get-started-user/pages/starting-a-workspace-from-a-git-repository-url.adoc @@ -34,7 +34,7 @@ TIP: You can also use the *Git Repository URL* field on the *Create Workspace* p pass:c,a,q[{prod-url}]#____ ---- + -To append optional parameters, add `?____` to the URL. See xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for workspace URLs] for supported parameters. +To append optional parameters, add `?____` to the URL. See xref:develop:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for workspace URLs] for supported parameters. + For example: + @@ -97,10 +97,10 @@ For GitHub, you can also use a URL of a directory containing a devfile, or a dir [role="_additional-resources"] .Additional resources -* xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for workspace URLs] +* xref:develop:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for workspace URLs] * xref:basic-actions-you-can-perform-on-a-workspace.adoc[] * xref:using-a-git-provider-access-token.adoc[] -* xref:end-user-guide:mounting-git-configuration.adoc[] +* xref:develop:mounting-git-configuration.adoc[] // vale RedHat.GitLinks = NO * link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations] // vale RedHat.GitLinks = YES diff --git a/modules/get-started-user/pages/using-a-git-provider-access-token.adoc b/modules/get-started-user/pages/using-a-git-provider-access-token.adoc index fc7ad9ac57..e0885c7eea 100644 --- a/modules/get-started-user/pages/using-a-git-provider-access-token.adoc +++ b/modules/get-started-user/pages/using-a-git-provider-access-token.adoc @@ -101,7 +101,7 @@ stringData: ---- // vale RedHat.GitLinks = YES -. Open `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`. +. Open `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user {namespace} as `name`. . Apply the Secret to your {prod-short} user {orch-namespace}: + @@ -112,7 +112,7 @@ $ {orch-cli} apply -f personal-access-token.yaml -n ____ + [IMPORTANT] ==== -If you are using Azure DevOps Server, you must also modify the xref:end-user-guide:mounting-git-configuration.adoc[cloud development environment gitconfig] with the following section: +If you are using Azure DevOps Server, you must also modify the xref:develop:mounting-git-configuration.adoc[cloud development environment gitconfig] with the following section: [source,http] ---- diff --git a/modules/secure/pages/security-best-practices.adoc b/modules/secure/pages/security-best-practices.adoc index c19a46b45c..3ccaf2d656 100644 --- a/modules/secure/pages/security-best-practices.adoc +++ b/modules/secure/pages/security-best-practices.adoc @@ -111,16 +111,16 @@ The following table lists the resources and actions that you can grant users per |projects |"get" -|devworkspace +|`devworkspaces` |"get", "create", "delete", "list", "update", "patch", "watch" -|devworkspacetemplates +|`devworkspacetemplates` |"get", "create", "delete", "list", "update", "patch", "watch" |=== [IMPORTANT] ==== -Each user is granted permissions only to their namespace and cannot access other users' resources. Cluster administrators can add extra permissions to users. They should not remove permissions granted by default. +Each user is granted permissions only to their {namespace} and cannot access other users' resources. Cluster administrators can add extra permissions to users. They should not remove permissions granted by default. For more details about configuring cluster roles for {prod} users and role-based access control, see the Additional resources section. ==== @@ -136,7 +136,7 @@ Isolation of the development environments is implemented using OpenShift project [IMPORTANT] ==== -Access to the resources in a namespace must be limited to the developer owning it. Granting read access to another developer is equivalent to sharing the developer credentials and should be avoided. +Access to the resources in a {namespace} must be limited to the developer owning it. Granting read access to another developer is equivalent to sharing the developer credentials and should be avoided. ==== == Restrict platform access with allow and deny lists @@ -244,7 +244,7 @@ For credential-free Git access that reduces token sprawl, see Additional resourc * xref:configuring-cluster-roles-for-users.adoc[] * xref:configuring-advanced-authorization.adoc[] * xref:administration-guide:configuring-oauth-for-git-providers.adoc[] -* xref:end-user-guide:using-credentials-and-configurations-in-workspaces.adoc[] +* xref:develop:using-credentials-and-configurations-in-workspaces.adoc[] * link:https://docs.openshift.com/container-platform/{ocp4-ver}/authentication/using-rbac.html[OpenShift role-based access control] * link:https://docs.openshift.com/container-platform/{ocp4-ver}/applications/quotas/quotas-setting-per-project.html[Resource quotas per project] * link:https://docs.openshift.com/container-platform/{ocp4-ver}/nodes/clusters/nodes-cluster-limit-ranges.html[Limit ranges] diff --git a/modules/troubleshoot/pages/troubleshooting-devfile-issues.adoc b/modules/troubleshoot/pages/troubleshooting-devfile-issues.adoc index 0875429bf4..a24e0c9532 100644 --- a/modules/troubleshoot/pages/troubleshooting-devfile-issues.adoc +++ b/modules/troubleshoot/pages/troubleshooting-devfile-issues.adoc @@ -80,4 +80,4 @@ Fix common devfile issues that prevent workspaces from starting or operating cor * link:https://devfile.io/docs/2.2.2/what-is-a-devfile[What is a devfile] * link:https://devfile.io/docs/2.2.2/adding-schema-support[Adding devfile schema support to an IDE] * link:https://devfile.io/docs/2.2.2/overview[Devfile customization overview] -* xref:end-user-guide:devfile-introduction.adoc[] +* xref:develop:devfile-introduction.adoc[] From d605cc383071e34ffeb78ac4bf20a0ff65a08b48 Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Thu, 17 Sep 2026 11:49:02 +0530 Subject: [PATCH 2/2] feat: forward-port GitHub Copilot Chat setup into Develop module PR #3097 (procedures: Document GitHub Copilot Chat usage, RomanNikitenko, merged May 18) targeted the 7.117.x release branch directly instead of main, so this content never reached main and was absent from every JTBD category restructure, including this Develop PR. Forward-porting it now (Job 27: "Use AI coding assistants in your workspace"). - Add modules/develop/pages/using-github-copilot-chat.adoc, ported from 7.117.x with fixes: - Add missing [role="_abstract"] tag - Reword abstract to open with "Set up" to match the title verb - Convert 1 inline IMPORTANT: admonition to block-delimited format - Replace "Kubernetes object" with the {kubernetes} attribute - Fix RedHat.TermsWarnings/Using Vale warnings (may->might, appears->is displayed, using->by using) - Nest it under microsoft-visual-studio-code-open-source-ide.adoc in modules/develop/nav.adoc, matching its original 7.117.x placement - On microsoft-visual-studio-code-open-source-ide.adoc (CONCEPT): move the pre-existing Open VSX registry link + the new Copilot Chat link out of body text into a proper [role="_additional-resources"] .Additional resources block (Parameter 2a), with a plain-text bridge sentence in the body pointing to it (Parameter 2b). Keep the existing xref:administration-guide:extensions-for-microsoft-visual-studio-... target as-is -- that page still lives at that path on main and in this branch; it only moves once PR #3143 (Extend) merges, at which point a follow-up xref fix (matching the #3178 precedent) will be needed after that merge, not before. NOTE: :copilot-ext-ver: is still pinned to 0.36.2 from the 7.117.x (DS 3.28 / Che 7.117) era. Needs SME confirmation that this version is still current/compatible on 7.122.x before merge. Vale: 0 errors on all 3 changed files. Remaining warnings are on functional GitHub/Open VSX links and pre-existing URL paths. Co-authored-by: Cursor --- modules/develop/nav.adoc | 1 + ...ft-visual-studio-code-open-source-ide.adoc | 8 +- .../pages/using-github-copilot-chat.adoc | 91 +++++++++++++++++++ 3 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 modules/develop/pages/using-github-copilot-chat.adoc diff --git a/modules/develop/nav.adoc b/modules/develop/nav.adoc index f6c093f39a..a5f346add5 100644 --- a/modules/develop/nav.adoc +++ b/modules/develop/nav.adoc @@ -38,6 +38,7 @@ *** xref:devfile-introduction.adoc[] ** xref:ides-in-workspaces.adoc[] *** xref:microsoft-visual-studio-code-open-source-ide.adoc[] +**** xref:using-github-copilot-chat.adoc[] *** xref:connect-visual-studio-code-to-che-workspace.adoc[] *** xref:defining-a-common-ide.adoc[] ** xref:using-ai-assistants-in-workspaces.adoc[] diff --git a/modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc b/modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc index ba86a31d1b..a3f684897a 100644 --- a/modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc +++ b/modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc @@ -9,7 +9,7 @@ The {prod-short} build of link:https://github.com/microsoft/vscode[Microsoft Visual Studio Code - Open Source] is the default IDE of a new workspace. -You can automate installation of Microsoft Visual Studio Code extensions from the xref:administration-guide:extensions-for-microsoft-visual-studio-code-open-source.adoc[Open VSX registry] at workspace startup. See _Automating installation of Microsoft Visual Studio Code extensions at workspace startup_. +You can automate installation of Microsoft Visual Studio Code extensions from the Open VSX registry at workspace startup. See _Automating installation of Microsoft Visual Studio Code extensions at workspace startup_. For AI-assisted coding with GitHub Copilot Chat in this IDE, see Additional resources. [TIP] ==== @@ -34,4 +34,10 @@ Configure IDE preferences on a per-workspace basis by invoking the link:https:// NOTE: You might see your organization's branding in this IDE if your organization customized it through a branded build. +[role="_additional-resources"] +.Additional resources + +* xref:administration-guide:extensions-for-microsoft-visual-studio-code-open-source.adoc[] +* xref:using-github-copilot-chat.adoc[] + include::partial$proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc[leveloffset=+1] diff --git a/modules/develop/pages/using-github-copilot-chat.adoc b/modules/develop/pages/using-github-copilot-chat.adoc new file mode 100644 index 0000000000..3bf24eab09 --- /dev/null +++ b/modules/develop/pages/using-github-copilot-chat.adoc @@ -0,0 +1,91 @@ +:_content-type: PROCEDURE +:description: Set up GitHub Copilot Chat in a Che workspace +:keywords: copilot, github-copilot, copilot-chat, ai, extensions +:navtitle: Set up GitHub Copilot Chat +:copilot-ext-ver: 0.36.2 + +[id="using-github-copilot-chat"] += Set up GitHub Copilot Chat + +[role="_abstract"] +Set up GitHub Copilot Chat in your {prod-short} workspace by installing the link:https://open-vsx.org/extension/redhat/devspaces-copilot-chat-integration/0.36.2[Dev Spaces Copilot Chat Integration] extension (version {copilot-ext-ver}) and authenticating with your GitHub account to get AI-assisted coding suggestions. + +.Prerequisites + +* A GitHub account with an active link:https://github.com/features/copilot[GitHub Copilot] subscription. +* A running {prod-short} workspace with the Code - OSS editor. +* The following URLs must be accessible from the workspace (ensure they are added to the allowlist if you are in a restricted or air-gapped environment): ++ +-- +** `https://github.com` +** `https://api.github.com` +** `https://api.githubcopilot.com` +-- + +.Procedure + +. Install version {copilot-ext-ver} of the *Dev Spaces Copilot Chat Integration* extension. ++ +Choose one of the following options depending on your Open VSX registry configuration: ++ +-- +* If your {prod-short} instance is configured to use the link:https://open-vsx.org[public Open VSX registry] or a standalone Open VSX registry that contains the extension: ++ +Open the Extensions view by pressing kbd:[Ctrl+Shift+X], search for `Dev Spaces Copilot Chat Integration`, select version *{copilot-ext-ver}*, and click *Install*. + +* If your {prod-short} instance uses the default embedded Open VSX registry or a registry that does not contain the extension, install it manually from a `.vsix` file: ++ +Download the `.vsix` file from the link:https://open-vsx.org/extension/redhat/devspaces-copilot-chat-integration/0.36.2[Open VSX registry], then press kbd:[F1] to open the Command Palette and run `Extensions: Install from VSIX...`. +-- ++ +[IMPORTANT] +==== +Use version {copilot-ext-ver} of the extension. Other versions might not be compatible with the current {prod-short} editor. +==== + +. Authenticate by using Device Authentication. ++ +Press kbd:[F1] to open the Command Palette, type `GitHub: Device Authentication`, and select the command. ++ +[IMPORTANT] +==== +You must complete Device Authentication *before* attempting to use AI features. Initiating "Sign in to use AI Features" without a valid device authentication token causes authentication errors that require signing out and re-authenticating. +==== + +. Complete the device authentication flow. ++ +A notification is displayed with a device code. Click the link to open the GitHub device activation page in your browser, paste the code, and authorize access. + +. Refresh the browser page. ++ +After successful authentication, a notification prompts you to refresh the browser page. Refresh the page to apply the authentication token. Copilot Chat is authenticated automatically and ready to use. + +.Verification + +* Open the Copilot Chat panel, type a prompt such as "Explain this file", and verify that a response is displayed. + +[NOTE] +==== +Device Authentication is a one-time step. The credentials are saved as a `{kubernetes}` object and persist across workspaces on the same cluster. +==== + +.Troubleshooting + +If you attempted to use Copilot Chat before completing Device Authentication, the extension might enter an error state. Typical symptoms include: + +* Copilot Chat is connected but does not respond to prompts. +* The Copilot Chat output log contains errors such as: ++ +[source,text] +---- +Failed to get copilot token. reason: NotAuthorized +GitHub Copilot could not connect to server. Extension activation failed: "Failed to get copilot token. reason: NotAuthorized" +---- + +This happens when *Sign in to use AI Features* is triggered before a valid Device Authentication token exists. + +To recover: + +. Click the *Accounts* icon on the left activity bar, select your account, and click *Sign Out*. A confirmation dialog is displayed indicating the account has been used by the Dev Spaces Copilot Chat Integration. Click *Sign Out* to confirm. +. Press kbd:[F1] to open the Command Palette and run `GitHub: Device Authentication`. Complete the device authentication flow in the browser. +. Refresh the browser page when prompted. Copilot Chat is now ready to use.