Using GitHub Codespaces in Visual Studio Code

You can develop in your codespace directly in Visual Studio Code by connecting the GitHub Codespaces extension with your GitHub account.

In this article

About GitHub Codespaces in Visual Studio Code

You can use your local install of Visual Studio Code to create, manage, work in, and delete codespaces. To use GitHub Codespaces in VS Code, you need to install the Codespaces extension. For more information on setting up GitHub Codespaces in VS Code, see Prerequisites.

By default, if you create a new codespace on GitHub, it will open in the browser. If you would prefer to open any new codespaces in VS Code automatically, you can set your default editor to be VS Code. For more information, see Setting your default editor for GitHub Codespaces.

If you prefer to work in the browser, but want to continue using your existing VS Code extensions, themes, and shortcuts, you can turn on Settings Sync. For more information, see Personalizing GitHub Codespaces for your account.

Prerequisites

To develop in a codespace directly in VS Code, you must install and sign into the GitHub Codespaces extension with your GitHub credentials. The GitHub Codespaces extension requires VS Code October 2020 Release 1.51 or later.

Use the Visual Studio Code Marketplace to install the GitHub Codespaces extension. For more information, see Extension Marketplace in the VS Code documentation.

  1. In VS Code, in the Activity Bar, click the Remote Explorer icon.

    Screenshot of the Activity Bar. The icon for the "Remote Explorer" side bar (a rectangle overlaid by a circle) is highlighted with an orange outline.

    Note

    If the Remote Explorer is not displayed in the Activity Bar:

    1. Access the Command Palette. For example, by pressing Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux).
    2. Type: details.
    3. Click Codespaces: Details.

  2. Select "GitHub Codespaces" from the dropdown at the top of the "Remote Explorer" side bar, if it is not already selected.

  3. Click Sign in to GitHub.

    Screenshot of the "Remote Explorer" side bar for "GitHub Codespaces" with the "Sign in to GitHub" button displayed.

  4. If you are not currently signed in to GitHub you'll be prompted to do so. Go ahead and sign in.

  5. When you're prompted to specify what you want to authorize, click the Authorize button for "GitHub."

  6. If the authorization page is displayed, click Authorize Visual-Studio-Code.

Connecting to an enterprise on GHE.com

If you access GitHub through a subdomain of GHE.com, you must configure the Github-enterprise: Uri and Github > Codespaces: Auth Provider settings in VS Code before you can connect to your codespaces.

  1. To open your VS Code settings, press Command+, (Mac) or Ctrl+, (Windows).

  2. In the search bar, search for enterprise.

  3. For the Github-enterprise: Uri setting, enter the URL where you access GitHub. For example: https://octocorp.ghe.com.

    Alternatively, you can add the following to your settings.json file:

    JSON
    "github-enterprise.uri": "https://SUBDOMAIN.ghe.com"

  4. In the VS Code settings, search for Codespaces Auth Provider.

  5. For the Github > Codespaces: Auth Provider setting, select github-enterprise from the dropdown.

    Alternatively, you can add the following to your settings.json file:

    JSON
    "github.codespaces.authProvider": "github-enterprise"

  6. You will be shown a prompt asking you to sign in. Click Sign in to GitHub, then follow the prompts to authorize your account.

    If you don't see the prompt, try restarting VS Code.

If you ever need to switch back to an account on GitHub.com, set the Github > Codespaces: Auth Provider setting back to its default value and remove the Github-enterprise: Uri setting.

Creating a codespace in VS Code

After you connect your account on GitHub to the GitHub Codespaces extension, you can create a new codespace. For more information about the GitHub Codespaces extension, see the VS Code Marketplace.

  1. In VS Code, in the Activity Bar, click the Remote Explorer icon.

    Screenshot of the Activity Bar. The icon for the "Remote Explorer" side bar (a rectangle overlaid by a circle) is highlighted with an orange outline.

    Note

    If the Remote Explorer is not displayed in the Activity Bar:

    1. Access the Command Palette. For example, by pressing Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux).
    2. Type: details.
    3. Click Codespaces: Details.

  2. Hover over the "Remote Explorer" side bar and click .

    Screenshot of the "Remote Explorer" side bar for GitHub Codespaces. The tooltip "Create New Codespace" is displayed beside the plus sign button.

  3. In the text box, type the name of the repository you want to develop in, then select it.

    Screenshot of "octo-org/he" entered into the text box and a list of four repositories that start with this string.

    A message is displayed at the right side of subsequent prompts telling you who will pay for the codespace.

    Screenshot of a prompt for a branch, with the message "Usage paid for by hubwriter."

  4. Click the branch you want to develop on.