eclipse-che · gtrivedi88 · Jul 10, 2026
@@ -7,7 +7,8 @@ start_page: discover:what-is-che.adoc
 nav:
   - modules/discover/nav.adoc
   - modules/install/nav.adoc
-  - modules/get-started/nav.adoc
+  - modules/get-started-admin/nav.adoc
+  - modules/get-started-user/nav.adoc
   - modules/end-user-guide/nav.adoc
   - modules/upgrade/nav.adoc
   - modules/secure/nav.adoc

@@ -1,5 +1,6 @@
 .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[]
@@ -38,7 +39,7 @@
 * xref:using-credentials-and-configurations-in-workspaces.adoc[]
 ** xref:mounting-secrets.adoc[]
 *** xref:creating-image-pull-secrets.adoc[]
-*** xref:get-started:using-a-git-provider-access-token.adoc[]
+*** xref:get-started-user:using-a-git-provider-access-token.adoc[]
 ** xref:mounting-configmaps.adoc[]
 *** xref:mounting-git-configuration.adoc[]
 *** xref:mounting-ssh-configuration.adoc[]

@@ -0,0 +1,76 @@
+:_content-type: PROCEDURE
+:description: Start a cloud development environment from a raw devfile URL
+:keywords: start-new-workspace, start-a-new-workspace, how-to-start-new-workspace, how-to-start-a-new-workspace, starting-a-new-workspace, how-to-start-workspace, how-to-start-a-workspace
+:navtitle: Start a cloud development environment from a raw devfile URL
+:page-aliases: get-started:starting-a-workspace-from-a-raw-devfile-url.adoc
+
+[id="starting-a-workspace-from-a-raw-devfile-url"]
+= Start a cloud development environment from a raw devfile URL
+
+[role="_abstract"]
+Start a cloud development environment from a devfile hosted outside your Git repository so that you can share a standard development environment across teams or test devfile changes before committing them.
+
+// vale RedHat.Spelling = NO
+
+TIP: You can also use the *Git Repo URL* field on the *Create Workspace* page of your {prod-short} dashboard to enter the URL of a devfile to start a new cloud development environment.
+
+// vale RedHat.Spelling = YES
+
+.Prerequisites
+
+* You have a running instance of {prod-short}.
+* You know the Fully Qualified Domain Name (FQDN) URL of your organization's {prod-short} instance: `pass:c,a,q[{prod-url}]`.
+* You have a devfile that includes project information to clone the Git repository. See https://devfile.io/docs/2.2.0/adding-projects.
+
+.Procedure
+
+. Optional: Open the {prod-short} dashboard to authenticate to your organization's instance of {prod-short}.
+
+. Enter the devfile URL in your browser to start a new cloud development environment.
++
+For a public repository:
++
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__<devfile_url>__
+----
++
+For a private repository, include your personal access token in the URL:
++
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__https://__<token>__@__<host>__/__<path_to_devfile>
+----
++
+where:
++
+`__<token>__`:: Your personal access token that you generated on the Git provider's website. This method works for GitHub, GitLab, Bitbucket, Microsoft Azure, and other providers that support Personal Access Token.
++
+[IMPORTANT]
+====
+Automated Git credential injection does not work with token-embedded URLs. To configure Git credentials separately, see xref:get-started-user:using-a-git-provider-access-token.adoc[].
+====
++
+To append optional parameters, add `?__<optional_parameters>__` to the URL. See xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for cloud development environment URLs] for supported parameters.
++
+For example:
++
+* Public repository: `pass:c,a,q[{prod-url}#https://raw.githubusercontent.com/che-samples/cpp-hello-world/main/devfile.yaml]`
+* Private repository: `pass:c,a,q[{prod-url}#https://__<token>__@raw.githubusercontent.com/che-samples/cpp-hello-world/main/devfile.yaml]`
+
+.Verification
+
+* After you enter the URL, the starting page is displayed in the browser tab.
+* When the cloud development environment is ready, the IDE loads automatically.
+* The cloud development environment has a unique URL: `pass:c,a,q[{prod-url}]/__<user_name>__/__<unique_url>__`.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for cloud development environment URLs]
+* xref:get-started-user:basic-actions-you-can-perform-on-a-workspace.adoc[]
+* xref:get-started-user:using-a-git-provider-access-token.adoc[]
+* xref: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
@@ -0,0 +1,6 @@
+.Get Started as an Administrator
+* Prepare the platform for developers
+** xref:your-first-week-as-administrator.adoc[]
+** xref:verify-the-platform-end-to-end.adoc[]
+** xref:configure-github-oauth-for-your-team.adoc[]
+** xref:what-to-configure-next.adoc[]
@@ -0,0 +1,71 @@
+:_content-type: PROCEDURE
+:description: Configure GitHub OAuth for your team
+:keywords: github, oauth, authentication, credentials
+:navtitle: Configure GitHub OAuth for your team
+
+[id="configure-github-oauth-for-your-team"]
+= Configure GitHub OAuth for your team
+
+[role="_abstract"]
+Configure a GitHub OAuth application so that developers can clone repositories and push code from {prod-short} workspaces without manually entering credentials. This procedure covers GitHub.com and GitHub Enterprise Cloud. For other providers, see the Additional resources.
+
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+* You are logged in to GitHub with an account that has permission to create OAuth applications for your organization.
+
+.Procedure
+
+. Go to the link:https://github.com/settings/applications/new[GitHub OAuth application registration page].
+
+. Enter the following values:
++
+.. *Application name*: `pass:c,a,q[{prod-short}]`
+.. *Homepage URL*: `pass:c,a,q[{prod-url}]/`
+.. *Authorization callback URL*: `pass:c,a,q[{prod-url}]/api/oauth/callback`
+
+. Click *Register application*.
+
+. Click *Generate new client secret*.
+
+. Copy the *Client ID* and the *Client Secret*. You need both values in the next step.
+
+. Prepare and apply the {orch-name} Secret:
++
+[source,yaml,subs="+quotes,+attributes,+macros"]
+----
+kind: Secret
+apiVersion: v1
+metadata:
+  name: github-oauth-config
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: oauth-scm-configuration
+  annotations:
+    che.eclipse.org/oauth-scm-server: github
+type: Opaque
+stringData:
+  id: __<GitHub_OAuth_Client_ID>__
+  secret: __<GitHub_OAuth_Client_Secret>__
+----
+
+. Apply the Secret:
++
+[source,bash,subs="+quotes,+attributes"]
+----
+$ {orch-cli} apply -f - <<EOF
+<Secret_prepared_in_the_previous_step>
+EOF
+----
+
+.Verification
+
+* The output displays `secret/github-oauth-config created`.
+* A developer creates a new workspace from a private GitHub repository and is not prompted for credentials.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:administration-guide:configuring-oauth-for-git-providers.adoc[Connect Git providers with OAuth for GitHub, GitLab, Bitbucket, and Azure DevOps]
+* link:https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[GitHub Docs: Creating an OAuth App]
@@ -0,0 +1,62 @@
+:_content-type: PROCEDURE
+:description: Verify the platform works end-to-end
+:keywords: verify, installation, dashboard, test workspace
+:navtitle: Verify the platform works end-to-end
+
+[id="verify-the-platform-end-to-end"]
+= Verify the platform works end-to-end
+
+[role="_abstract"]
+Verify that {prod-short} is operational by checking the Operator status, opening the dashboard, and creating a test workspace. This confirms that the full pipeline works before you invite developers.
+
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+* You have installed {prod-short} on an {orch-name} cluster. See xref:install:installing-che.adoc[Install {prod-short}].
+
+.Procedure
+
+. Verify that the {prod-short} Operator pod is running:
++
+[source,bash,subs="+attributes"]
+----
+$ {orch-cli} get pods -n {prod-namespace} -l app.kubernetes.io/component={prod-id-short}-operator
+----
+
+. Verify that the `CheCluster` custom resource reports no errors:
++
+[source,bash,subs="+attributes"]
+----
+$ {orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.status.chePhase}'
+----
++
+The expected output is `Active`.
+
+. Retrieve the {prod-short} dashboard URL:
++
+[source,bash,subs="+attributes"]
+----
+$ {orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.status.cheURL}'
+----
+
+. Open the URL in a web browser and log in with your {orch-name} credentials.
+
+. On the *Create Workspace* page, click any sample (for example, *Python*) to start a test workspace.
+
+. Wait for the workspace to start. The first start takes 2-3 minutes while container images are pulled to the cluster node.
+
+. Confirm that the IDE loads in your browser tab and that you can open a terminal.
+
+. Return to the *Workspaces* page and stop the test workspace by selecting *⋮* > *Stop Workspace*.
+
+.Verification
+
+* The {prod-short} dashboard loads and displays the *Create Workspace* page.
+* A test workspace starts and the IDE loads in the browser.
+* You can open a terminal in the workspace.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:install:proc_verifying-the-installation.adoc[Confirm {prod-short} is running]
+* xref:install:proc_finding-the-fully-qualified-domain-name-fqdn.adoc[Get the dashboard URL to share with your team]
@@ -0,0 +1,39 @@
+:_content-type: REFERENCE
+:description: What to configure next after verifying the platform and configuring Git access
+:keywords: configuration, next steps, post-installation
+:navtitle: What to configure next
+
+[id="what-to-configure-next"]
+= What to configure next
+
+[role="_abstract"]
+After verifying the platform and configuring Git access, continue with these configuration tasks based on your organization's priorities.
+
+.Post-installation configuration tasks
+[cols="1,2,1",options="header"]
+|===
+| Priority | Task | Guide
+
+| Recommended
+| Speed up workspace starts by pre-caching container images on cluster nodes.
+| xref:optimize:caching-images-for-faster-workspace-start.adoc[Speed up workspace starts with image caching]
+
+| Recommended
+| Configure workspace resource limits, idle timeouts, and the number of workspaces per user.
+| xref:administration-guide:configuring-workspaces-globally.adoc[Set workspace policies for all users]
+
+| Recommended
+| Configure OAuth for additional Git providers (GitLab, Bitbucket, Azure DevOps).
+| xref:administration-guide:configuring-oauth-for-git-providers.adoc[Connect Git providers with OAuth]
+
+| As needed
+| Control access to {prod-short} with role-based access control.
+| xref:secure:managing-identities-and-authorizations.adoc[Control access to {prod-short}]
+
+| As needed
+| Customize the `CheCluster` custom resource to change {prod-short} behavior.
+| xref:administration-guide:understanding-the-checluster-custom-resource.adoc[Customize the central configuration]
+
+|===
+
+Share the {prod-short} dashboard URL with your developers. They can find their first-day instructions in the xref:get-started-user:your-first-workspace.adoc[Get started as a developer] guide.
@@ -0,0 +1,29 @@
+:_content-type: CONCEPT
+:description: Your first week as a platform administrator
+:keywords: getting started, administrator, post-installation, onboarding
+:navtitle: Your first week as a platform administrator
+
+[id="your-first-week-as-administrator"]
+= Your first week as a platform administrator
+
+[role="_abstract"]
+After installing {prod-short}, complete a short sequence of configuration tasks before inviting developers to the platform. Each task builds on the previous one and takes you from a fresh deployment to a production-ready environment.
+
+Your post-installation tasks follow this order:
+
+. *Verify the platform works end-to-end.* Confirm that the Operator is healthy, the dashboard loads, and a test workspace starts successfully.
+
+. *Configure Git provider access.* Connect {prod-short} to your organization's Git provider with OAuth so that developers can clone repositories and push code without manually configuring credentials.
+
+. *Share the dashboard URL with developers.* After verification and Git configuration, share the {prod-short} dashboard URL with your team. Developers can start coding immediately by entering a Git repository URL on the *Create Workspace* page.
+
+. *Tune the platform for your environment.* Adjust workspace resource limits, enable image caching for faster starts, and configure security policies based on your organization's requirements.
+
+The first three tasks are covered in this guide. The fourth task is covered across the Secure, Optimize, and Configure guides.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:secure:managing-identities-and-authorizations.adoc[Secure {prod-short}]
+* xref:optimize:caching-images-for-faster-workspace-start.adoc[Speed up workspace starts with image caching]
+* xref:administration-guide:understanding-the-checluster-custom-resource.adoc[Customize the central configuration]
@@ -0,0 +1,8 @@
+.Get Started as a Developer
+* Create your first cloud workspace
+** xref:your-first-workspace.adoc[]
+** xref:starting-a-workspace-from-a-git-repository-url.adoc[]
+** xref:basic-actions-you-can-perform-on-a-workspace.adoc[]
+* Connect to your Git repositories
+** xref:authenticating-to-a-git-server-from-a-workspace.adoc[]
+*** xref:using-a-git-provider-access-token.adoc[]
@@ -0,0 +1,29 @@
+:_content-type: CONCEPT
+:description: How Git authentication works in cloud development environments
+:keywords: authentication, authenticate, github, gitlab, bitbucket
+:navtitle: How Git authentication works in cloud development environments
+:page-aliases: end-user-guide:authenticating-to-a-git-server-from-a-workspace.adoc, get-started:authenticating-to-a-git-server-from-a-workspace.adoc
+
+[id="authenticating-to-a-git-server-from-a-workspace"]
+= How Git authentication works in cloud development environments
+
+// vale RedHat.CaseSensitiveTerms = NO
+
+[role="_abstract"]
+When you clone a private repository or push code from a cloud development environment, {prod-short} needs credentials to access your Git provider. Authentication can be configured at the platform level by your administrator or individually with a personal access token.
+
+User authentication to a Git server from a cloud development environment is configured by the administrator or, in some cases, by the individual user:
+
+* Your administrator configures an OAuth application on GitHub, GitLab, Bitbucket, or Microsoft Azure Repos for your {prod} instance.
+
+* Alternatively, individual users create their own {kubernetes} Secrets for personal Git-provider access tokens or configure SSH keys.
+
+[role="_additional-resources"]
+.Additional resources
+* xref:using-a-git-provider-access-token.adoc[Using a Git-provider access token]
+// 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
+* xref:administration-guide:configuring-oauth-for-git-providers.adoc[Give developers credential-free Git access]
+
+// vale RedHat.CaseSensitiveTerms = YES
@@ -0,0 +1,35 @@
+:_content-type: REFERENCE
+:description: Manage your cloud development environments from the dashboard
+:keywords: workspace, workspaces, reopen, restart, stop, start, delete
+:navtitle: Manage your cloud development environments
+:page-aliases: end-user-guide:basic-actions-you-can-perform-on-a-workspace.adoc, get-started:basic-actions-you-can-perform-on-a-workspace.adoc
+
+[id="basic-actions-you-can-perform-on-a-workspace"]
+= Manage your cloud development environments
+
+[role="_abstract"]
+Stop, restart, and delete cloud development environments from the {prod-short} dashboard to control resource usage and keep your environment organized. Access the *Workspaces* page at `pass:c,a,q[{prod-url}]/dashboard/#/workspaces`.
+
+.Cloud development environment actions
+[cols="1,2",options="header"]
+|===
+| Action | GUI steps in the *Workspaces* page
+
+| _Reopen a running cloud development environment_
+| Click *Open*.
+
+| _Restart a running cloud development environment_
+| Go to *⋮* *>* *Restart Workspace*.
+
+| _Stop a running cloud development environment_
+| Go to *⋮* *>* *Stop Workspace*.
+
+| _Start a stopped cloud development environment_
+| Click *Open*.
+
+| _Delete a cloud development environment_
+| Go to *⋮* *>* *Delete Workspace*.
+
+|===
+
+NOTE: Each cloud development environment is an {orch-name} `DevWorkspace` custom resource. You can also manage cloud development environments from the command line with `{orch-cli}` or `kubectl`. See xref:end-user-guide:managing-workspaces-with-apis.adoc[].