codespaces

GitHub Codespaces with included free usage is now rolling out to all GitHub Free and Pro accounts. We've added experiences to quickly start new projects in a codespace using many of the frameworks you know and love. These templates are a prebuilt development environment all boxed up to work with one click, without the need to configure your development environment.

Codespace templates come with a pre-configured devcontainer. Using a forwarded port you can see your running web application. The configuration of the devcontainer enables the necessary files to be open by default, run the services necessary, and preview the output of the application in your web editor.

Do you want to start developing in Codespaces, but you're unsure what framework to start with? Use the Blank Template to jump right into a brand new codespace! We've also included a set of starter templates for you on the Codespaces index page. You can even make your own your template for developers to use by creating your own repository template! By creating your own codespace template from a repo template, you can create a one-click, prebuilt development environment for others to use your projects.

We hope you take Codespace Templates out for a spin, and join us in the community discussion space to share your templates and collaborate with us!

A development container allows you to create a full-featured development environment to use in your codespace. Codespaces use the devcontainer.json file to define the environment you will be working in within your codespace. We've added new features to devcontainers.json to help you customize the initial experience when you open a codespace.

Define the initial layout of your codespace with openFiles

You can use openFiles to define what files are open by default. If you specify multiple files, the files will open up in order from left to right. The first file defined will be the focused file. openFiles is specific to the Codespaces customization, and is only enabled in the Codespaces web editor for now. Use openFiles to improve your default development environment and ensure that you're setting contributors up for success!

Run scripts after your client connects to your codespace with postAttachCommand

postAttachCommand enables you to run scripts in the terminal after your client connects to the codespace. This change enables you to define multiple postAttachCommand definitions and they will run on separate terminals. This enables you to start your server and watch for changing files after launch from your devcontainer.json.

Combine these features into a full initial codespace experience

These changes to postAttachCommand, combined with the existing openPreview option in the onAutoForward property, enable you to create codespaces with a default layout that ensures a great Codespaces launch experience for users of your repository.

Read more about postAttachCommand, onAutoForward, openFiles, and openPreview on our docs pages!

With an organizational level policy to restrict container images, organization administrators can now control which base container images are used while creating organization-owned codespaces. This enables administrators to ensure that only verified container images are being used to create organization-owned codespaces.

Organization admins can specify which images and/or image sources are allowed to be used while creating organization-owned codespaces. If the image specified in the dev container configuration does not match one of the allowed images, then subsequent codespace creation will fail asking you to update the image in your configuration. The base image policy does not apply to the default image, or the image that's used to recover a codespace if an error is introduced into a dev container configuration which prevents the container from being rebuilt.

For this release, the image policy will be applied at codespace creation and will not be applied when you rebuild a container. Support for the rebuild scenario is coming soon. We'd love your feedback on this policy and any additional policies that will help your scenarios on Codespaces discussions.

For more information, see Restricting base images for organization-owned codespaces

Preview Changes in Your Web Editor

Have you ever launched an application in your codespace only for the running application to get lost in a sea of browser tabs? Today we're announcing the ability to preview your running application directly in your web editor.

Update your Preview URL

Supporting this feature required a change to the URL of previewed applications from -.githubpreview.dev to -.preview.app.github.dev. This is potentially a breaking change. If you rely on a .githubpreview.dev preview url in any project you will need to update your code to reflect the new URL format.

Alternatively, the environment variable GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN gives you access to the domain that your application will forward to. This will enable you to code in this variable anywhere you have hard-coded the preview URL.

Today, we're releasing updates that will optimize prebuilding codespaces for your repositories. With these updates, as long as there is an active prebuild for a given repository, branch, and devcontainer combination, you will be able to spin up prebuilt codespaces for it, even if the latest prebuild workflow for that branch might be failing. This ensures fast codespace creation most of the times regardless of any breaking changes that may be adversely affecting the latest prebuild update.

Repository admins will have the option to disable this optimization if needed by going to their prebuild configuration page under advanced options.

For more information, see Configuring prebuilds for your repository.

If you have any feedback to help improve this experience, be sure to post it on our discussions forum.

With this update, organization admins can manage billing settings for codespaces that are created for organization controlled repositories. Admins can choose to opt-in to the organization covering the bill for GitHub Codespaces, enable Codespaces access only for select members of the organization, allow for all organization members, or also include outside collaborators. See the screenshot below, and documentation for Enabling GitHub Codespaces for your organization for more details.

Note: The functionality of this interface remains the same. The label was updated to "Billing" where it used to be labeled "User permissions" to increase clarity. There are no changes required to your settings as a result of this update.

Any GitHub user who can clone a repository and has access to Codespaces will be able to create a codespace for it. To manage who can clone a repository in your Organization see Managing teams and people with access to your repository.

In April 2022, we released improvements to help streamline your Codespaces experience when working with multi-repository and monorepo projects. Today we're announcing support for prebuilding these project types as well to enable you take advantage of fast creation times across any project configuration.

Prebuilding codespaces for multi-repository projects

For multi-repository projects, or projects that need additional dev time resources (ex. packages), repository administrators can now specify required permissions in the dev container configuration for a prebuild-enabled branch. The prebuild configuration UI will then guide the administrator to authorize those permissions during the creation of the prebuild. This means that users no longer have to set up and manage repository level personal access tokens for prebuild-enabled multi-repository projects.

Prebuilding codespaces for monorepo projects

For monorepo projects, repository administrators can choose a specific dev container configuration from within their repository to be prebuilt while configuring the prebuild. This enables sub-teams working on specific parts of a monorepo to have a prebuild that is optimized for their scenario and requirements.

Get started

Here are some helpful links to get you started:

• Creating a prebuild configuration for multi-repository projects
• Creating a prebuild configuration for monorepo projects

If you have any feedback to help improve this experience, be sure to post it on our discussions forum.

Today, we’re announcing that the ability to prebuild codespaces is entering general availability. A prebuilt codespace serves as a “ready-to-go” template where your source code, editor extensions, project dependencies, commands, and configurations have already been downloaded, installed, and applied so that new codespaces are available on-demand without any wait period. This helps significantly speed up codespace creations–especially for complex or large codebases.

With general availability, we’ve introduced a ‘prebuild in progress’ label in cases where a prebuild template creation is in progress to enable developers stay informed for when a given branch and machine type is ready for a fast codespace creation experience. Administrators now have more control on how often prebuild configurations are updated to manage Actions usage. They can also configure retention settings on prebuild templates to manage underlying storage costs. Additionally, with failure notifications, repository administrators can specify a set of individuals or teams to be informed via email in case a prebuild-associated workflow fails to help with efficient monitoring. Administrators can also temporarily pause a prebuild workflow run while fixing an underlying issue.

With general availability, organizations will be billed for Actions minutes required to run prebuild associated workflows and storage of templates associated with each prebuild configuration for a given repository and region. As an administrator, you can download the usage report for your organization to get a detailed view of prebuild associated Actions and storage costs for your organization-owned repositories.

Prebuilt codespaces are generally available for all GitHub Enterprise Cloud and Team organizations. Repository admins can head over to their repository’s settings page and create prebuild configurations under the Codespaces tab. Once set up, you can take advantage of fast codespace creation by selecting machine types with the ‘prebuild ready’ tag.

Check out the prebuilds documentation to get started!

When you work in a codespace, the environment you are working in is created using a development container, hosted on a virtual machine. If you don’t define a configuration in your repository, GitHub creates a codespace using a default Linux image. This Linux image includes common languages and runtimes such as Python, Node.js, JavaScript, TypeScript etc. to help you get started with an environment that you can further customize or use as is based on your team’s needs.

‘Zero-configuration’ getting started experience for machine learning users

With this update, we’ve released a new version of the default image that enables a seamless getting started experience for machine learning scenarios:

• The default image now has Jupyter pre-installed by default so that you can immediately run jupyter notebook or jupyter lab from the terminal to get started with your data science project.
• The default image also has the following commonly used machine learning specific Python libraries pre-installed by default:
  • For numeric computing: numpy, pandas, scipy
  • For data visualizations: matplotlib, seaborn
  • For model building: scikit-learn, tensorflow, keras, torch
  • For data fetching: requests
• Lastly, you can include any additional project-dependent Python packages in the requirements.txt file, and those will be automatically installed at a user scope when you create your codespace.

Additional updates

• Alongside these improvements, the default image has been updated with the following tools to optimize for speed and costs associated with default codespaces. We’ve also updated the major version of the image to 2 since the removal of these toolsets introduces breaking changes. While some of the tools are not included by default anymore, you can always add these by creating your own devcontainer configuration.
  
  Tools added:

  • Node 14
  • Node 16
  • Python 3.9
  • Python 3.10
  • Conda 4.12
  • Java 11
  • Maven 3.8
  • Ruby 3.0
  • Ruby 3.1
  • PHP 8.0
  • PHP 8.1
  • PHP Composer 2.3
  • Hugo 0.96
  Tools removed:

  • Node 12
  • Python 3.8
  • Conda 4.8
  • .NET 5.0
  • Ruby 2.7
  • PHP 7.2
  • PHP 7.3
  • PHP Composer 2.0
  • Hugo 0.90
  • Maven 3.6
  • PowerShell
  • Az CLI
  • Rust

• Lastly, as a part of this update, for tools that have LTS support (e.g. node, python), the default image will include the latest two LTS releases going forward.

To learn more, check out the latest Codespaces default image configuration.

Currently, codespaces are automatically stopped after 30 minutes of inactivity to avoid wasteful resources when they're not being used. Additionally, a default idle timeout can be set for a codespace of up to four hours.

We heard from many organization admins that they want to restrict idle timeouts for organization-owned codespaces as a measure of cost control. With this feature, we've added the ability for administrators to set a maximum idle timeout that applies to organization-owned codespaces. For instance, if the maximum idle timeout constraint is set to 15 minutes, then all organization-owned codespaces will be automatically stopped after 15 minutes of inactivity regardless of the default timeout set by individual developers.

We will continue adding additional policy constraints based on feedback, some of which include setting maximum retention periods, setting allowed container images, and more. We'd love your feedback on additional policies that will help your scenarios on Codespaces discussions.

For more information, see Restricting idle timeouts for organization-owned codespaces

Codespaces now has improvements that will streamline your experience when working with multi-repository and monorepo projects.

To enable teams to develop applications that span across multiple repositories (e.g. common in microservice architectures), we have added the ability for users to configure which permissions their codespace should have on creation. This means that users will no longer have to set up a personal access token inside of their codespace to clone or create pull requests for multiple repositories.

Additionally, if you're a part of a larger organization and have many teams working in a single repository (e.g. monorepo), Codespaces now supports multiple devcontainer.json files inside of your .devcontainer directory, as long as they follow the pattern of .devcontainer/${DIR}/devcontainer.json.

Lastly, to provide more flexibility during codespace creation, there's a new advanced create flow for Codespaces that allows you to select various options, such as branch, geographic region, machine type, and a specific dev container file while creating your codespace. If you want to skip the advanced creation flow, you can always go for the one-click create by selecting Create codespace on <branch name> to create a codespace with the default configuration.

With these updates, repositories can be setup with multiple devcontainers, each with permission sets, setup scripts, and a codespace configuration specific for certain sub-teams or developer roles (e.g. front-end, back-end). Then, developers can select the ideal devcontainer, machine type, and geographic region for their task during the codespace creation with the advanced flow, as needed.

Here are some helpful links to get you started!

• Configuring codespaces for multi-repository scenarios
• Configuring multiple devcontainers for a repository
• Codespaces advanced creation

Repository administrators can now configure how often/when prebuild configurations for a given branch should be updated. Prebuilds enable developers to startup Codespaces in seconds – regardless of repository size or complexity – by building your development environment beforehand. Previously, prebuild configurations were updated on every push made to a prebuild-enabled branch. During public beta, we heard from many repo admins requiring more control on how often their configurations should be updated based on their team’s processes as well costs associated with running Actions workflows to keep configurations up to date.

With this feature, admins can now make more nuanced trade-offs between environment “freshness” and Actions usage. For example, an admin working in a large organization may decide to update their prebuild configuration every hour rather than on every push to get the most economy and efficiency out of their Actions usage. While creating or updating prebuilds for a given repo and branch, repository admins can choose from three triggers to initiate a refresh:

• Every push (default): With this setting, prebuild configurations are updated on every push made to the given branch. This ensures that new Codespaces always contain the latest configuration, including any recently added or updated dependencies.
• On configuration change: With this setting, prebuild configurations are updated only when configuration files (ex. devcontainer) change. This ensures that developers always have access to a Codespace based on the latest configuration without having to run Actions workflows on every push made to the repo.
• Scheduled: With this setting, you can have your prebuild configurations update on a custom schedule only, regardless of any pushes made to the branch or updates made to associated configuration files. This can further reduce consumption of Actions minutes and give admins even more control on how often configurations should be updated.

For more information, see Configuring prebuilds for your repository

Currently, forwarded ports within codespaces can be set to private in which case they can be accessed only by the owner of the codespace, be shared with members of the organization or be set to public at which point anyone the URL is shared with can view the port. We heard from many organization admins that they want to disable public ports for organization-owned codespaces with the goal of ensuring that company assets can only be shared and accessed by members of the organization for security purposes.

With this feature, we have added the ability for organization admins to add port visibility constraints that enable them to control which visibility settings are available within organization-owned codespaces. For instance, admins will be able to disable the 'public' visibility port setting for desired repositories within their organization and enable developers to continue sharing ports only with members of their organization. This would be done to help preventing codespaces users from accidentally exposing company owned assets to unauthorized individuals.

We will continue adding additional policy constraints based on feedback, some of which include setting a maximum idle timeout, setting maximum retention periods, setting allowed container images, and more. We'd love your feedback on additional policies that will help your scenarios.

For more information, see Restricting the visibility of forwarded ports