Eclipse Che natively supports the Git version control system (VCS), which is provided by the JGit library. Versioning functionality is available in the IDE and in the terminal.

An Subversion (SVN) plug-in also exists, but it is not part of the default Che assembly.

The following sections describe how to connect and authenticate users to a remote Git repository. Any operations that involve authentication on the remote repository need to be done via the IDE interface unless authentication is configured separately for the workspace machine (terminal, commands).

Private repositories require a secure SSH connection. In order to connect to Git repositories over SSH, an SSH key pair needs to be generated. SSH keys are saved in user preferences, so the same key can be used in all workspaces.

HTTPS Git URLs can only be used to push changes when OAuth authentication is enabled. See Enabling authentication with social accounts and brokering.

Generating and uploading SSH keys

SSH keys can be generated in the Che user interface.

  1. Go to Profile > Preferences > SSH > VCS, and click the Generate Key button.

  2. When prompted to provide the host name for your repository, use the bare host name (do not include www or https) as in the example below.

  3. Save the resulting key to your Git-hosting provider account.

The host name is an actual host name of a VCS provider. Examples:,

Using existing SSH keys

You can upload an existing public key instead of creating a new SSH key. When uploading a key, add the host name (using no www or https - as in the example below). Note that the Public key > View button is not be available when using this option because the public file should be generated already.

ssh keys

The following examples are specific to GitHub and GitLab, but a similar procedure can be used with all Git or SVN repository providers that use SSH authentication. See documentation provided by other providers for additional assistance.

The default type of SSH key does not work in Che. The git pull command fails on authorization. To work around the issue, you need a different type of an SSH key.

To convert an existing SSH key to the PEM format, run the following command and substitute <your_key_file> for the path to your key file.

$ ssh-keygen -p -f <your_key_file> -m PEM

Or, to generate a new PEM SSH key instead of the default RFC 4716/SSH2 key, omit the -p flag. Substitute <new_key_file> for the path to the new file.

$ ssh-keygen -f <new_key_file> -m PEM
Example 1. GitHub example

When not using GitHub OAuth, you can manually upload a key. To add the associated public key to a repository or account on

  1. Click your user icon (top right).

  2. Go to Settings > SSH and GPG keys and click the New SSH key button.

  3. Enter a title and paste the public key copied from Che to the Key text field.

ssh github
Example 2. GitLab example

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

  1. Click your user icon (top right).

  2. Go to Settings > SSH Keys.

  3. Enter a title and paste the public key copied from Che to the Key text field.

ssh gitlab

Configuring GitHub OAuth

OAuth for Github allows users to import projects using SSH addresses (git@), push to repositories, and use the Pull Request panel. 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, Eclipse Che.

  5. In the Homepage URL field, enter http://${CHE_HOST}:${CHE_PORT}.

  6. In the Authorization callback URL field, enter http://${CHE_HOST}:${CHE_PORT}/api/oauth/callback.

    github oauth
  7. On Docker, set the following to environment variables in the che.env file (see Docker configuration).

  8. On OpenShift, update the deployment configuration (see OpenShift configuration).

  • Substitute all occurrences of ${CHE_HOST} and ${CHE_PORT} with the URL and port of your Che installation.

  • Substitute <your-github-client-id> and <your-github-secret> with your GitHub client ID and secret.

  • This configuration only applies to single-user deployments of Che. See: Enabling authentication with social accounts and brokering.

Once OAuth is configured, SSH keys are generated and uploaded automatically to GitHub by a user in the IDE in Profile > Preferences > SSH > VCS by clicking the Octocat icon. You can connect to your GitHub account and choose repositories to clone, rather than having to manually type (or paste) GitHub project URLs.

Configuring GitHub OAuth for OpenShift infrastructure

  • A deployed instance of Eclipse Che


OAuth for GitHub allows users to import projects using the SSH addresses (git@), push to repositories, and use the Pull Request panel. The steps listed in this section are performed by an administrative user.

Note that these steps are applicable when a user has Che 6 deployed in the multi-user mode.

To enable automatic SSH key upload to GitHub for users, take the following steps:

  1. In the Overview tab, click the <application-name> to open it.

  2. Click the Keycloak link to open the Red Hat Single Sign-On window.

  3. Expand the Configure tab and then click Identity Providers.

  4. In the Add provider drop-down list, click GitHub. The Add identity provider window is displayed.

  5. In the Add identity provider window:

    1. The Redirect URI field, depending on your Eclipse Che installation, type the Authorization callback URL.

    2. Copy the client ID and the client secret from GitHub and paste them in the Client ID and the Client Secret fields, respectively.

    3. In the Homepage URL and the Authorization callback URL field, depending on your Eclipse Che installation, type the two URLS.

    4. In the Default Scopes field, type repo, user, write:publick_key.

    5. Set Store Tokens and Stored Tokens Readable to ON.

    6. Click Save.

      The Success! The github provider has been created. message indicates success. And, the GitHub provider is added to the Identity Providers window.

      github provider added

      Perform the following steps to set role mapping for non-administrative users.

  6. Expand the Manage tab and then click Users.

  7. Click the Role Mappings tab.

  8. Click the Client Roles drop-down menu and click broker.

  9. In the Available Roles list, click read-token.

  10. Click Add selected.

  11. In the Effective Roles list, click read-token.

The GitHub OAuth is now set for the user.

Configuring GitLab OAuth

OAuth integration with GitLab is not supported. Although GitLab supports OAuth for clone operations, pushes are not supported. A feature request to add support exists in the GitLab issue management system: Allow runners to push via their CI token.

Submitting pull requests using the built-in Pull Request panel

Eclipse Che provides a Pull Request panel to simplify the creation of pull requests for GitHub, BitBucket, and Microsoft VSTS (with Git) repositories.

pr panel

Saving committer name and email

Committer name and email are set in Profile > Preferences > Git > Committer. Once set, every commit will include this information.

Interacting with Git from a workspace

After importing a repository, you can perform the most common Git operations using interactive menus or as terminal commands.

Terminal Git commands require their own authentication setup. This means that keys generated in the IDE work only when Git is used through the IDE menus. Git installed in a terminal is a different Git system. You can generate keys in ~/.ssh there as well.

Use keyboard shortcuts to access the most frequently used Git functionality faster:



Push to remote


Pull from remote


Work with branches


Compare current changes with the latest repository version


Git status highlighting in the project tree and editor

Files in project explorer and editor tabs can be colored according to their Git status:

project explorer editor tabs git colors
  • Green: new files that are staged in index

  • Blue: files that contain changes

  • Yellow: files that are not staged in index

The editor displays change markers according to file edits:

editor git change markers
  • Yellow marker: modified line(s)

  • Green marker: new line(s)

  • White triangle: removed line(s)

Performing Git operations


Commit your changes by navigating to Git > Commit…​ in the main menu, or use the Alt+C shortcut.

git commit tree view
  1. Select files that will be added to index and committed. All files in the selected package or folder in the project explorer are checked by default.

  2. Type your commit message. Optionally, you can select Amend previous commit to modify the previous commit (for more details, see Git commit documentation).

  3. To push your commit to a remote repository by checking the Push committed changes to check-box and select a remote branch.

  4. Click Commit to proceed (the Commit button is active when at least one file is selected and a commit message is present, or Amend previous commit is checked).

Behavior for files in the list view is the same as in the Compare window (see Reviewing changed files section). Double-clicking a file opens diff window with it.

Pushing and pulling

Push your commits by navigating to Git > Remotes…​ > Push in the main menu, or use the Alt+Shift+C shortcut.

git push
  1. Choose the remote repository.

  2. Choose the local and remote branch.

  3. Optionally, you can force select Force push.

Get changes from a remote repository by navigating to Git > Remotes…​ > Pull in the main menu, or use the Alt+P shortcut.

git pull

You can use Rebase instead of merge to keep your local commits on top (for more information, see Git pull documentation).

Managing branches

Manage your git branches by navigating to Git > Branches…​ in the main menu, or use the Ctrl+B shortcut.

git branches window

You can filter the branches view by choosing to see only local or remote branches.

Reviewing changed files

The Git Compare window is used to show files that have changed.

To compare the current state of code to the latest local commit, navigate to Git > Compare > Select-to-what in the main menu, or use the Ctrl+Alt+D shortcut. Another way is to select an object in the project tree and choose Git > Select-to-what from the context menu of an item.

Listing changed files

The Git Compare window shows changed files in the selected object in the project explorer. To see all changes, select a project folder. If only one file has changed, a diff window is shown instead of the compare window.

git compare tree view

By default, affected files are listed as a tree.

The Expand all directories and Collapse all directories options help to get a better view. The View as list button switches the view of changed files to a list, where each file is shown with its full path. To return to the tree view, click Group by directories.

git compare list view
Viewing diffs

To view a diff for a file, select the file and click Compare, or double-click the file name.

You can review changes between two states of code. To view the diff, go to Git > Compare > Select-to-what in main menu. If more than one file has changed, a list of the changed files is opened first. To select a file to compare, double-click it, or select a file, and then click Compare. Another way to open a diff is to select a file in the Projects Explorer and choose Git > Select-to-what from its context menu or directly from the context menu in the editor.

git diff widget

Your changes are shown on the left, and the file being compared to is on the right. The left pane can be used for editing and fixing your changes.

To review multiple files, you can navigate between them using the Previous (or Alt+.) and Next (or Alt+,) buttons. The number of files for review is displayed in the title of the diff window.

The Refresh button updates the difference links between the two panes.

Subversion (SVN)

The SVN plug-in is not included in the default Che build. You can build your own Che assembly with this plugin.