Clarify `About billing for Codespaces`

[jsoref]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces

What part(s) of the article would you like to see updated?

https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces

• Anything that implicitly thinks about repositories should explicitly mention them.
• Anything that only mentions organizations should explicitly mention individual accounts.
• Anything that talks about organization or team accounts should be reworded to not do so, as such things, afaiu do not exist. GitHub has user accounts, and it has organizations. To my knowledge there is no such thing as a "team account".

https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces#calculating-storage-usage

• Anything talking about "your account" should be really clarified to say something else. I have a personal account. I also have a number of organizations. As billing is by organization and not account, it seems unlikely that "your account" is the appropriate term.

Additional information

I understand this feature is somewhat new, but I think it's time for it to undergo a review.

I don't understand the feature enough to provide further input.

---

Content design plan

In the article "About billing for Codespaces" (https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces):

1. In the "Codespaces pricing" section, change the first paragraph to:

   Charges are incurred for the use of {% data variables.product.prodname_codespaces %} for repositories owned by organization and enterprise accounts on {% data variables.product.prodname_team %} and {% data variables.product.prodname_enterprise %}. These accounts do not include any free minutes or storage for {% data variables.product.prodname_codespaces %}. Repositories in personal accounts are not currently billed for {% data variables.product.prodname_codespaces %} usage.
   

2. In the "Calculating compute usage" section, change "Compute usage is calculated by summing the actual number of minutes used by all codespaces." to:

   Compute usage is calculated by summing the actual number of minutes used by all codespaces that are billable to the organization or enterprise.
   

3. In the "Calculating storage usage" section, change "Your Codespaces usage shares your account's existing billing date, payment method, and receipt." to:

   Your {% data variables.product.prodname_codespaces %} usage shares your organization or enterprise account's existing billing date, payment method, and receipt.
   

4. In the "Billing for Codespaces prebuilds" section, change the first sentence of the final paragraph from "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." to:

   If you are an organization or enterprise owner, you can track usage of prebuild workflows and storage by downloading a {% data variables.product.prodname_actions %} usage report for your organization or enterprise. 
   

5. In the first paragraph of the "How billing is handled for forked repositories" section, delete the first sentence and change the second sentence to:

   To incur charges to an organization account (or to an enterprise account, if the organization belongs to an enterprise), the user must be a member or collaborator of that organization, otherwise they cannot create a codespace for which the organization, or its parent enterprise, would be billed.
   

6. In the second paragraph of the same section, delete "private" from "For example, a user in a private organization can fork a repository".

[steveward]

Thanks for opening this @jsoref! I'll triage this for the team to take a look at. 👀

[hubwriter]

@jsoref - Many thanks for raising this.

Anything that talks about organization or team accounts should be reworded to not do so, as such things, afaiu do not exist. GitHub has user accounts, and it has organizations. To my knowledge there is no such thing as a "team account".

There are 3 types of account: personal accounts, organization accounts, and enterprise accounts (see https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts). The article talks about organization and enterprise accounts on GitHub Team and GitHub Enterprise (use of Codespaces by personal accounts is currently in beta and not currently billed). I think the documentation here is correct.

• Anything that implicitly thinks about repositories should explicitly mention them.
• Anything that only mentions organizations should explicitly mention individual accounts.

I'm not clear what you mean by these 2 points. Could you say a bit more about this? If you could refer to specific pieces of text that would be helpful.

Thanks again for raising this issue. I'd really like to make sure that this article is as clear as possible. Your help towards this is much appreciated.

[jsoref]

There are 3 types of account: personal accounts, organization accounts, and enterprise accounts (see https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts).

As my colleague noticed when I went over this with him, that's wrong:

GitHub’s products

• GitHub Free for personal accounts
• GitHub Pro <- this is a type of account too
• GitHub Free for organizations
• GitHub Team
• GitHub Enterprise

---

Codespaces pricing

Codespaces usage is billed for all organization and enterprise accounts on GitHub Team and GitHub Enterprise, which do not include any free minutes or storage. Personal accounts are not currently billed for Codespaces usage.

This is actually talking about repositories.

I think it means something like:

Codespaces usage is billed according to repositories owned by organization and enterprise accounts on GitHub Team and GitHub Enterprise, which do not include any free minutes or storage. Repositories in Personal accounts are not currently billed for Codespaces usage.

---

Calculating storage usage

Compute usage is defined as the total number of uptime minutes for which a Codespaces instance is active. Compute usage is calculated by summing the actual number of minutes used by all codespaces. These totals are reported to the billing service daily, and are billed monthly.

It would be helpful if this clarified that it was "for all accounts that created codespaces for the organization/enterprise".

---

Your Codespaces usage shares your account's existing billing date, payment method, and receipt. To view all the subscriptions for your account on GitHub.com, see "Viewing your subscriptions and billing date."

Is closer to:

Your Codespaces (codespace's? Codespaces's? Codespaces'?) usage shares your enterprise or organization account's existing billing date, payment method, and receipt. To view all the subscriptions for your account on GitHub.com, see "Viewing your subscriptions and billing date."

Because, in fact, a user who may be a billing administrator for an organization account has their own personal account, and when talking about "your account", it's really helpful to clarify whether the organization account or their personal account is being referenced.

---

Billing for Codespaces 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 Codespaces Prebuilds." For more information, see "Viewing your GitHub Actions usage."

This doesn't talk about enterprises, which is odd.

Nor does this:

Codespaces can only be used in organizations where a billable owner has been defined.

Are enterprises not mentioned because all enterprises must have a billable owner? Statements like this are confusing/misleading because by not covering the other cases they read as excluding everything else.

Consider:

For organizations, Codespaces can only used where a billable owner has been defined.

How billing is handled for forked repositories

For example, a user in a private organization can fork a repository within that organization, and can subsequently use a codespace billed to the organization; this is because the organization is the owner of the parent repository, which can remove the user's access, the forked repository, and the codespace.

I'm not sure what a private organization is. 😢 I've certainly never seen an option to make one private.

[hubwriter]

@jsoref - That's really great detail! Many thanks for going the extra mile on this. 🎖️

We'll take a good look at all of these points and someone from the team will write up a content design plan for the necessary changes.

Thanks again for your help with this. Much appreciated. 👍

[mattpollard]

👋🏻 Echoing @hubwriter's appreciation here: thanks for the detail. Just a quick note:

There are 3 types of account: personal accounts, organization accounts, and enterprise accounts (see https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts).

As my colleague noticed when I went over this with him, that's wrong:

GitHub’s products

• GitHub Free for personal accounts
• GitHub Pro <- this is a type of account too
• GitHub Free for organizations
• GitHub Team
• GitHub Enterprise

Slight correction: there are three types of accounts. In the context of GitHub.com...

• Free is a plan for personal accounts and organization accounts;
• Pro is a plan for personal accounts;
• Team is a plan for organization accounts;
• Enterprise is a plan that includes both organization accounts and an enterprise account for containing and managing those organization accounts (and, in the case of Enterprise Managed Users, user accounts that are provisioned and managed by the enterprise account).

You can read more about this in the "Types of GitHub accounts" article.

I'm not sure what a private organization is. 😢 I've certainly never seen an option to make one private.

You're correct: organizations don't have visibility levels (though members of organizations can choose whether to publicize their membership in an organization).

Let me know if you have further questions!

[jaclynj]

Codespaces usage is billed according to repositories owned by organization and enterprise accounts on GitHub Team and GitHub Enterprise, which do not include any free minutes or storage. Repositories in Personal accounts are not currently billed for Codespaces usage.

Yes! This is much clearer.

---

It would be helpful if this clarified that it was "for all accounts that created codespaces for the organization/enterprise".

This is mostly true. It is depends on their org settings. This is our internal billable owner doc* that we keep up to date to understand who should be billed. (who should be billed for the codespace = the billable owner). Note that 'user pays scenario' is not implemented - Codespaces is not publicly available for individuals currently, but users do have access via the Codespaces beta. Users in the Codespaces beta have free usage.

*Edit: Just realized you probably don't have access to the flowchart. Added a screenshot below.

From that flow chart, to understand Is the user allowed to bill Codespaces to the org? - see #4 here https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization#enable-codespaces-for-users-in-your-organization

Depending on the selection, the users specified will be able to create codespaces billable to that org.

So simplifying to "for all accounts that created codespaces for the organization/enterprise" made sense for a while because most users couldn't create a codespace unless an org gave them access, and at the time we paused allowing individuals into the codespace beta.

But as we increase the # of individual users added to the codespace beta, which right now is free for individuals, this means that a beta user that is 'disallowed' from a particular org can still create codespaces in the repo if they have access to the repo. Although they could create the codespace, it wouldn't be billed to the org unless the org allowed for it under access settings.

---

Your Codespaces (codespace's? Codespaces's? Codespaces'?) usage shares your enterprise or organization account's existing billing date, payment method, and receipt. To view all the subscriptions for your account on GitHub.com, see "Viewing your subscriptions and billing date."

Because, in fact, a user who may be a billing administrator for an organization account has their own personal account, and when talking about "your account", it's really helpful to clarify whether the organization account or their personal account is being referenced.

Correct, this is more accurate.

---

Billing for Codespaces 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 Codespaces Prebuilds." For more information, see "Viewing your GitHub Actions usage."

This doesn't talk about enterprises, which is odd.

Nor does this:

Codespaces can only be used in organizations where a billable owner has been defined.

Are enterprises not mentioned because all enterprises must have a billable owner? Statements like this are confusing/misleading because by not covering the other cases they read as excluding everything else.

Consider:

For organizations, Codespaces can only used where a billable owner has been defined.

I am not sure why enterprises aren't measured. In our code we skip billing for the codespace if the billable owner (which depending on some logic is either the repo owner, codespace owner, or parent repo owner in the case of a fork) is a business or business_plus plan which I don't think includes enterprises.

@tanmayeekamath could you confirm what the behavior should be for enterprises?

Also I am not sure what Codespaces can only be used in organizations where a billable owner has been defined. is supposed to mean. Our logic defines who the "billable owner" is. It's not really a user-facing concept, more like an implementation detail. I think we can remove this line.

---

How billing is handled for forked repositories

For example, a user in a private organization can fork a repository within that organization, and can subsequently use a codespace billed to the organization; this is because the organization is the owner of the parent repository, which can remove the user's access, the forked repository, and the codespace.

I'm not sure what a private organization is. 😢 I've certainly never seen an option to make one private.

I am not sure what private organization means either. For forking, if the org has given you access to codespaces for repos within their org, you can fork the repos within that org and your forks will be billed to the parent org. cc @tanmayeekamath to confirm expected behavior and to let us know if private organization is significant here.

[tanmayeekamath]

Thanks for the detailed feedback, this is very helpful!

+1 to everything @jaclynj mentioned above.

Re. Billing for codespaces prebuilds
Going back to the types of accounts:

• Free is a plan for personal accounts and organization accounts;
• Pro is a plan for personal accounts;
• Team is a plan for organization accounts;
• Enterprise is a plan that includes both organization accounts and an enterprise account for containing and managing those organization accounts (and, in the case of Enterprise Managed Users, user accounts that are provisioned and managed by the enterprise account).

For the Team and Enterprise plans, Codespaces can be enabled at an organization account level today. This means, for an Enterprise account that contains multiple organization accounts, an admin will need to enable Codespaces by going to each org account's settings and enable access as needed (https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization#enable-codespaces-for-users-in-your-organization)
I think we need to do better at clarifying throughout our billing docs that organization accounts can either be a part of Team or Enterprise plans and that codespaces + prebuilds billing applies to both.

Very similar to the feedback above, prebuild usage is also billed according to repositories owned by organization and enterprise accounts on GitHub Team and GitHub Enterprise. We'll make a note to clarify this in docs.

For forking, if the org has given you access to codespaces for repos within their org, you can fork the repos within that org and your forks will be billed to the parent org.

This is correct, we should update the docs to remove the mention of private organization.

[hubwriter]

Hi @jsoref - Thanks again for this issue.

I've updated your original comment above with a content design plan detailing the changes that need to be made. You, or anyone else, are welcome to raise a PR making these changes to the markdown file for this article. 🙇