Unpacking GitHub Codespaces Storage: A Deep Dive into Free Tier Limits and Effective Repo Tracking

A recent discussion on GitHub's community forum illuminated a common pain point for educators and developers alike: understanding and managing GitHub Codespaces storage usage, especially when operating within free tier limits. Computer Science teacher Jim McCormick sparked the conversation, highlighting his students' unexpected encounters with storage limits despite seemingly low actual file usage. This scenario, common in environments utilizing modern software engineering management tools, underscores the need for clarity in cloud resource billing.

The Codespaces Storage Conundrum: GB-hr vs. GB-month

Jim's initial confusion stemmed from GitHub reporting usage as "15 GB-hr" while free accounts offer "15 GB-month." He correctly pointed out that 15 GB-hr would be an incredibly small allowance, especially when his students' actual codebases were under 2GB. The core of the problem, as clarified by community experts, lies in how GitHub Codespaces provisions and meters disk storage.

Understanding GitHub's Codespaces Billing Model

• Default Provisioned Disk Size: Even if a student's repository or code takes up only a few hundred megabytes, GitHub Codespaces by default provisions a 32 GB block storage disk for standard virtual machines. Storage usage is calculated based on this allocated disk capacity, not the actual amount of space occupied by files.
• Stopped Codespaces Still Consume Storage: A critical insight is that when a student finishes a lab and closes their browser, the Codespace enters a 'stopped' state. While compute billing halts, the provisioned 32 GB disk continues to exist and accrue storage until the Codespace is explicitly deleted. The default retention period for stopped Codespaces is 30 days.
• The GB-month Calculation: The "GB-month" metric is cumulative. 1 GB-month is equivalent to 1 GB maintained for the full month (approximately 720 hours). For example, a single 32 GB Codespace existing for just 11.25 days (270 hours) would consume around 12 GB-months of storage (32 GB * 270 hours / 720 hours). Two 32 GB Codespaces (64 GB total) existing for only 7 days (168 hours) would nearly exhaust the 15 GB-month free quota (64 GB * 168 hours / 720 hours = 14.93 GB-months). This explains why students quickly hit limits if they create multiple Codespaces and don't delete them.

Resolving and Preventing Codespaces Storage Overages

For educators and developers engaging in repo tracking and resource management within Codespaces, several actions can mitigate unexpected storage consumption:

Immediate Actions for Students and Teachers:

1. Delete Existing Stopped Codespaces: Students should regularly visit github.com/codespaces, review their list, and explicitly delete Codespaces from completed labs using the three dots menu (...) -> Delete.
2. Shorten the Default Retention Period: Individual students can adjust their retention period in Settings > Codespaces > Retention period (e.g., to 1 or 3 days). For organization-managed Codespaces, an organization owner can enforce a retention policy under Organization Settings > Codespaces > Policies > Retention period.
3. Inspect Detailed Usage Reports: For precise insights into Codespace IDs, provisioned gigabytes, and hourly timestamps contributing to usage, navigate to Settings > Billing and plans > Get usage report, select Codespaces, and download the CSV report.
4. Check for Prebuilds: Ensure Codespace prebuilds are not inadvertently enabled on template repositories, as stored prebuild images also consume significant quota.

Verifying Disk Usage:

Students can check actual disk usage within their Codespace terminal using:

df -h

Organization vs. Individual Billing:

It's important to note that when students join an organization, they generally still use their personal free allowance (15 GB-month, 120 core-hours) unless the Codespaces are explicitly configured to be organization-owned. Jim McCormick confirmed his Codespaces were owned by individuals, meaning personal limits applied.

Conclusion

The GitHub Codespaces storage discussion highlights a crucial aspect of cloud-based development: understanding the underlying billing mechanisms. Proactive management—deleting unused Codespaces, adjusting retention policies, and monitoring usage—is key to staying within free tier limits and optimizing resource allocation. For educators, integrating these best practices into curriculum helps students develop good habits in managing their cloud development environments, an essential skill in modern software engineering management tools.