Chapter 11. Using version control

CodeReady Workspaces 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.

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.

11.1. Generating and uploading SSH keys

SSH keys can be generated in the CodeReady Workspaces 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:,

11.1.1. 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 CodeReady Workspaces. 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 11.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 CodeReady Workspaces to the Key text field.
ssh github

Example 11.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 CodeReady Workspaces to the Key text field.
ssh gitlab

11.2. 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, CodeReady Workspaces.
  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 OpenShift, update the deployment configuration.

  • Substitute all occurrences of ${CHE_HOST} and ${CHE_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.

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.

11.3. 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.

11.4. Submitting pull requests using the built-in Pull Request panel

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

pr panel

11.5. Saving committer name and email

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

11.6. 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


11.7. 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)

11.8. Performing Git operations

11.8.1. Commiting

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.

11.8.2. 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).

11.8.3. 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.

11.9. 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.