Billing and paid organizations

shithub's first paid surface is organization billing. The code does not ship billing yet; this document records the product and engineering contract that the PAYMENTS sprint series implements.

The current implementation already has the important shape for paid organizations: orgs.plan is an enum with free, team, and enterprise; organizations own repositories; organization members and teams exist; branch protection and PR review gates exist; Actions has schema for org/repo secrets, variables, and artifacts. Billing must turn that substrate into a fair hosted service without taxing public/open-source collaboration.

Product contract

As of 2026-05-12, GitHub's public pricing page presents Free at $0, Team at $4/user/month, and Enterprise starting at $21/user/month. shithub follows the same mental model but removes Copilot/AI promises from the paid-org offering.

Initial decisions:

• Free organizations remain self-serve.
• Team is $4 per active organization member per month.
• Active organization members, including owners, count as paid seats.
• Team has no launch trial.
• Enterprise is a visible contact-sales stub, not self-serve.
• Stripe Billing is the first payment processor.
• PayPal, manual invoices, SAML, SCIM, LDAP, enterprise account hierarchy, and contracts are deferred.

The fairness rule is explicit: public/open-source collaboration should stay generous. Paid gates focus on private collaboration, hosted cost, advanced organization controls, and support expectations.

Entitlement matrix

Current capability audit

Already present and safe to gate:

• Organizations with plan and billing_email.
• Organization members, owner role, and invitations.
• Teams, including privacy='secret'.
• Branch protection rules and required review counts.
• PR review and reviewer-request substrate.
• Org/repo Actions secrets and variables schema.

Present but missing enforcement or metering:

• Storage quota type exists, but quota persistence and enforcement are incomplete.
• Actions minutes, artifacts, and object usage need accounting before paid limits can be promised.
• Packages storage cannot be sold until the Packages sprint is active and quota enforcement exists.

Deferred:

• SAML, SCIM, LDAP, enterprise account hierarchy, audit-log export, data residency, compliance promises, and custom support SLAs.
• Copilot/AI features are intentionally outside shithub's paid-org product.

Billing architecture

Stripe is the payment source of truth. shithub is the entitlement source of truth.

The billing implementation should add a local billing domain that stores only Stripe IDs and payment summaries, never card data. Webhooks update local subscription state after signature verification. Policy and request handlers read local billing/entitlement state and must not call Stripe in hot paths.

Required local concepts:

• Stripe customer per billable organization.
• Subscription state per organization.
• Subscription item ID for seat quantity sync.
• Immutable webhook receipts with unique provider event IDs.
• Invoice/payment summaries for UI.
• Seat snapshots for auditability.
• Billing grace/lock state derived from processed subscription events.

Entitlement architecture

Paid feature checks must live behind a central entitlement package, not as scattered orgs.plan checks in handlers.

Expected feature keys:

• org.secret_teams
• org.advanced_branch_protection
• org.required_reviewers
• org.actions_org_secrets
• org.actions_org_variables
• org.private_collaboration_limit
• org.storage_quota
• org.actions_minutes_quota

Authorization and entitlement are separate gates. A user must have both the policy permission and the paid entitlement for gated writes. Denials must preserve existing policy.Maybe404 behavior where existence leaks matter.

Downgrade behavior

Downgrades must preserve customer data. Moving from Team to Free should not delete teams, secrets, variables, branch rules, or review settings. Existing gated resources become read-only where possible. Users can remove gated configuration, but cannot create or expand it until the organization upgrades again.

Open questions for implementation

• Whether Free should limit private org collaborators before usage metering exists, or whether the first paid gates are advanced controls only.
• Whether required reviewers are gated only for private org repos. The current lean is private-org-only.
• Whether org-level Actions secrets and variables should be Team-only even for public repositories. The current lean is yes for org scope.
• Exact Free and Team quota numbers for Actions and storage. These must come from real host-cost estimates before SP08.

Source references

• GitHub pricing: https://github.com/pricing
• GitHub plans docs: https://docs.github.com/en/get-started/learning-about-github/githubs-plans
• Stripe Billing: https://docs.stripe.com/billing
• Stripe pricing models: https://docs.stripe.com/products-prices/pricing-models