As a user, you can create a workspace using a direct URL rather than navigating the user dashboard. This blog post describes how to author a URL to start a workspace. The coordinates are organized into the standard sequence shown below.

Authoring a URL to start a workspace

To use a URL to start a workspace you can choose to:

  • Paste the URL in the address bar of your browser.

  • Distribute the URL as a link (in an onboarding procedure, in a pull request comment).

When you click on a URL to start a workspace, Eclipse Che:

  1. Creates or reuses a workspace. A parameter can request to always create a new workspace.

  2. Clones the repository.

  3. Searches for a devfile in the given repository. A parameter can override the default location: .devfile.yaml or devfile.yaml. The devfile describes the containers and commands to use for that project. See the Devfile Documentation. Omitting this file will result in a default container, which provides different languages (including Java, Node.js, Python, PHP, Golang, etc) and tools (including curl, jq, yq, etc).

  4. Starts the containers to use for that project.

  5. Starts the IDE. A parameter can override the default IDE.

URL parameters reference

Table 1. Mandatory repository parameter:
parameter Description example

#<repository_URL>

Repository URL

#https://github.com/eclipse-che/che-server/tree/7.40.x

Table 2. Optional parameters: (? followed by keyword=value)
Keyword Description Example

che-editor=<ide>

IDE

?che-editor=eclipse/che-theia/latest

devfilePath=<devfile>

Devfile path

?devfilePath=.che/my-devfile.yaml

new

Always create a new workspace

?new

Note: ?new keyword has no value

In the last part of the URL, parameter list preceded by ? and using the & separator.

https://che-host#<repository_url>?<parameter_1>&<parameter_2>

Defining the Git repository URL

This syntax is available when using DevWorkspace Operator.

The Git repository URL is mandatory. Che supports following Git providers: GitHub, GitLab, or on-premise Bitbucket.

Add a # character and append the repository URL: #<repository_URL>.

Example 1. Open Eclipse Che Server repository in Eclipse Che hosted by Red Hat

https://workspaces.openshift.com#https://github.com/eclipse-che/che-server.

URL syntax by Git provider

URL syntax for cloning GitHub-hosted repositories to the starting workspace:

  • To clone the default branch on GitHub to the starting workspace:

    #https://github.com/<user_or_org>/<repository>

    Example 2. Cloning the default branch of the Plug-in registry repository.

    #https://github.com/eclipse-che/che-plugin-registry

  • To clone a specified branch on GitHub to the starting workspace:

    #https://github.com/<user_or_org>/<repository>/tree/<branch-name>

    Example 3. Cloning the 7.39.x branch of the Plug-in registry repository.

    #https://github.com/eclipse-che/che-plugin-registry/tree/7.39.x

  • To clone the branch of a pull request on GitHub to the starting workspace:

    #https://github.com/<user_or_org>/<repository>/pull/<pull-request-id>

    Example 4. Cloning the Plug-in registry repository pull request #1097.

    #https://github.com/eclipse-che/che-plugin-registry/pull/1097

URL syntax for cloning GitLab-hosted repositories:

  • To clone the default branch on GitLab to the starting workspace:

    #https://gitlab.com/<user_or_org>/<repository>

  • To clone a specified branch on GitLab to the starting workspace:

    #https://gitlab.com/<user_or_org>/<repository>/-/tree/<branch>

URL syntax for cloning BitBucket-hosted repositories:

Warning
 Eclipse Che supports only on premises BitBucket instances.

Defining the editor or Integrated Development Environment (IDE)

Eclipse Che starts workspaces with a default IDE: Che Theia.

Overriding the default editor is possible with the ?che-editor=<editor-id> parameter. The editor-id comes from the identifier of the IDE in the plug-in registry.

Example 5. Using the next version of Theia (build after each commit)

https://che-host#https://github.com/example/foo?che-editor=eclipse/che-theia/next

Some available IDE keys:

  • eclipse/che-theia/latest

  • eclipse/che-theia/next

  • che-incubator/intellij-community/latest

  • che-incubator/pycharm/latest

  • che-incubator/che-code/insiders

Obtain IDE keys from the plug-in registry by looking at Che Editor type entries.

https://che-host/che-plugin-registry/main/index.json

The parameter ?che-editor accepts a link to the devfile hosted on a public server (with Cross-Origin Resource Sharing (CORS) enabled).

https://che-host#https://github.com/example/foo?che-editor=https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/che-incubator/che-code/insiders/devfile.yaml

Using a different devfile file from the repository

If the devfile file name is different from the default search pattern, which is .devfile.yaml or devfile.yaml, it is possible to override that name.

Use the parameter ?devfilePath=mydevfile.yaml at the end of https://che-host#<git_repository_url>.

https://che-host#https://github.com/example/foo?devfilePath=mydevfile.yaml

The short name for the devfilePath parameter is df.

https://che-host#https://github.com/example/foo?df=mydevfile.yaml

Creating or reusing a workspace

If you enter a URL such as https://che-host#http://github.com/foo/bar and you don’t have any workspace named bar, Eclipse Che creates a workspace named bar and clones the GitHub repository.

Each time you enter a URL such as https://che-host#http://github.com/foo/bar again, Eclipse Che reopens the existing workspace bar.

Always creating a new workspace

To create another workspace each time you enter the same URL, enter the URL appended with ?new in the URL format https://che-host#http://github.com/foo/bar?new. Even if you already have a workspace named bar, each time you enter such URL, Eclipse Che will create another, sequentially named workspace (example: bar-abcde).