Chapter 2. Che-Theia IDE basics

This section describes basics workflows and commands for Che-Theia: the native integrated development environment for Red Hat CodeReady Workspaces.

2.1. Defining custom commands for Che-Theia

The Che-Theia IDE allows users to define custom commands in a devfile that are then available when working in a workspace.

The following is an example of the commands section of a devfile.

- name: theia:build
  - type: exec
    component: che-dev
    command: >
    workdir: /projects/theia
- name: run
  - type: vscode-task
    referenceContent: |
             "version": "2.0.0",
               "label": "theia:watch",
                "type": "shell",
                "options": {"cwd": "/projects/theia"},
                "command": "yarn",
                "args": ["watch"]
- name: debug
  - type: vscode-launch
    referenceContent: |
             "version": "0.2.0",
             "configurations": [
               "type": "node",
               "request": "attach",
               "name": "Attach by Process ID",
               "processId": "${command:PickProcess}"
CodeReady Workspaces commands


  • The exec type implies that the CodeReady Workspaces runner is used for command execution. The user can specify the component in whose container the command is executed.
  • The command field contains the command line for execution.
  • The workdir is the working directory in which the command is executed.
Visual Studio Code (VS Code) tasks


  • The type is vscode-task.
  • For this type of command, the referenceContent field must contain content with task configurations in the VS Code format.
  • For more information about VS Code tasks, see the Task section on the Visual Studio User Guide page.
VS Code launch configurations


  • The type is vscode-launch.
  • It contains the launch configurations in the VS Code format.
  • For more information about VS Code launch configurations, see the Debugging section on the Visual Studio documentation page.

For a list of available tasks and launch configurations, see the tasks.json and the launch.json configuration files in the /workspace/.theia directory where the configuration from the devfile is exported to.

2.1.1. Che-Theia task types

There are two types of tasks in a devfile: tasks in the VS Code format and CodeReady Workspaces commands. Tasks from the devfile are copied to the configuration file when the workspace is started. Depending on the type of the task, the task is then available for running:

  • CodeReady Workspaces commands: From the TerminalRun Task menu in the configured tasks section, or from the My Workspace panel
  • Tasks in the VS Code format: From the Run Tasks menu

To run the task definitions provided by plug-ins, select the TerminalRun Task menu option. The tasks are placed in the detected tasks section.

2.1.2. Running and debugging

Che-Theia supports the Debug Adapter Protocol. This protocol defines a generic way for how a development tool can communicate with a debugger. It means Che-Theia works with all implementations.



To debug an application:

  1. Click DebugAdd Configuration to add debugging or launch configuration to the project.

    che theia basics 1
  2. From the pop-up menu, select the appropriate configuration for the application that you want to debug.

    che theia basics 2
  3. Update the configuration by modifying or adding attributes.

    che theia basics 3
  4. Breakpoints can be toggled by clicking the editor margin.

    che theia basics 3 b
  5. Open the context menu of the breakpoint to add conditions.

    che theia basics 3 c
  6. To start debugging, click ViewDebug.

    che theia basics 4
  7. In the Debug view, select the configuration and press F5 to debug the application. Or, start the application without debugging by pressing Ctrl+F5.

    che theia basics 5

2.1.3. Editing a task and launch configuration


To customize the configuration file:

  1. Edit the tasks.json or launch.json configuration files.
  2. Add new definitions to the configuration file or modify the existing ones.


    The changes are stored in the configuration file.

  3. To customize the task configuration provided by plug-ins, select the TerminalConfigure TasksS menu option, and choose the task to configure. The configuration is then copied to the tasks.json file and is available for editing.

2.2. Version Control

Red Hat CodeReady Workspaces natively supports the VS Code SCM model. By default, Red Hat CodeReady Workspaces includes the native VS Code Git extension as a Source Code Management (SCM) provider.

2.2.1. Managing Git configuration: identity

The first thing to do before starting to use Git is to set a user name and email address. This is important because every Git commit uses this information.


  • The Visual Studio Code Git extension installed.


To configure Git identity using the CodeReady Workspaces user interface, go to in Preferences.

  1. Open File > Settings > Open Preferences:

    git config identity
  2. In the opened window, navigate to the Git section, and find:

    And configure the identity.

To configure Git identity using the command line, open the terminal of the Che-Theia container.

  1. Navigate to the My Workspace view, and open Plugins > theia-ide…​ > New terminal:

    terminal git command
  2. Execute the following commands:

    $ git config --global "John Doe"
    $ git config --global

Che-Theia permanently stores this information and restores it on future workspace starts.

2.2.2. Accessing a Git repository via HTTPS



To clone a repository using HTTPS:

  1. Use the clone command provided by the Visual Studio Code Git extension.

Alternatively, use the native Git commands in the terminal to clone a project.

  1. Navigate to destination folder using the cd command.
  2. Use git clone to clone a repository:

    $ git clone <link>

Self-signed SSL certificates are not supported. Use SSH keys instead.

2.2.3. Accessing a Git repository via SSH

Prerequisites Generating an SSH key

A common SSH key that works with all Git providers is present by default. To start using it, add the public key to the Git provider.

To generate an SSH key pair that only works with a particular Git provider:

  1. Run the SSH: generate key pair for particular host command.
  2. After the key is generated, click the View button and copy the public key from the editor.
  3. Add the public key to the Git provider. Adding the associated public key to a repository or account on GitHub

To add the associated public key to a repository or account on GitHub:

  1. Navigate to
  2. Click the drop-down arrow next to the user icon in the top-right corner of the window.
  3. Click SettingsSSH and GPG keys and then click the New SSH key button.
  4. In the Title field, type a title for the key, and in the Key field, paste the public key copied from CodeReady Workspaces.
  5. Click the Add SSH key button.

    che theia basics ssh Adding the associated public key to a Git repository or account on GitLab

To add the associated public key to a Git repository or account on GitLab:

  1. Navigate to
  2. Click the user icon in the top-right corner of the window.
  3. Click SettingsSSH Keys.
  4. In the Title field, type a title for the key and in the Key field, paste the public key copied from CodeReady Workspaces.
  5. Click the Add key button.

    che theia basics ssh keys

2.2.4. Configuring GitHub OAuth

OAuth for Github allows users to clone projects using SSH addresses (git@) and push to repositories.


To enable automatic SSH key upload to GitHub for users:

  1. On, click your user icon (top right).
  2. Go to Settings > Developer settings > OAuth Apps.
  3. Click the Register a new application button.
  4. In the Application name field, enter, for example, Red Hat CodeReady Workspaces.
  5. In the Homepage URL field, enter http://$\{CODEREADY_HOST}:$\{CODEREADY_PORT}.
  6. In the Authorization callback URL field, enter http://$\{CODEREADY_HOST}:$\{CODEREADY_PORT}/api/oauth/callback.

    github oauth
  • Substitute all occurrences of ${CODEREADY_HOST} and ${CODEREADY_PORT} with the URL and port of your CodeReady Workspaces installation.
  • Substitute <your-github-client-id> and <your-github-secret> with your GitHub client ID and secret.

2.2.5. Managing pull requests using the GitHub PR plug-in

To manage GitHub pull requests, the VS Code GitHub Pull Request plug-in is available in the list of plug-ins of the workspace. Using the GitHub Pull Requests plug-in

  1. Authenticate by running the GitHub Pull Requests: Manually Provide Authentication Response command and paste the GitHub token.
  2. Select the repository permissions when generating the token. Creating a new pull request

  1. Open the GitHub repository. To be able to execute remote operations, the repository must have a remote with an SSH URL.
  2. Checkout a new branch and make changes that you want to publish.
  3. Run the GitHub Pull Requests: Create Pull Request command.

2.3. Che-Theia Troubleshooting

This section describes some of the most frequent issues with the Che-Theia IDE.

Che-Theia shows a notification with the following message: Plugin runtime crashed unexpectedly, all plugins are not working, please reload the page. Probably there is not enough memory for the plugins.

This means that one of the Che-Theia plug-ins that are running in the Che-Theia IDE container requires more memory than the container has. To fix this problem, increase the amount of memory for the Che-Theia IDE container:

  1. Navigate to the CodeReady Workspaces Dashboard.
  2. Select the workspace in which the problem happened.
  3. Switch to the Devfile tab.
  4. In the components section of the devfile, find a component of the cheEditor type.
  5. Add a new property, memoryLimit: 1024M (or increase the value if it already exists).
  6. Save changes and restart the workspace.

Additional resources