We’ve heard from admins across a number of organizations about the need to manage codespaces at scale in order to minimize waste, and to stay compliant and within budgets. With policies, admins are able to manage machine types, maximum idle timeouts, and port visibility to provide better security and cost control. Today, we’re releasing additional capabilities that will enable organizations to efficiently manage and confidently scale with Codespaces.

Codespaces now clean up after themselves

Inactive codespaces will now automatically delete if they have been unused after a default period of 30 days. With that, developers no longer need to remember to manually clean up old instances of developer environments that may be unintentionally generating additional cost.

Retention setting for all individuals

The default Codespaces 30-day retention period setting applies to all individual users on GitHub.com that are using Codespaces. Developers can choose to adjust this setting to a value up to 30 days if needed.

To help developers stay informed, they will be notified via email when their codespace is scheduled to be deleted in 24 hours. If you want to retain your codespace, just reconnect to it, and the retention period counter will reset. In addition to the email notification, you can also view the expiration period for your codespaces by navigating to GitHub.com/codespaces or in the Green Code dropdown when you create a new codespace. These notifications work together to ensure your codespaces don’t accidentally get auto-deleted.

If your codespace was accidentally deleted due to the retention setting and you need it restored, you can always reach out to GitHub Support. Lastly, this setting will only apply to new codespaces created after this feature is released.

Retention policy for organization administrators

Organization admins will now be able to set an organization-level retention constraint to define the maximum retention period that will override the individual retention setting for organization-owned codespaces. With this, admins no longer need to remind individual teams to clean up stale codespaces and can manage costs with a maximum setting that addresses their needs. Like the retention period setting, organization members will be notified via email 24 hours prior to the scheduled deletion of their codespaces, in case they want to connect to it to save it.

Organization APIs available in public beta

Alongside retention settings, today we’re introducing support for organization-level REST API and CLI commands in public beta so that admins can programmatically manage their organization-owned codespaces at scale. As an admin, have you ever experienced the need to stop and force delete a set of codespaces on behalf of users or get a list of codespaces across repositories in your organization to observe how teams are using it?

Organization API and CLI commands will address these scenarios by providing you with a set of commands that you can execute in your command line, thus saving you time and effort as more teams within your organization start using Codespaces. With this beta, we’re adding support for the following API and CLI commands that organization admins can utilize:

API

• List all codespaces within your organization.
• Get information on a specific codespace within your organization.
• Stop or delete codespaces within your organization.

CLI

• List all codespaces within your organization.
• Stop codespaces within your organization.
• Delete codespaces within your organization.

Our goal is to continue iterating on organization APIs during the beta period, and we would love to hear any feedback to help make these better for your scenarios.

Lastly, if you’re a developer wanting to manage your own codespaces programmatically, you can find user-level Codespaces APIs in our documentation that are generally available. With these APIs, you can perform CRUD (Create, Read, Update, and Delete) operations, view available machine types, and manage user-level and repository-level secrets for your codespaces seamlessly.

How to get started

The default 30-day retention setting will be applied to all new codespaces going forward across GitHub Free, Team, and Enterprise Cloud plans. The maximum retention policy constraint is generally available, and organization APIs are in public beta for GitHub Team and Enterprise Cloud plans.

Here are links to our documentation to get started:

• Default Retention Setting
• Maximum Retention Policy
• Organization APIs

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

Written by

Tanmayee Kamath

@tanmayeekamath