SupportConsoleDevelopersStart a trialContact

Chapter 2. User onboarding

If your organization is already running a OpenShift Dev Spaces instance, you can get started as a new user by learning how to start a new workspace, manage your workspaces, and authenticate yourself to a Git server from a workspace:

  1. Section 2.1, “Starting a new workspace with a clone of a Git repository”
  2. Section 2.2, “Starting a new workspace from a devfile URL”
  3. Section 2.3, “Optional parameters for the URLs for starting a new workspace”
  4. Section 2.4, “Basic actions you can perform on a workspace”
  5. Section 2.5, “Authenticating to a Git server from a workspace”

2.1. Starting a new workspace with a clone of a Git repository

Working with OpenShift Dev Spaces in your browser involves multiple URLs:

  • The URL of your organization’s OpenShift Dev Spaces instance, used as part of all the following URLs
  • The URL of the Workspaces page of your OpenShift Dev Spaces dashboard with the workspace control panel
  • The URLs for starting a new workspace
  • The URLs of your workspaces in use

With OpenShift Dev Spaces, you can visit a URL in your browser to start a new workspace that contains a clone of a Git repository. This way, you can clone a Git repository that is hosted on GitHub, a GitLab instance, or a Bitbucket server.

Tip

You can also use the Git Repo URL * field on the Create Workspace page of your OpenShift Dev Spaces dashboard to enter the URL of a Git repository to start a new workspace.

Prerequisites

  • Your organization has a running instance of OpenShift Dev Spaces.
  • You know the FQDN URL of your organization’s OpenShift Dev Spaces instance: https://devspaces-<openshift_deployment_name>.<domain_name>.
  • Optional: You have authentication to the Git server configured.

  • Your Git repository maintainer keeps the devfile.yaml or .devfile.yaml file in the root directory of the Git repository. (For alternative file names and file paths, see Section 2.3, “Optional parameters for the URLs for starting a new workspace”.)

    Tip

    You can also start a new workspace by supplying the URL of a Git repository that contains no devfile. Doing so results in a workspace with Universal Developer Image and with Microsoft Visual Studio Code - Open Source as the workspace IDE.

Procedure

To start a new workspace with a clone of a Git repository:

  1. Optional: Visit your OpenShift Dev Spaces dashboard pages to authenticate to your organization’s instance of OpenShift Dev Spaces.

  2. Visit the URL to start a new workspace using the basic syntax: 

    https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>
    Tip

    You can extend this URL with optional parameters: 

    https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?<optional_parameters> 1
    1
    See Section 2.3, “Optional parameters for the URLs for starting a new workspace”.

    Example 2.1. A URL for starting a new workspace

    https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/che-samples/cpp-hello-world

    Example 2.2. The URL syntax for starting a new workspace with a clone of a GitHub-hosted repository

    With GitHub and GitLab, you can even use the URL of a specific branch of the repository to be cloned:

    • https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/<user_or_org>/<repository> starts a new workspace with a clone of the default branch.
    • https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/<user_or_org>/<repository>/tree/<branch_name> starts a new workspace with a clone of the specified branch.
    • https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/<user_or_org>/<repository>/pull/<pull_request_id> starts a new workspace with a clone of the branch of the pull request.

    After you enter the URL to start a new workspace in a browser tab, it renders the workspace-starting page.

    When the new workspace is ready, the workspace IDE loads in the browser tab.

    A clone of the Git repository is present in the filesystem of the new workspace.

    The workspace has a unique URL: https://devspaces-<openshift_deployment_name>.<domain_name>#workspace<unique_url>.

Tip

Although this is not possible in the address bar, you can add a URL for starting a new workspace as a bookmark by using the browser bookmark manager:

  • In Mozilla Firefox, go to ☰ > Bookmarks > Manage bookmarks Ctrl+Shift+O > Bookmarks Toolbar > Organize > Add bookmark.
  • In Google Chrome, go to ⋮ > Bookmarks > Bookmark manager > Bookmarks bar > ⋮ > Add new bookmark.

Additional resources

2.2. Starting a new workspace from a devfile URL

Working with OpenShift Dev Spaces in your browser involves multiple URLs:

  • The URL of your organization’s OpenShift Dev Spaces instance, used as part of all the following URLs
  • The URL of the devfile
  • The URLs for starting a new workspace
  • The URLs of your workspaces in use

With OpenShift Dev Spaces, you can open a devfile URL in your browser to start a new workspace.

Tip

You can also use the Git Repo URL * field on the Create Workspace page of your OpenShift Dev Spaces dashboard to enter the URL of a devfile to start a new workspace.

Prerequisites

  • Your organization has a running instance of OpenShift Dev Spaces.
  • You know the FQDN URL of your organization’s OpenShift Dev Spaces instance: https://devspaces-<openshift_deployment_name>.<domain_name>.

Procedure

To start a new workspace from a devfile URL:

  1. Optional: Visit your OpenShift Dev Spaces dashboard pages to authenticate to your organization’s instance of OpenShift Dev Spaces.

  2. Visit the URL to start a new workspace using the basic syntax: 

    https://devspaces-<openshift_deployment_name>.<domain_name>#<devfile_url>
    Tip

    You can extend this URL with optional parameters: 

    https://devspaces-<openshift_deployment_name>.<domain_name>#<devfile_url>?<optional_parameters> 1
    1
    See Section 2.3, “Optional parameters for the URLs for starting a new workspace”.

    Example 2.3. A URL for starting a new workspace

    https://devspaces-<openshift_deployment_name>.<domain_name>#https://raw.githubusercontent.com/che-samples/cpp-hello-world/main/devfile.yaml

    Tip

    You can pass your Personal Access Token to the URL to have access to private repositories: 

    https://devspaces-<openshift_deployment_name>.<domain_name>#https://<token>@<host>/<path> 1
    1
    Your Personal Access Token that you generated on the Git provider’s website.

    This works for GitHub, GitLab, Bitbucket, Microsoft Azure, and other providers that support Personal Access Token.

    Verification

    After you enter the URL to start a new workspace in a browser tab, it renders the workspace-starting page. When the new workspace is ready, the workspace IDE loads in the browser tab.

The workspace has a unique URL: https://devspaces-<openshift_deployment_name>.<domain_name>#workspace<unique_url>.

Tip

You can not bookmark a URL for starting a new workspace in the address bar, but you can create the bookmark by using the browser bookmark manager instead:

  • In Mozilla Firefox, go to ☰ > Bookmarks > Manage bookmarks Ctrl+Shift+O > Bookmarks Toolbar > Organize > Add bookmark.
  • In Google Chrome, go to ⋮ > Bookmarks > Bookmark manager > Bookmarks bar > ⋮ > Add new bookmark.
Important

To initiate a clone of the Git repository in the filesystem of the new workspace, the devfile must contain project info.

See https://devfile.io/docs/2.2.0/adding-projects.

Additional resources

2.3. Optional parameters for the URLs for starting a new workspace

When you start a new workspace, OpenShift Dev Spaces configures the workspace according to the instructions in the devfile. When you use a URL to start a new workspace, you can append optional parameters to the URL that further configure the workspace. You can use these parameters to specify a workspace IDE, start duplicate workspaces, and specify a devfile file name or path.

2.3.1. URL parameter concatenation

The URL for starting a new workspace supports concatenation of multiple optional URL parameters by using & with the following URL syntax:

https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?<url_parameter_1>&<url_parameter_2>&<url_parameter_3>

Example 2.4. A URL for starting a new workspace with the URL of a Git repository and optional URL parameters

The complete URL for the browser:

https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/che-samples/cpp-hello-world?new&che-editor=che-incubator/intellij-community/latest&devfilePath=tests/testdevfile.yaml

Explanation of the parts of the URL: 

https://devspaces-<openshift_deployment_name>.<domain_name> 1
#https://github.com/che-samples/cpp-hello-world 2
?new&che-editor=che-incubator/intellij-community/latest&devfilePath=tests/testdevfile.yaml 3
1
OpenShift Dev Spaces URL.
2
The URL of the Git repository to be cloned into the new workspace.
3
The concatenated optional URL parameters.

2.3.2. URL parameter for the IDE

You can use the che-editor= URL parameter to specify a supported IDE when starting a workspace.

Tip

Use the che-editor= parameter when you cannot add or edit a /.che/che-editor.yaml file in the source-code Git repository to be cloned for workspaces.

Note

The che-editor= parameter overrides the /.che/che-editor.yaml file.

This parameter accepts two types of values:

  • che-editor=<editor_key> 

    https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?che-editor=<editor_key>
    Table 2.1. The URL parameter <editor_key> values for supported IDEs
    IDE<editor_key> valueNote

    Microsoft Visual Studio Code - Open Source

    che-incubator/che-code/latest

    This is the default IDE that loads in a new workspace when the URL parameter or che-editor.yaml is not used.

    JetBrains IntelliJ IDEA Community Edition

    che-incubator/che-idea/latest

    Technology Preview.

    Eclipse Theia

    eclipse/che-theia/latest

    Deprecated and will be removed in a future release.

  • che-editor=<url_to_a_file> 

    https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?che-editor=<url_to_a_file>1
    1
    URL to a file with devfile content.
    Tip
    • The URL must point to the raw file content.
    • To use this parameter with a che-editor.yaml file, copy the file with another name or path, and remove the line with inline from the file.

2.3.3. URL parameter for starting duplicate workspaces

Visiting a URL for starting a new workspace results in a new workspace according to the devfile and with a clone of the linked Git repository.

In some situations, you might need to have multiple workspaces that are duplicates in terms of the devfile and the linked Git repository. You can do this by visiting the same URL for starting a new workspace with a URL parameter.

The URL parameter for starting a duplicate workspace is new: 

https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?new
Note

If you currently have a workspace that you started using a URL, then visiting the URL again without the new URL parameter results in an error message.

2.3.4. URL parameter for the devfile file name

When you visit a URL for starting a new workspace, OpenShift Dev Spaces searches the linked Git repository for a devfile with the file name .devfile.yaml or devfile.yaml. The devfile in the linked Git repository must follow this file-naming convention.

In some situations, you might need to specify a different, unconventional file name for the devfile.

The URL parameter for specifying an unconventional file name of the devfile is df=<filename>.yaml: 

https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?df=<filename>.yaml 1
1
<filename>.yaml is an unconventional file name of the devfile in the linked Git repository.
Tip

The df=<filename>.yaml parameter also has a long version: devfilePath=<filename>.yaml.

2.3.5. URL parameter for the devfile file path

When you visit a URL for starting a new workspace, OpenShift Dev Spaces searches the root directory of the linked Git repository for a devfile with the file name .devfile.yaml or devfile.yaml. The file path of the devfile in the linked Git repository must follow this path convention.

In some situations, you might need to specify a different, unconventional file path for the devfile in the linked Git repository.

The URL parameter for specifying an unconventional file path of the devfile is devfilePath=<relative_file_path>: 

https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?devfilePath=<relative_file_path> 1
1
<relative_file_path> is an unconventional file path of the devfile in the linked Git repository.

2.3.6. URL parameter for the workspace storage

If the URL for starting a new workspace does not contain a URL parameter specifying the storage type, the new workspace is created in ephemeral or persistent storage, whichever is defined as the default storage type in the CheCluster Custom Resource.

The URL parameter for specifying a storage type for a workspace is storageType=<storage_type>: 

https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?storageType=<storage_type> 1
1
Possible <storage_type> values:
  • ephemeral
  • per-user (persistent)
  • per-workspace (persistent)
Tip

With the ephemeral or per-workspace storage type, you can run multiple workspaces concurrently, which is not possible with the default per-user storage type.

Additional resources

2.3.7. URL parameter for additional remotes

When you visit a URL for starting a new workspace, OpenShift Dev Spaces configures the origin remote to be the Git repository that you specified with # after the FQDN URL of your organization’s OpenShift Dev Spaces instance.

The URL parameter for cloning and configuring additional remotes for the workspace is remotes=: 

https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?remotes={{<name_1>,<url_1>},{<name_2>,<url_2>},{<name_3>,<url_3>},...}
Important
  • If you do not enter the name origin for any of the additional remotes, the remote from <git_repository_url> will be cloned and named origin by default, and its expected branch will be checked out automatically.
  • If you enter the name origin for one of the additional remotes, its default branch will be checked out automatically, but the remote from <git_repository_url> will NOT be cloned for the workspace.

2.4. Basic actions you can perform on a workspace

You manage your workspaces and verify their current states in the Workspaces page (https://devspaces-<openshift_deployment_name>.<domain_name>/dashboard/#/workspaces) of your OpenShift Dev Spaces dashboard.

After you start a new workspace, you can perform the following actions on it in the Workspaces page:

Table 2.2. Basic actions you can perform on a workspace
ActionGUI steps in the Workspaces page

Reopen a running workspace

Click Open.

Restart a running workspace

Go to ⋮ > Restart Workspace.

Stop a running workspace

Go to ⋮ > Stop Workspace.

Start a stopped workspace

Click Open.

Delete a workspace

Go to ⋮ > Delete Workspace.

2.5. Authenticating to a Git server from a workspace

In a workspace, you can run Git commands that require user authentication like cloning a remote private Git repository or pushing to a remote public or private Git repository.

User authentication to a Git server from a workspace is configured by the administrator or, in some cases, by the individual user:

Additional resources

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.