Introduction

Gitpod is frictionless coding.

Whether you just want to hack, have code to review or feel like trying something new on GitHub, Gitpod beams you right into a ready-to-code dev environment with a single click.

Because Gitpod is based on OSS tech like VS Code, Docker and Kubernetes, it is familiar, comprehensive, extensible, and easy to use. With deep GitHub integration, tools for sharing, and a focus on usability, Gitpod contains your entire dev workflow in a browser tab.

Unlike traditional cloud and desktop IDEs, Gitpod understands the context and prepares the IDE automatically. For instance, if you are creating a Gitpod workspace from a GitHub pull request, the IDE will open in code-review mode.

Also, Gitpod workspaces are meant to be disposable. That is, you do not need to maintain anything. They are created when you need them, and you can forget about them when you are done. Simply go to GitHub and create a fresh workspace whenever you need one.

The IDE is open-source and based on Eclipse Theia. Theia is highly extensible and builds upon mature technologies such as TypeScript, VS Code, Webpack, and Node.js.

This site provides all the details on how to use Gitpod and Theia. If you have questions or want discuss something, please join the Gitpod community on Spectrum.

Architecture

Gitpod.io runs in multiple Kubernetes clusters hosted on Google Cloud infrastructure in three different regions:

Gitpod Cluster Map

When starting a workspace, Gitpod will automatically pick the cluster that is closest to your location and start a Kubernetes pod in it. The requested git repository gets cloned and the branch you need is checked out. Furthermore, Gitpod runs any scripts that are configured for that git repository state.

Learn more about how to configure your GitHub repository here.

Getting Started

Gitpod delivers the IDE part for the web-based development flows of common code hosting platforms. The following example shows how to use Gitpod with a GitHub repository.

  1. Point your browser to some GitHub repository, pull request, or issue, e.g. https://github.com/arunoda/learnnextjs-demo

  2. Either prefix the URL in the address bar of your browser with https://gitpod.io# (e.g. https://gitpod.io#https://github.com/arunoda/learnnextjs-demo) or push the Gitpod button if you have installed the Gitpod extension.

  3. On first use you will have to authorize access to your GitHub account. This is necessary so you can access your data from within Gitpod.

  4. Gitpod will now launch a workspace container for you in the cloud, containing a full Linux system. It will also clone the GitHub repository branch based on the GitHub page you were coming from.

Next up you should learn about Gitpod's IDE.

Browser Extension

Creating a workspace is as easy as prefixing any GitHub URL with gitpod.io#.

For convenience, we built the Gitpod browser extension. It adds a button to GitHub that does the prefixing for you. Nothing more.

We provide the extension for

Browser Extension

Workspaces

A workspace is what you code in, it consists of the files, configuration and the underlying docker file. Workspace are created on the fly driven by convention and configuration.

A Gitpod workspace can be created from any GitHub project, branch, issue, or pull request. Very soon Gitpod will support additional platforms and integrate with GitLab, Bitbucket, and Jira.

In Gitpod workspaces usually have a very short life. Gitpod creates one when you need it and forgets about when you are done. There is no reason to get back and do any maintainance. Because everything is driven by configuration, you can always create a fresh one when you need it.

Context URLs

Gitpod derives the workspace context from the URL of the repository page from which it was started. Different issues, pull requests, or branches will result in different workspaces, allowing developers to easily perform individual tasks in their own isolated environments.

Each workspace includes a full Linux container. From the IDE's terminal, the user can directly access all development tools of the Linux system and even install missing ones.

In the following we describe the supported contexts and what they do:

GitHub Project Context

Creating a Gitpod workspace from the project's base URL does not carry a lot of context. Gitpod will check out the master branch and open the Readme.md if it exists.

An example for this context is https://github.com/arunoda/learnnextjs-demo.

GitHub File Context

The file context is an extension to the project context, in that Gitpod will check out the corresponding branch and open the respective file in an editor.

An example for this context is https://github.com/arunoda/learnnextjs-demo/blob/getting-started/pages/index.js.

When pointing to a directory, e.g. https://github.com/arunoda/learnnextjs-demo/tree/create-dynamic-pages/pages, Readme.md will be opened if it exists there.

GitHub Issue Context

When starting a workspace from a GitHub issue, a local branch named GH-{issue-number} will be created, based on the remote's default branch. In most cases that will be origin/master.

In addition, the commit message is preconfigured with fixes #{organization}/{repo}#{issue-number}. This will automatically close the GitHub issue once such a commit is merged into the default branch.

As soon as changes have been committed locally, the Pull Request view on the right can be used to push changes to a remote repository and create a pull request.

GitHub Pull Request Context

Starting workspaces from pull requests will clone the respective branch and open the file changes of the PR in a view on the left. The first change is opened in the diff editor. Also the Pull Request view on the right is configured to reflect the PR information.

This context is meant for code reviews or to take action on feedback you got from a reviewer.

Life of a Workspace

Gitpod makes creating fresh workspaces as easy as clicking a button on a GitHub page. In most cases it is easier to create fresh workspaces rather than going back to older ones. See the dashboard documentation on where to find your workspace history and how to restart the older workspaces.

Timeouts

Any running workspace will automatically stop after 30 minutes of inactivity. Activity is triggered by any action in the IDE; moving the mouse is enough. If the IDE is still open, but the corresponding workspace has stopped, a dialog will pop up that lets you start the workspace again.

For convenience, closing the browser window/tab containing the IDE reduces the timeout to 5 minutes.

Stop and Archive

If you want more control over your Gitpod hours, you can stop your workspace explicitly. To do so, click on the avatar in the top right and choose the Stop Workspace command (also available through the command palette). The dialog will ask if you want to archive the workspace. By default, archived workspaces are not shown in the workspace list of the dashboard and will not be considered when starting a fresh workspace for the same context URL.

Workspaces can also be stopped, started, archived, and unarchived from the dashboard.

Changes are Saved

Gitpod continuously backs up the current state of the workspace's repository in the cloud, so that you can revisit it later. Files in other locations will not be saved. Gitpod never deletes a workspace. See dashboard for details.

Starting: Initial and Restart

Gitpod workspaces have two start modes, for which you can configure dedicated tasks on startup:

  • initial
  • restart

Read more about how to configure tasks in configuring start tasks.

Collaboration & Sharing of Workspaces

There are two diffeent ways to share your workspaces, you can share

Sharing Running Workspaces

Sharing running workspaces allows to quickly look at the same workspace together with a (remote) colleague. It is similar to collaborating on Google Docs, in that you can see who is online and look at the same code and processes.

All users in one workspace share the Theia backend and the filesystem. Opened editors, terminals, and other UI state are currently not shared.

How To Share and Unshare a Running Workspace

Running workspaces can be shared from the dashboard or from within the IDE. In the IDE, right-click on the user's avatar and choose

Share Running Workspace.

Provide the URL shown in the dialog to anyone you want to share your workspace with.

Security note:

Beware, anybody with this URL and a Gitpod account will be able to access the workspace as long as it is shared and running.

Every action towards git in a shared workspace happens on behalf of the workspace owner's account without further authorization. It is highly recommended to give workspace URLs only to trusted users and unshare workspaces as soon as sharing them is no longer necessary.

A running Gitpod workspace really is your personal machine.

By unsharing the workspace, the link becomes useless to anybody but the workspace owner. All users that are currently looking at your workspace will be shown as avatars in the top right corner of the IDE.

Sharing Snapshots

You can take snapshot URLs of your workspaces at any time and share them with others. Anyone clicking on such a snapshot link will get a complete clone of your workspace, including the

  • state of the workspace
  • the IDE layout

Even initially workspaces based snapshot are treated as restarts, so you can configure them to launch differently than if you had created a fresh workspace from git. Also, this is useful if you want to create easy to consume reproducible workspace states, for issues, stackoverflow answers, trainings, etc.

Unlike sharing running workspaces snapshoted workspaces are full copies. This means users can do what ever they like with the content. And of course, no access to any of your credentials is shared.

Read more about this feature here.

How To Take a Snapshot URL

Creating a snapshot is simple. You can either use the command palette (F1) or find the action item in the avatar menu on the top right.

Once you execute it, the snapshot is taken and the URL is shown in a dialog.

Command Line Interface

Gitpod sports a command line interface that is available in each workspace terminal called gp:

Command line interface for Gitpod

Usage:
  gp [command]

Available Commands:
  help              Help about any command
  init              Create a new .gitpod.yml file
  open              Opens a file in Gitpod
  preview           Opens a URL in Theia's preview view
  url               Prints the URL of this workspace
  forward-port      Makes a port available on 0.0.0.0 so that it can be exposed to the internet

Flags:
  -h, --help   help for gp

Use "gp [command] --help" for more information about a command.

Init

Gitpod workspaces can be configured - see Configuring Workspaces for more details. gp init helps creating this configuration by guiding through this process and producing a gitpod.yml in the end (think npm init).

Open

Modern editors/IDE's sport command line tooling to open a file (e.g. VS Code code foo.txt). In Gitpod this can be done using gp open <filename>. We have also added common aliases for gp open: code and open.

Preview

gp preview is similar to gp open, except that it does not open a file in the editor but a URL in a preview pane on the right.

URL

Gitpod workspaces can expose services to the internet. gp url provides the URL which points to a service served from a Gitpod workspace. For example gp url 8080 prints the URL which points to the service listening on port 8080 in this current workspace.

You can combine the previewand the url command to open a certain path instead of the default URL.

For instance:

gp preview $(gp url 3000)my/path/index.html

If you put this into the .gitpod.yml to open the a certain page on startup, don't forget to ignore the default action when the port opens.

Forward Port

In Gitpod services/servers running on a port need to be exposed before they become accessible from the internet. This process only works with services listening on 0.0.0.0 and not just localhost. Sometimes it is not possible to make a server listen on 0.0.0.0, e.g. because it is not your code and there are simply no means of configuration.

In that case, gp forward-port <port> can be used to forward all traffic form a socket listing on all network interfaces to your process listening on localhost only.

Configuring Your Repository

Gitpod workspaces are started with a single click. In order to make sure they come with the tools you need and work correctly you can provide configuration.

Gitpod Config File

A workspace gets configured through a .gitpod.yml file written in YAML syntax. Here's an example:

# The Docker image to run your workspace in. Defaults to gitpod/workspace-full
image: "<your-workspace-image>"
# Command to start on workspace startup (optional)
tasks:
  - command: "yarn install && yarn build"
# Ports to expose on workspace startup (optional)
ports:
  - port: 8000

There are three ways you can provide this file:

Checked-in Gitpod Config File

The simplest and preferred option is to check in a .gitpod.yml file into your repository. This way you version your workspace configuration together with your code. If, for example, you need to go back to an old branch that required a different Docker image, it will start with the correct image, since that bit of configuration is part of your codebase.

definitely-gp Repository

Sometimes you can't check in a .gitpod.yml file, for instance because you do not have sufficient access rights. However, you can still provide a .gitpod.yml file through the central definitely-gp repository. Note that it contains .gitpod.yml files for public GitHub repositories only. To add your .gitpod.yml file to definitely-gp, simply raise a PR.

Inferred Gitpod Config File

If the first two locations do not have a .gitpod.yml file for your project, Gitpod will compute one by analyzing your project and using good common defaults.

Creating a Gitpod Config File

Gitpod comes with a cli, that walks you through the initial creation of a .gitpod.yml file. Open a terminal and type

gp init

It will ask you about the different configuration options and generate and open an initial .gitpod.yml file for you. You can now edit directly in the file supported by validation, completion and hovers providing information about the various options.

Docker Image

If the standard Docker image that is provided by Gitpod does not include all the tools you need for developing your project, you can provide a custom Docker image.

Configure a Custom Docker Image

There are two ways to configure a custom Docker image in your .gitpod.yml file:

  • Reference a publicly available image:

    image: node:alpine
    

    The official Gitpod Docker images are hosted on DockerHub.

  • Reference a Dockerfile next to your .gitpod.yml file:

    image:
      file: docker/gitpod.Dockerfile
      # Context is optional, defaults to an empty context
      context: docker
    

    The Docker image is rebuilt automatically whenever the Dockerfile changes.

Creating Docker Images for Gitpod

A good starting point for creating custom Docker Images is the gitpod/workspace-full image. It already contains all the tools necessary to work with all languages Gitpod supports. You can find the source code in this GitHub repository.

FROM gitpod/workspace-full

# install custom tools, runtime, etc.

When you are launching the Gitpod IDE, the local console will use the gitpod user, so all local settings, config file, etc. should apply to /home/gitpod or be run using USER gitpod.

Switching users in the Dockerfile to gitpod requires switching back to USER root at the end of the Dockerfile, so that the IDE can start. The following example shows a typical Dockerfile inheriting from gitpod/workspace-full:

FROM gitpod/workspace-full:latest

USER root
# Install custom tools, runtime, etc.
RUN apt-get update && apt-get install -y \
        ... \
    && apt-get clean && rm -rf /var/cache/apt/* && rm -rf /var/lib/apt/lists/* && rm -rf /tmp/*

USER gitpod
# Apply user-specific settings
ENV ...

# Give back control
USER root

See also Gero's blog post running through an example.

Exposing Ports

If you want to access services running in your workspace, e.g. a development HTTP server on port 8080, you need to expose that port first. Gitpod has two means of doing that:

  1. On-the-fly: when you start a process which listens on a port in your workspace, Gitpod will ask you if you want to expose that port to the internet.
  2. In your configuration: if you already know that you want a particular port exposed, you can configure it in the .gitpod.yml file and skip the extra click later on. For example:
ports:
  - port: 8080

Ports are mapped to their own URLs. In a workspace you can get the URL mapped to a port using gp url <port>. At the moment you can only expose HTTP servers.

Configure the Opening Behavior

When a newly started service gets detected, you usually get a notification telling you about it. If it is not yet exposed, because it is not listed in the .gitpod.yml, the notification will allow you to expose the port. If it is already exposed, either through the .gitpod.yml or by manually exposing it, the notification asks whether and how to open it.

Ports Notification

To change this behavior you can provide the property onOpen. It has four possible values:

  • notify (default) - Show the notification.
  • open-preview - Open in the preview on the right.
  • open-browser - Open in a browser tab.
  • ignore - Don't do anything.

Any changes to the .gitpod.yml will have effect immediately.

Ports Notification

Start Tasks

When starting or restarting a workspace you typically want to run certain tasks. Most probably that includes the build and maybe also running tests and automatically start the application in e.g. a dev server.

Gitpod allows you to configure start tasks in the .gitpod.yml file.

For instance, the start script for the Gitpod documentation repository is defined as:

tasks:
- command: mdbook serve --hostname 0.0.0.0

You can have multiple tasks, which are opened on separated terminals.

tasks:
- command: echo Terminal1
- command: echo Terminal2

They are started in parallel. See belows options on configuring where and how the terminals are placed in the workbench.

Defining Commands

The command property is used to specify the command that shall be run on every start of a workspace. It is a bash command and doesn't need to terminate. For instance, you could start a web server or a database.

The script below will start a development-time web server in many npm projects:

tasks:
  - command: npm run dev

init command

The init property can be used to specify shell commands that should only be executed after a workspace was freshly cloned and needs to be initialized somehow. Such tasks are usually builds or downloading dependencies. Anything you only want to do once but not when you restart a workspace or start a snapshot.

Here is an example for a node project that makes use of init:

tasks:
  - init: npm install
    command: npm run dev

This will make sure that npm install is executed only after the repository was cloned, but not when restarting the workspace or starting a snapshot of that workspace.

before command

In case you need to run something even before init, that is a requirement for both init and command, you can use the before property.

tasks:
  - before: setup.sh
    init: npm install
    command: npm run dev

Check the table below for an overview of the different starting scenarios.

Start Mode Execution
Fresh Workspace before && init && command
Restart Workspace before && command
Snapshot before && command

Configuring the Terminal

A task allows to configure where and how the terminal should open using the properties below. Please note that this information is used if no previous terminals in the layout exist. Snapshots will first try to reuse existing terminals in the layout, before opening new ones.

openIn

You can configure where in the IDE the terminal should be opened:

openIn Where
openIn:bottom the bottom panel (default)
openIn:left the left panel
openIn:right the right panel
openIn:main the main editor area

openMode

You can configure how the terminal should be opened relative to the previous task.

openMode Description
openMode:tab-after Opens in the same tab group right after the previous tab
openMode:tab-before Opens in the same tab group left before the previous tab
openMode:split-right Splits and adds the terminal to the right
openMode:split-left Splits and adds the terminal to the left
openMode:split-top Splits and adds the terminal to the top
openMode:split-bottom Splits and adds the terminal to the bottom

Working with Go

Go projects need a specific workspace layout: the source code of your repository and its dependencies must be in the directories

src/[repository-provider]/[repository-owner]/[repository-name]

in the $GOPATH. Using the .gitpod.yml file, you can bring about such a workspace layout. Here is how we do that for the example go-gin-app repository:

...
checkoutLocation: "src/github.com/demo-apps/go-gin-app"
workspaceLocation: "."
tasks:
  - command: >
      cd /workspace/src/github.com/demo-apps/go-gin-app &&
      go get -v ./... &&
      go build -o app &&
      ./app

In more detail:

  • By default, Gitpod clones the repository into the directory /workspace, which becomes the root directory for the workspace. With checkoutLocation and workspaceLocation you can change this behavior (the paths are taken relative to /workspace).
  • Gitpod preconfigures the $GOPATH environment variable to include the directory /workspace.
  • With go get -v ./... we retrieve the sources of the dependencies from GitHub.
  • To build the app, we run go build -o app.
  • Lastly, we start the application.

Theia – Gitpod's IDE

The IDE in Gitpod is based on the open-source project Theia. It is hosted and developed under the umbrella of the Eclipse Foundation, which ensures vendor neutrality and emphasizes diversity.

Overview

When you open Theia for the first time, a welcome screen is shown to quickly get you started. After closing it you will see the workbench shell. Depending on the context URL, different views might be opened.

Let us have a look at the primary elements of the workbench shell.

Views and Editors

A Theia workbench shell consists of any number of opened views and editors. Views and editors can be freely arranged by dragging and dropping them around.

Main Area and Panels

Within the main area, the drag-and-drop functionality allows for splitting freely as you will. Also widgets can be moved to the side or bottom panels.

Tips & Tricks

Command Palette

The command palette is at the core of a keyboard-centric interaction, and can be also useful for looking up available commands and key bindings. It is available through the following two keyboard shortcuts:

  • F1
  • Ctrl+Shift+P (⌘+Shift+P on macOS)

Command Palette Context

The command palette lists only those commands that are available in the current context. For example, the Go To Line... command shows in the palette only when a code editor is opened and has focus.

Color Themes

Gitpod opens in its dark theme. If you prefer a lighter experience, you can switch to the light theme. Simply use the command palette and select Change Color Theme.

Change Color Theme

Open File

To quickly open any file using the keyboard, press:

  • Ctrl+P (⌘+P on macOS).

It will let you search, find, and open any file by name.

Open File

Search in Workspace

To search for or to replace string occurrences in all files of your workspace, press:

  • Ctrl+Shift+F (⌘+Shift+F on macOS)

It opens the search view, which is described in more detail here.

Symbols and References

Most languages allow to name things and refer to them in other places, for example variables, functions, classes, modules etc. Gitpod supports the notion of symbols and references, and lets you navigate between them in both directions:

  • Open Symbol (Ctrl+Shift+O) finds a symbol by its name.
  • Find All References (Shift+F12) lists all references to the symbol at the current position in an inline editor.
  • Go to Definition (Ctrl+F12 or Ctrl/⌘+click) brings you to the definition of a symbol. Peek Definition (Alt+F12) does the same in an inline editor.
  • Rename Symbol (F2) renames the symbol and changes all references to it accordingly.

Format Document

To tidy up your code, many languages support Format Document (Alt+Shift+F). If you want to apply this to only a subsection of the current document, select the desired region and pick Format Selection from the editor's context menu.

Git Integration

Theia integrates closely with Git by offering convenient UIs on top of the command line git (which is available in the terminal as well).

Authoring Commits

The Git view is automatically added to the left panel. If you have accidentally closed it, you can reopen it from the View > Git menu or with the Ctrl+Shift+G (⌘+Shift+G on macOS) key binding.

The Git view consists of three major sections. The top section is for authoring the commit messages. It also provides access to a couple of basic Git commands.

Right below is the commit section, which lists the changed files by their name and separates them in two groups: the STAGED CHANGES and CHANGED. The latter shows all unstaged changes.

At the bottom of the Git view, a small section gives a quick insight into the most recent commit.

In the list of staged and unstaged changes, the file names are followed by the path to their parent directory and an indicator describing the type of the change. This can be:

  • A: Added (new staged),
  • U: new Unstaged,
  • R: Renamed,
  • C: Copied (blue), Conflicted (red),
  • M: Modified, and
  • D: Deleted.

An unstaged change can be reverted by clicking on the Discard Changes action next to the file location. Double-clicking on a modified file will open it in a diff editor. The read-only editor on the left-hand side shows the state from the index. The right-hand side of the editor reflects the state of the working tree, and it lets you to further modify the file. New and deleted files do not open in a diff editor. Files can be staged (added to the index) by clicking on the Stage Changes action (+ sign). To unstage changes, use Unstage Changes action (- sign).

After staging the desired files and specifying the commit message, the changes can be committed to the repository. After a successful commit, the Last Commit section is automatically updated.

Git Status Bar

In the bottom left corner of Theia you can find indicators describing the status of your Git repository. It shows the current branch, dirty indicators, and the number of ahead and behind changes of the current branch.

The dirty indicators are as follows:

  • *: You have unstaged changes in your branch.
  • +: You have staged changes in your branch, but no unstaged.
  • !: You have conflicting changes in your branch.

By clicking on the branch name, you can perform a git checkout. This operation is equivalent to the Git: Checkout command from the command palette.

There is a Synchronize Changes action as well in the status bar, next to the branch indicator, if the currently checked-out branch has an upstream branch configured. Synchronize Changes will pull remote changes to your local repository and then push local commits to the upstream branch.

Branches and Tags

You can create and check out branches directly within Theia through the Git: Checkout command in the command palette. For creating a new branch, select the first item from the list, Create new branch..., and specify the desired name of your branch. Theia creates the new branch for you and checks it out.

Gutter Indicators

If you open a file that is under version control by Git and start applying changes, Theia will add annotations to the gutter and to the overview ruler of the editor:

  • A red triangle indicates where lines have been deleted.
  • A green bar shows the newly added lines.
  • A blue bar indicates modified lines.

Blame Annotations

You can show the blame annotation by either selecting the Show Blame Annotations from the editor's context menu or by picking Git: Show Blame Annotations from the command palette. This will show the blame annotations on the left hand-side of the editor. Press Esc if you want to hide the blame annotations.

Merge Conflicts

Theia recognizes merge conflicts. Theia highlights the differences and provides inline action to accept either the local or the incoming change. Alternatively, both modifications can be accepted at the same time. Once you have resolved the conflicts, stage your changes and commit them.

Viewing Diffs

The Git extension supports diffing within Theia. Selecting any of the modified files will open a diff viewer. Its left-hand side is a read-only editor showing the index state, and the right-hand side is an editor for the working-tree state.

Git History

Theia provides various ways to review the Git history.

  • The history of an individual file can be checked, or
  • The history of multiple files within a directory can be reviewed at once.

You can activate the Git History view by right-clicking on the file in the Files navigator and selecting the Git History context menu item. Alternatively, you can open the history view from the View > Git History menu or toggle the view with the Alt+H command. The content of the Git History view does not update when changing the active editor or when altering the selection in the Files view. To get the history of an individual resource you have to either use the Git History command from the command palette or from the Files navigator's context menu.

The top of the Git History view shows the path of the resource or resources. Right below the path, you can see the list of commits with some details such as the committer, the subject of the commit message, and the relative time of the commit. You can open up the commit in a read-only editor to review all the details about the commit.

Search

There are several ways to perform a search and to find things in the workspace:

Search in Workspace

The Search in Workspace command will bring up the Search view. Run it either through the command palette or by pressing Ctrl+Shift+F (⌘+Shift+F on macOS).

In the Search view, you can start typing, and the matching results will be shown automatically without pressing Enter. The search can be restricted to case matching, whole word matching, or the query can be given as a regular expression. Search results are grouped by file, with an indication of the number of occurrences and the file's path. Expand a file to see a preview of all of the hits within that file. Then single-click on one of the hits to view it in the editor.

Advanced Search Options

In the input box below the search box, you can enter patterns to include or exclude from the search. If you enter theName, it will match every directory and file named theName in the workspace. If you enter ./theName, it will match the directory theName/ at the top level of your workspace. Use ! to exclude those patterns from the search. !theName will skip searching any directory or file named theName. You can also use globbing syntax:

  • * to match one or more characters in a path segment,
  • ? to match on one character in a path segment,
  • ** to match any number of path segments, including none,
  • {} to group conditions (e.g., {**/*.html,**/*.txt} matches all HTML and text files), and
  • [] to declare a range of characters to match (e.g., theName.[0-9] to match on theName.0, theName.1, …).

Theia excludes some directories by default (for instance, node_modules and others that are ignored through .gitignore) to reduce the number of search results. If you would like to search for all files in the workspace, click on the Include Ignored Files in the search field.

Search and Replace

You can also Search and Replace across files. Expand the Search widget to display the Replace text box.

When you type text into the Replace text box, you will see a diff display of the pending changes. You can replace across all files from the Replace text box, replace all in one file, or replace a single change. Double-clicking on any of the Search and Replace occurrences, opens the file in a diff editor so that you can review the modification in the editor before eventually applying them.

Open File

Use Ctrl+P (⌘+P on macOS) to search files in the workspace by name. By default, hidden and ignored files do not show up among the results.

If you want to include all files in this search, press Ctrl+P once again.

Selecting a file will open it an an editor.

Open Workspace Symbol

Press Ctrl+O (⌘+O on macOS) to find symbols in the workspace. Note: what kinds of symbols are searchable is language-specific.

Navigator Search

When the Files navigator is in focus, start typing to highlight all those files whose names match your pattern. This search ignores all collapsed files in the navigator. When the navigator search is active and there are highlighted files, you can use the cursor arrows to jump the matching resources in the navigator. You can finish your search anytime by hitting Esc, or by deleting your pattern with Backspace.

Use this to quickly locate a file in the Files navigator.

Find and Replace in Editor

Press Ctrl+F (⌘+F on macOS) in the editor to open the Find/Replace search widget. It is recommended to use this search functionality if you want to find something in a given file. As always, alternatively, you can use the command palette (look for Find) or the Edit > Find menu item to open the search widget.

This functionality helps you finding all occurrences in a single file. Your query can match the whole word, can be case sensitive, or even a regular expression. It also provides a convenient way to replace all you search occurrences.

Pull Requests

Gitpod lets you follow the standard GitHub flow. It does not require any detours or additional steps.

In the GitHub flow, each programming task starts with a GitHub issue. In the issue you describe the task, defect, or feature, and log all discussions and related commits.

To start a Gitpod workspace for an issue, either prefix the issue's URL in the address bar with https://gitpod.io# or click on the Gitpod button that comes with the Gitpod browser extension. Gitpod will start your cloud workspace in a new browser tab.

In the status bar in the lower left corner, you can see that Gitpod created a local branch GH-{issue-number} (GH-5 in this example) for your issue. If you open the Git view, you will notice that the commit message has already been filled in as Fixes.... This causes GitHub to automatically close the issue once this commit is merged.

Additionally, Gitpod has encountered a .gitpod.yml file in the repository and runs its initialization task. In this example the initialization task builds and starts the app, so that it can be tested right away in the Preview view.

Now solve the issue by applying a few changes. In this example, you add one file and modify two existing ones. If you want to browse through all changes so far, go to the Files navigator view, choose Diff: Compare with..., and select the master branch in the quick open menu. The Diff view allows you to step through all the changes easily using the arrow keys.

Once you are done reviewing your changes, it is time to commit them. Go to the Git view and stage all changed files by clicking on the + icon that pops up when you hover over the entries. Once everything is staged, add a meaningful commit message and press the Commit button.

The next step in the GitHub flow is to propose your changes as a GitHub pull request. You can do that from within Gitpod. In the Pull Request view you will see a message that your current branch has no remote tracking branch. When you click on the Publish Changes button, Gitpod creates a remote branch on GitHub and synchronizes it with your local branch.

The Pull Request view allows you to change title and description of the PR in Markdown (the Preview tab shows the rendered version). You can also specify a different target branch to merge into. If you are satisfied with all these values, click the Create Pull Request button. The pull request is now pushed to GitHub.

The Pull Request view will now provide you with review facilities. You can view the PR on GitHub or synchronize with out-of-band changes, change the target branch, view the conversation, or start a review.

Now, leave a question to the reviewer. Open one of the modified files, hover over the gutter left of the line numbers where you want to add the comment, and then click on the comment icon. Enter your comment (once again in Markdown with Preview facilities) and click Add single comment.

Your comment should now appear in the Conversation view, and once it is synchronized with GitHub, in the Pull Request view as well.

It looks like you are done here, so stop the workspace and ask a colleague to do a review. Click on the avatar in the upper right corner and choose Stop Workspace. In the following dialog, choose Do It.

Code Reviews

Let us have a look how we can perform a code review on GitHub with Gitpod. We continue the example from the previous chapter, where we created a pull request (PR). In the role of a reviewer you open this PR on GitHub. Once again, Gitpod allows you to follow the GitHub flow.

Just like the creator of the PR, you can start a Gitpod workspace by prefixing the URL or using the Gitpod button provided by the Gitpod browser extension. Gitpod spawns a workspace and the IDE loads in the browser.

The initialization task in the repository's .gitpod.yml file builds and starts the app automatically such that you can test the changes right within Gitpod's Preview.

Gitpod has opened the Diff view and the first change in an editor. Using the arrow keys, you can easily browse through the changes and examine them in their context. Applying further changes is easy, as you have a full IDE at your fingertips. You can commit them to the PRs branch as described in the section on Git.

You can also add additional review comments. The Conversations view lists all existing review comments and allows to navigate to their locations in the code. Let us use it to answer the question from the creator of the PR.

By clicking Start a review, Gitpod creates a review on GitHub and adds our comment. All subsequent comments will be filed into this review. All reviews are listed in the Pull Request view. Out-of-band comments and reviews can be synchronized using the synchronize button.

The review can be finished by pushing the review button. You can add your final verdict and push it to GitHub.

If you have approved the PR, you can merge the changes by pushing the Merge button in the Pull Request view or conventionally on the GitHub website.

Dashboard

Gitpod's dashboard allows you to log in and out, navigate through all your workspaces, and view details of your account and subscription. It can be reached by pointing your browser to https://gitpod.io.

If you are not logged in, you will see a Log in button. Otherwise, the top-right corner will display your avatar's picture. Clicking it will reveal the User Menu.

Workspaces

By default, the dashboard shows you a list of your workspaces and their current state. The list is sorted by relevance (running workspaces first). It can be searched using the search field.

a workspace entry

Each entry provides information about the workspace's name, creation date, workspace context (repository, branch, commit ID, issue, or pull-request), execution state (e.g. Starting, Stopping, Last run).

Workspaces can be started, opened, or stopped using the respective buttons.

You can also enable/disable sharing of a workspace by clicking the lock icon. See the section on collaboration for details about sharing workspaces.

Archived Workspaces

You can archive a workspace if you do not want it to appear in the list.

If you try to open a workspace from an existing context, Gitpod will redirect you to the dashboard to let you choose whether to open a new workspace or reuse an existing one. Archived workspaces will not be taken into account.

Account Details

Account details can be accessed via the User Menu > Account details. This page allows you to add or remove accounts to code hosting platforms and manage your Gitpod subscription. It also gives you a tabular view on your Gitpod usage.

Log Out

You can log out of Gitpod using Log out from the User Menu. Note that your GitHub authentication token will be preserved for the next time you log in.

Subscriptions

In order to use Gitpod, a user has to have a valid subscription. If you are not aware of that, you are likely using the free subscription. See our homepage for possible subscription plans.

Our internal calculation unit is Gitpod hours. One Gitpod hour allows you to use one workspace for one hour on a default server. If you use multiple workspaces in parallel you will be charged for each of these individually, e.g. for running three workspaces in parallel for half an hour we will charge you 1.5 Gitpod hours. For non-default resources, we apply a factor that reflects the additional costs we have for the special hardware. The granularity is Gitpod seconds.

Depending on the type of subscription, you get a certain amount of Gitpod hours per subscription month. Subscription months, unlike calendar months, start directly with at the moment of the subscription. At the end of a subscription month, your remaining Gitpod hours for that months expire, and you will start with the subscription amount again.

You can upgrade to a higher subscription plan at any point in time. The new subscription month starts immediately. Downgrading is possible as well, but the new subscription month will start with the end of the prior subscription.

We may introduce other types of additional Gitpod hours (expiring or not) in the future. When you have different kinds of credits, the one with the earliest expiry date will be used first.

You can see your current amount of Gitpod hours in the dashboard or in the IDE (Help > Account Details). You will be warned multiple times when you are getting close to running out of Gitpod hours. As soon as your credits are used up, your workspaces will be closed automatically. You can still use the dashboard, but you will not be able to start any workspaces until you have Gitpod hours again.

Latest Release Notes

February Release 2019 🎉

We are close to leaving the beta phase and with that are also approaching a more regular release schedule. This means we are going to have monthly release notes. They will pop up only once and you can easily dismiss them by pressing [ESC]. If you want to look up the release notes later you can open them through the command palette [F1]. Simply search for 'Release Notes'.

So here are the new & noteworthy things that we have been hard at work at this time.

GitHub Links

You can now navigate to GitHub directly from the editor. The GitHub URL of any editor position or selection can be accessed with a right-click, and used for example in GitHub issues or Pull Request comments to reference interesting code locations.

GitHub Links

Snapshots

In addition to live sharing a running Gitpod workspace, you can now take a snapshot. Snapshots capture the current state of a workspace session including the UI layout and the file changes. Anyone who has a snapshot link can create a fresh workspace based on that.

This is super handy for providing reproducibles in GitHub issues and StackOverflow posts. They are also great to prepare trainigs, tutorials, or just to showcase stuff you have thrown together.

Please see this blog post as well as the documentation for more details.

Snapshot

Configuration

The possibilities to fine-tune the developer experience when using Gitpod on your repository have been improved. Here are the features you can define in your .gitpod.yml:

Tasks

You can now specify multiple tasks. Each task will have its own terminal view on start. You can even specify where those terminals whould be opened. The following config, for instance, will make sure that two terminals are opened next to each other.

tasks:
 - command: echo 'left'
 - command: echo 'right'
   openMode: split-right

Split Terminals

Lifecycles

In addition we have introduced multiple lifecycle phases for the tasks, such as init and before. The main purpose is to avoid reruning unnecessary commands such as full builds, when restarting workspaces or opening snapshots.

Check the table below for an overview of the different starting scenarios.

Start Mode Execution
Fresh Workspace before && init && command
Restart Workspace before && command
Snapshot before && command

Ports

You can now specify the default behavior on port detection. By default users get a notification when starting a server, asking whether they want to open a web view or an external browser.

This behavior can now be pre-configured so users are not bothered with annoying notifications. Here is an example where we configure port 8080 to automatically open in a web preview pane:

ports:
 - port: 8080
   onOpen: open-preview

Check out the docs to learn more about pre-configuring things in Gitpod.

YAML Support

Gitpod now understands YAML syntax and uses json schema specifications to validate and guide developers. While this works for any YAML files it comes in especially handy when editing .gitpod.yml.

yaml in action

Gitpod CLI

The CLI for Gitpod has learned new tricks. Check out all the cool things you can do with it by typing gp help.

Here are the new commands we added:

gp init

To get the best experience with Gitpod, you should configure your repository to have the right tools, run the right commands on start, etc. This information is stored in a .gitpod.yml file sitting in your repository.

The gp init command walks you through the basic setup and generates a .gitpod.yml and if desired a corresponding Dockerfile.

gitpod /workspace/my-repo $ gp init
Use the arrow keys to navigate: ↓ ↑ → ←
? Workspace Docker image:
  ▸ default
    custom image
    docker file

More information about writing .gitpod.yml configurations can be found in the docs.

gp url

One of the things you do in a .gitpod.yml is declaring the exposed ports. Gitpod maps them to a specific subdomain in order to make them accessible. For instance if you have a dev server running on 0.0.0.0:3000 the gp url command gives you the external url for that service.

Here is an example:

gitpod /workspace/release-notes $ gp url 3000
https://3000-b33f605e-b32a-4e44-ae5a-acad9641de0a.ws-eu0.gitpod.io/

gp url can also give you the URL of the workspace itself:

gitpod /workspace/release-notes $ gp url
https://b33f605e-b32a-4e44-ae5a-acad9641de0a.ws-eu0.gitpod.io/

gp preview

gp preview is similar to gp open, except that it does not open a file in the editor but a URL in a preview pane on the right.

This is especially handy together with gp url if you want to open a specific path from a script.

Here's an example:

gp preview $(gp url 3000)my/special/path.html

Improved Docker Performance

In addition to the .gitpod.yml you can provide a Dockerfile which is automatically picked up by Gitpod. See this blog post for more information on setting up a Dockerfile for your project.

For example, here is a Dockerfile that allows developing native UI applications in Go on Gitpod:

FROM gitpod/workspace-full-vnc
RUN apt-get update \
    && apt-get install -y libgtk-3-dev

Since we launched this feature, the performance and logging for docker builds have also been improved significantly.

Status Page

As we continuously improve and expand Gitpod, there are times when things inevitably don't go as planned, occasionally causing downtime. If you're ever curious about the status of gitpod.io, or you'd like to follow how we resolve an incident, we made status.gitpod.io just for you.

In fact, thanks to Statusfy, it took us just a few hours to build an entire open source status page. Learn more about this short adventure in this blog post.

Java Debugging

In addition to Node.js one can now also launch and debug Java applications directly from within the editor. Code lense actions on main() methods will automatically use the right classpath from the current project settings (based on maven, gradle or eclipse classpath information).

Launch configs are stored in a VS Code compatible launch.json file.

Debug Java

XML Support

The new improved XML support not only does syntax highlighting for XML and XSD but also uses associated schemas to provide diagnostics, content assist and hover information.

XML Support

Better Previews

Previews can now easily be opened by clicking on the top right icon (icon) on any previewable files, such as Markdown, HTML and SVG files.

The inverse is supported, too. I.e. clicking the file icon on the top right of a preview will open the corresponding editor on the left. For Markdown even scrolling is synced between the two views.

AsciiDoc Support

In addition to Markdown, Gitpod now also supports previewing AsciiDoc as you type.

asciidoc

Many Bugfixes, small features and other improvements

These are just the most noteworthy features we have been working on. For a more detailed list of bugfixes and enhancemenst see all the issues we've closed: