Skip to main content

About GitHub Codespaces prebuilds

GitHub Codespaces prebuilds help to speed up the creation of new codespaces for large or complex repositories.

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


Prebuilding your codespaces allows you to be more productive and access your codespace faster, particularly if your repository is large or complex and new codespaces currently take more than 2 minutes to start. This is because any source code, editor extensions, project dependencies, commands, and configurations have already been downloaded, installed, and applied before you create a codespace for your project. Think of a prebuild as a "ready-to-go" template for a codespace.

By default, whenever you push changes to your repository, GitHub Codespaces uses GitHub Actions to automatically update your prebuilds.

When prebuilds are available for a particular branch of a repository, a particular dev container configuration file, and for your region, you'll see the " Prebuild ready" label in the list of machine type options when you create a codespace. If a prebuild is still being created, you will see the " Prebuild in progress" label. For more information, see "Creating a codespace."

The dialog box for choosing a machine type

The prebuild process

To create a prebuild you set up a prebuild configuration. When you save the configuration, a GitHub Actions workflow runs to create each of the required prebuilds; one workflow per prebuild. Workflows also run whenever the prebuilds for your configuration need to be updated. This can happen at scheduled intervals, on pushes to a prebuild-enabled repository, or when you change the dev container configuration. For more information, see "Configuring prebuilds."

When a prebuild configuration workflow runs, GitHub creates a temporary codespace, performing setup operations up to and including any onCreateCommand and updateContentCommand commands in the devcontainer.json file. No postCreateCommand commands are run during the creation of a prebuild. For more information about these commands, see the devcontainer.json reference in the VS Code documentation. A snapshot of the generated container is then taken and stored.

When you create a codespace from a prebuild, GitHub downloads the existing container snapshot from storage and deploys it on a fresh virtual machine, completing the remaining commands specified in the dev container configuration. Since many operations have already been performed, such as cloning the repository, creating a codespace from a prebuild can be substantially quicker than creating one without a prebuild. This is true where the repository is large and/or onCreateCommand commands take a long time to run.

About billing for Codespaces prebuilds

默认情况下,每次创建或更新预生成或推送到启用预生成的分支时,都会触发 GitHub Actions 工作流。 与其他工作流一样,虽然预生成工作流正在运行,但它们会消耗帐户中包含的一些 Actions 分钟数(如果有),或者它们会产生 Actions 分钟费用。 有关 Actions 分钟定价的详细信息,请参阅“关于 GitHub Actions 的计费”。

除了 GitHub Actions 分钟数,还将针对与给定存储库和区域的每个预生成配置关联的预生成的存储计费。 预生成的存储按与 codespace 存储相同的费率计费。 For details of GitHub Codespaces storage pricing, see "About billing for GitHub Codespaces."

To reduce consumption of Actions minutes, you can set a prebuild to be updated only when you make a change to your dev container configuration files, or only on a custom schedule. You can also manage your storage usage by adjusting the number of template versions to be retained for your prebuild configurations. For more information, see "Configuring prebuilds."

If you are an organization owner, you can track usage of prebuild workflows and storage by downloading a GitHub Actions usage report for your organization. You can identify workflow runs for prebuilds by filtering the CSV output to only include the workflow called "Create GitHub Codespaces Prebuilds." For more information, see "Viewing your GitHub Actions usage."

Use of codespaces created using prebuilds is charged at the same rate as regular codespaces.

About pushing changes to prebuild-enabled branches

By default, each push to a branch that has a prebuild configuration results in a GitHub-managed Actions workflow run to update the prebuild. The prebuild workflow has a concurrency limit of one workflow run at a time for a given prebuild configuration, unless changes were made that affect the dev container configuration for the associated repository. For more information, see "Introduction to dev containers." If a run is already in progress, the workflow run that was queued most recently queued will run next, after the current run completes.

With the prebuild set to be updated on each push, it means that if there are very frequent pushes to your repository, prebuild updates will occur at least as often as it takes to run the prebuild workflow. That is, if your workflow run typically takes one hour to complete, prebuilds will be created for your repository roughly hourly, if the run succeeds, or more often if there were pushes that change the dev container configuration on the branch.

For example, let's imagine 5 pushes are made, in quick succession, against a branch that has a prebuild configuration. In this situation:

  • A workflow run is started for the first push, to update the prebuild.

  • If the 4 remaining pushes do not affect the dev container configuration, the workflow runs for these are queued in a "pending" state.

    If any of the remaining 4 pushes change the dev container configuration, then the service will not skip that one and will immediately run the prebuild creation workflow, updating the prebuild accordingly if it succeeds.

  • Once the first run completes, workflow runs for pushes 2, 3, and 4 will be canceled, and the last queued workflow (for push 5) will run and update the prebuild.