Skip to main content

Creating a codespace for a repository

You can create a codespace for a branch in a repository to develop online.

About creating a codespace for a repository

可以在 GitHub.com 上、Visual Studio Code 中或使用 GitHub CLI 创建代码空间。 Use the tabs in this article to display instructions for each of these ways of creating a codespace.

如果要启动新项目,建议通过模板创建 codespace 并稍后将其发布到 GitHub 上的存储库。 For more information, see "Creating a codespace from a template."

Note: If you use a JetBrains IDE, you can use GitHub CLI to create a codespace. You can then use the JetBrains Gateway application to open the codespace in a JetBrains IDE. For more information, see "Using Codespaces in your JetBrains IDE."

You can use GitHub Codespaces on your personal GitHub.com account, with the quota of free use included each month for accounts on the Free and Pro plans. 通过提供付款详细信息和设置支出限制,可以在超出每月包含的存储空间和计算使用量后继续使用 GitHub Codespaces。 有关详细信息,请参阅“关于 GitHub Codespaces 的计费”。

Organizations can enable members and outside collaborators to create and use codespaces at the organization's expense. For more information, see "Enabling GitHub Codespaces for your organization."

您创建的每个代码空间只有您才可以使用。 其他任何人都不能在您的代码空间中工作。

If you create a codespace from a repository, the codespace will be associated with a specific branch, which cannot be empty. You can create more than one codespace per repository or even per branch.

可以在 github.com/codespaces 上查看你创建的每个可用代码空间。

The codespace creation process

When you create a codespace, a number of steps happen to create and connect you to your development environment:

  • Step 1: VM and storage are assigned to your codespace.
  • Step 2: Container is created and your repository is cloned.
  • Step 3: You can connect to the codespace.
  • Step 4: Codespace continues with post-creation setup.

For more information on what happens when you create a codespace, see "Deep Dive."

For more information on the lifecycle of a codespace, see "The codespace lifecycle."

If you want to use Git hooks for your codespace, then you should set up hooks using the devcontainer.json lifecycle scripts, such as postCreateCommand, during step 4. Since your codespace container is created after the repository is cloned, any git template directory configured in the container image will not apply to your codespace. Hooks must instead be installed after the codespace is created. For more information on using postCreateCommand, see the devcontainer.json reference in the VS Code documentation.

使用 VS Code 在 codespace 中开发时,你可以编辑代码、调试和使用 Git 命令。 有关详细信息,请参阅 VS Code 文档

To speed up codespace creation, repository administrators can enable GitHub Codespaces prebuilds for a repository. For more information, see "About GitHub Codespaces prebuilds."

Creating a codespace for a repository

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under the repository name, use the "Branch" dropdown menu, and select the branch you want to create a codespace for.

    Branch dropdown menu

  3. Click the Code button, then click the Codespaces tab.

    New codespace button

    If codespaces for this repository are billable to an organization, or its parent enterprise, a message is displayed below the Create codespace on BRANCH button telling you who will pay for the codespace.

  4. Create your codespace, either using the default options, or after configuring advanced options:

    • Use the default options

      To create a codespace using the default options, click the plus sign (). Alternatively, if you don't currently have any codespaces for this repository, you can click Create codespace on BRANCH.

    • Configure options

      To configure advanced options for your codespace, such as a different machine type or a particular devcontainer.json file:

      1. Click the ellipsis (...) at the top right of the Codespaces tab and select New with options.

        View the default machine type

      2. On the options page for your codespace, choose your preferred options from the dropdown menus.

        The codespace options page

        Notes

      3. Click Create codespace.

将 GitHub.com 上的帐户连接到 GitHub Codespaces 扩展后,可以创建新的 codespace。 有关 GitHub Codespaces 扩展的详细信息,请参阅 VS Code Marketplace

  1. 在 VS Code 中,从左侧边栏单击“远程 Explorer”图标。

    Visual Studio Code 中的 Remote Explorer 图标

    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: codespaces.
    3. Click Codespaces: Details.
  2. 单击“添加”图标:

    GitHub Codespaces 中的“新建 Codespace”选项

  3. 键入要在其中开发的存储库的名称,然后将其选中。

    搜索要在其中新建 codespace 的存储库

    如果你选择的存储库归组织所有,并且该组织已将此存储库的 codespace 配置为可向组织或其父企业计费,则后续提示中会显示一条消息,告知谁将支付 codespace 费用。

  4. 单击要在其中开发的分支。

    搜索要在其中新建 codespace 的分支

  5. 如果系统提示选择开发容器配置文件,请从列表中选择一个文件。

    为 GitHub Codespaces 选择一个开发容器配置文件

  6. 选择你要使用的机器类型。

    新 codespace 的实例类型

    注意:你选择的可用计算机类型可能会受到多种因素的限制。 其中可能包括为组织配置的策略,或者存储库的计算机类型最低规范。 有关详细信息,请参阅“限制对计算机类型的访问”和“为代码空间计算机设置最低规范”。

若要详细了解 GitHub CLI,请参阅“关于 GitHub CLI”。

To create a new codespace, use the gh codespace create subcommand.

gh codespace create 

You are prompted to choose a repository. If codespaces for this repository are billable to an organization, or its parent enterprise, a message is displayed telling you who will pay for the codespace. You are then prompted to choose a branch, a dev container configuration file (if more than one is available), and a machine type (if more than one is available).

Alternatively, you can use flags to specify some or all of the options:

gh codespace create -r OWNER/REPO -b BRANCH --devcontainer-path PATH -m MACHINE-TYPE

In this example, replace owner/repo with the repository identifier. Replace branch with the name of the branch, or the full SHA hash of the commit, that you want to be initially checked out in the codespace. If you use the -r flag without the b flag, the codespace is created from the default branch.

Replace path with the path to the dev container configuration file you want to use for the new codespace. If you omit this flag and more than one dev container file is available you will be prompted to choose one from a list. For more information about the dev container configuration file, see "Introduction to dev containers."

Replace machine-type with a valid identifier for an available machine type. Identifiers are strings such as: basicLinux32gb and standardLinux32gb. The type of machines that are available depends on the repository, your personal account, and your location. If you enter an invalid or unavailable machine type, the available types are shown in the error message. If you omit this flag and more than one machine type is available you will be prompted to choose one from a list.

For full details of the options for this command, see the GitHub CLI manual.

Further reading