Skip to main content

Creating a codespace

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

GitHub Codespaces 可用于使用 GitHub Team 或 GitHub Enterprise Cloud 的组织。 GitHub Codespaces 也可作为受限的 beta 版本提供给使用 GitHub Free 和 GitHub Pro 计划的个人用户。 有关详细信息,请参阅“GitHub 的产品”。

About codespace creation

You can create a codespace on GitHub.com, in Visual Studio Code, or by using GitHub CLI. 您创建的每个代码空间只有您才可以使用。 其他任何人都不能在您的代码空间中工作。

Codespaces are associated with a specific branch of a repository and the repository cannot be empty. You can create more than one codespace per repository or even per branch.

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 "Codespaces 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 文档

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

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

Access to GitHub Codespaces

When you have access to GitHub Codespaces, you'll see a "Codespaces" tab within the Code drop-down menu when you view a repository.

You'll have access to GitHub Codespaces under the following conditions:

Either all of these are true:

  • You are a member, or outside collaborator, of an organization that has enabled Codespaces and set a spending limit.
  • The organization owner has allowed you to create codespaces at the organization's expense.
  • The repository for which you want to create a codespace is owned by this organization.

Or both of these are true:

  • You are participating in the beta of Codespaces for individual users.
  • Either you own the repository for which you want to create a codespace, or it is owned by an organization of which you are either a member or an outside collaborator.

Before Codespaces can be used in an organization, an owner or billing manager must have set a spending limit. For more information, see "Managing spending limits for GitHub Codespaces."

Organization owners can specify who can create and use codespaces at the organization's expense. Organization owners can also prevent any codespace usage being charged to the organization. For more information, see "Enabling GitHub Codespaces for your organization."

Creating a codespace

  1. 在 GitHub.com 上,导航到存储库的主页。

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

    Branch drop-down menu

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

    New codespace button

    If codespaces for this repository are billable, 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 Create codespace on BRANCH.

      Optionally, before clicking Create codespace on BRANCH, you can click the down arrow at the side of the button to see what machine type will be used for your codespace.

      View the default machine type

      Note: The machine type with the lowest resources that are valid for the repository is selected by default.

    • Configure options

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

      1. Click the down arrow at the side of the Create codespace on BRANCH button, then click Configure and create codespace.

      2. Click the Configure and create codespace button.

      3. On the options page for your codespace, choose your preferred options from the drop-down menus.

        The codespace options page

        Notes

      4. Click Start session.

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

Note: Currently, VS Code doesn't allow you to choose a dev container configuration when you create a codespace. If you want to choose a specific dev container configuration, use the GitHub web interface to create your codespace. For more information, click the Web browser tab at the top of this page.

  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. Click the Add icon: .

    The Create new Codespace option in GitHub Codespaces

  3. Type the name of the repository you want to develop in, then select it.

    Searching for repository to create a new codespace

    If codespaces are billable for the repository you choose, a message will be displayed in subsequent prompts telling you who will pay for the codespace.

  4. Click the branch you want to develop on.

    Searching for a branch to create a new codespace

  5. If prompted to choose a dev container configuration file, choose a file from the list.

    Choosing a dev container configuration file for GitHub Codespaces

  6. Click the machine type you want to use.

    Instance types for a new codespace

    Note: 可供选择的计算机类型可能会受为组织配置的策略或存储库的计算机类型最低规范的限制。 有关详细信息,请参阅“限制对计算机类型的访问”和“为代码空间计算机设置最低规范”。

若要详细了解 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, 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