Gitpod seamlessly integrates with VS Code, allowing you to connect to your environments. This guide will walk you through the setup process and provide tips for managing, troubleshooting, and recovering environments within VS Code.

VS Code

​
Prerequisites

Before starting, ensure that you have the following:
  1. VS Code installed.
  2. The Gitpod extension for VS Code installed and enabled.
  3. The Remote - SSH extension installed and enabled in VS Code.
Tip: Keep your VS Code and extensions updated for the best experience.

​
Opening an Environment

​
VS Code

  1. Start an environment in Gitpod
  2. Open in VS Code
    • While the environment is starting, you can click the Open in VS Code button on the action bar. This button is available at any stage—even when the environment is not fully running yet.

      Open from the Action Bar

    • Alternatively, use the VS Code icon from the sidebar to launch the environment.

      Open from the Side Bar

  3. VS Code should open or you should see a dialog asking you to open. See Prerequisites if you cannot open VS Code.

    VS Code Open Dialog

​
VS Code Insiders

You can select VS Code Insiders from the editor selector dropdown by clicking on the dropdown arrow next to the editor button on the action bar.

VS Code Insiders

​
Install and Sign In

​
1. Install the Gitpod Extension

After opening, VS Code will prompt you to install the Gitpod extension if it’s not already installed.
  • Click Allow when prompted.

    Extension Installation Prompt

Note: The extension will make changes to your local SSH configuration to enable a smooth experience. This allows for seamless connectivity between VS Code and your environments.

​
2. Install Remote Development Extensions

The integration requires both the Remote - SSH extension to function. If this is not already installed, VS Code will notify you to add it.
  • Click Install to add this dependency.

    Install Prompt for Remote Development Extensions

​
3. Authenticate with Gitpod

VS Code will then ask you to authenticate with your Gitpod account:
  1. Click Open when prompted to navigate to the Gitpod authentication page.

    Authentication Prompt

  2. Follow the authentication process to complete the sign-in.

    Complete Authentication Page

  3. After signing in, you will be redirected back to VS Code and the page can be closed.
Note: If you encounter any issues during the sign-in process, it may be helpful to sign out and try again.

​
Workspace Trust

When connecting to a new environment, VS Code may prompt you to trust the workspace. This is a standard security measure for potentially untrusted code. For more information, refer to the VS Code documentation. Gitpod environments always run in isolated VMs, ensuring that code doesn’t access secrets outside the environment. The environment remains secure regardless of how you access it. If you’re familiar with the repository, you can safely click Trust Folder & Continue.

Workspace Trust Prompt

​
Managing Your Environment

Once connected, you can manage your environment directly from VS Code:

​
Viewing Environment Details

  • Check the status, active branch, and logs using the Environment Details panel.
  • If you closed the panel, re-open it using the Gitpod: Show Environment Details command from the Command Palette.

Environment Details in VS Code

Note: Clicking on details while opening the environment will also open the Environment Details panel.

Environment Details from Notification

​
Accessing Commands

  • Open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P) and type Gitpod to view commands such as:

    Gitpod Commands

  • Clicking on the remote indicator in the bottom-left corner of the remote window also shows a quick menu of Gitpod commands.

    Remote Indicator

​
Rebuild

Rebuilding is necessary to apply changes made to .devcontainer.json, Dockerfile, or docker-compose.yml files to the container. This process ensures that your development environment reflects the latest configuration updates. To rebuild the container, you have two options:
  1. Command Palette: Use Gitpod: Rebuild Container
  2. Rebuild Prompt: VS Code detects changes and prompts

    Rebuild Prompt

While the container is rebuilding, you will be disconnected and automatically reconnected when it’s finished. You can inspect the details view to learn about the progress and inspect logs.

Rebuild Logs

​
Troubleshooting

​
Limitations

Currently there are a couple limitations related to the devcontainer specification:
  • Port forwarding does not work for hosts other than localhost. For instance, forwarding ports from other services specified in a docker-compose.yml .
    • ✅ Workaround: Use network_mode: host in your docker-compose.yml for the services you want to port forward.
  • remoteEnv environment variables values are not applied unless the devcontainer is rebuilt.

​
Build Issues

If the initial build or a rebuild fails, you will enter recovery mode. When a build failure occurs:
  1. A modal will appear notifying you of the failure.

    Rebuild Failure

  2. Pay close attention to the error messages in the details view.

    Rebuild Failure Details

  3. Inspect the logs as necessary to understand the root cause of the failure.

    Rebuild Failure Logs

  4. Make the required changes to the .devcontainer.json file to address the issue.
  5. Trigger a rebuild using the Gitpod: Rebuild Container command.
Important: The recovery mode is not stable for development. Always aim to fix the configuration and successfully rebuild the container.

​
Authentication Issues

If you’re experiencing authentication issues or need to switch accounts:
  1. Use the Gitpod: Sign Out command to sign out.
  2. Confirm the sign-out when prompted.
  3. You can then sign in again with the same or a different account.

​
Connection Issues After Dev Container Rebuild

If you are unable to reliably connect to an environment after rebuilding a Dev Container in macOS:
  1. Allow VS Code’s “Code Helper.app” program in your local machine’s firewall.
  2. After updating firewall settings, restart VS Code, rebuild the Dev Container, and it should reconnect successfully.

​
General Issues

If you encounter unexpected problems:
  1. Check the Gitpod output view for any useful information.
  2. Check your network settings, sometimes the VPN or firewall settings can interfere with the connection.
  3. When sharing reports with us:
    • Use Developer: Set Log Level... command to Trace, it would give us more insights. Remember to set it back to Info afterwards.
    • In your VS Code settings, set remote.SSH.logLevel to trace.
    • Use the Gitpod: Export all logs command from the problematic window. This will contain all relevant logs.
Note: Be cautious when sharing logs on the internet, as they may contain sensitive information.

​
Uninstalling

When uninstalling the Gitpod extension, simply removing the extension from VS Code is not sufficient for a complete uninstall. Using the Uninstall Extension command ensures that all associated configurations, including SSH settings, are properly cleaned up.
  1. Use the Gitpod: Uninstall Extension command to initiate the uninstallation process.
  2. Follow the prompts to complete the uninstallation process.
If you’ve already uninstalled the extension without using the command, you can install it again and then use the uninstall command.