VS Code

Gitpod Flex 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.

Prerequisites

Before starting, ensure that you have the following:

1. VS Code installed.
2. The Gitpod Flex extension for VS Code installed and enabled.
3. The Remote - SSH and Dev Containers extensions installed and enabled in VS Code.

Tip: Keep your VS Code and extensions updated for the best experience.

Opening an Environment

1. Open Gitpod Flex

2. Start an environment

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

     

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

     

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

   

Install and Sign In

1. Install the Gitpod Flex Extension

After opening, VS Code will prompt you to install the Gitpod Flex extension if it’s not already installed.

• Click Allow when prompted.

  

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 and Dev Containers extensions to function. If these are not already installed, VS Code will notify you to add them.

• Click Install to add these dependencies.

  

3. Authenticate with Gitpod Flex

VS Code will then ask you to authenticate with your Gitpod Flex account:

1. Click Open when prompted to navigate to the Gitpod Flex authentication page.
2. Follow the authentication process to complete the sign-in.
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

While connecting to a new environment, VS Code might prompt you to trust the workspace. Click Trust Folder & Continue only if you are confident about the security of the project.

Tip: To learn more, see the VS Code Workspace Trust documentation.

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 Flex: Show Environment Details command from the Command Palette.

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

Accessing Commands

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

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

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 Flex: Rebuild Container

2. Rebuild Prompt: VS Code detects changes and prompts

   

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.

Troubleshooting

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.
2. Pay close attention to the error messages in the details view.
3. Inspect the logs as necessary to understand the root cause of the failure.
4. Make the required changes to the .devcontainer.json file to address the issue.
5. Trigger a rebuild using the Gitpod Flex: Rebuild Container command.

Important: The recovery mode is not stable for development. Always aim to fix the configuration and successfully rebuild the container.

Opening Issues

There are cases where the Dev Container is running, but the Dev Containers extension cannot open it. This can happen, for instance, due to reasons such as:

• Invalid remote user
• Failed initializeCommand which is re-executed on each window opening

In such cases, you may encounter the following modal:

If you select Edit Configuration in SSH, you will again end up in recovery mode, similar to the failed rebuild case. The same caution should be applied: avoid using recovery mode for development.

To recover from this situation:

1. Make necessary adjustments to the .devcontainer.json file to address the openning issue.
2. Use the Gitpod Flex: Reopen in Container command. This will reuse the same container but attempt to reopen the connection.
3. If you made changes that you believe require a rebuild, use the Gitpod Flex: Rebuild Container command again.

Authentication Issues

If you’re experiencing authentication issues or need to switch accounts:

1. Use the Gitpod Flex: 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.

General Issues

If you encounter unexpected problems:

1. Check the Gitpod Flex 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 the Gitpod Flex: 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 Flex 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 Flex: 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.