Requirements for listing an app

Apps on GitHub Marketplace must meet the requirements outlined on this page before our GitHub Marketplace onboarding specialists will approve the listing.

In this article

Before you submit your app for review, you must read and accept the terms of the "GitHub Marketplace Developer Agreement." You'll accept the terms within your draft listing on GitHub. Once you've submitted your app, one of the GitHub Marketplace onboarding specialists will reach out to you with more information about the onboarding process, and review your app to ensure it meets these requirements:

User experience

  • GitHub Apps should have a minimum of 100 installations.

  • OAuth Apps should have a minimum of 200 users.

  • Apps must provide value to customers and integrate with the platform in some way beyond authentication.

  • Apps must be publicly available in GitHub Marketplace and cannot be in beta or available by invite only.

  • Apps cannot actively persuade users away from GitHub.

  • Marketing materials for the app must accurately represent the app's behavior.

  • Apps must include links to user-facing documentation that describe how to set up and use the app.

  • When a customer purchases an app and GitHub redirects them to the app's installation URL, the app must begin the OAuth flow immediately. For details, see "Handling new purchases and free trials."

  • Customers must be able to install your app and select repositories on both a personal and organization account. They should be able to view and manage those accounts separately.

Brand and listing


Apps will go through a security review before being listed on GitHub Marketplace. A successful review will meet the requirements and follow the security best practices listed in "Security review process." For information on the review process, contact

Billing flows

Your app must integrate billing flows using the GitHub Marketplace webhook event.

Free apps

Free apps are encouraged in GitHub Marketplace and are a great way to offer open source services. If you list a paid version of your app outside of GitHub Marketplace, you must offer at least one paid plan when listing the app in GitHub Marketplace. If you are listing a free app, you'll need to meet these requirements:

  • Customers must be able to see that they have a free plan in the billing, profile, or account settings section of the app.
  • When a customer cancels your app, you must follow the flow for cancelling plans.

To offer your app as a paid service, you'll need to meet these requirements to list your app on GitHub Marketplace:

  • To sell your app in GitHub Marketplace, it must use GitHub's billing system. Your app does not need to handle payments but does need to use "GitHub Marketplace purchase events" to manage new purchases, upgrades, downgrades, cancellations, and free trials. See "Billing flows" to learn about how to integrate these events into your app. Using GitHub's billing system allows customers to purchase an app without leaving GitHub and pay for the service with the payment method already attached to their GitHub account.
  • Apps must support both monthly and annual billing for paid subscriptions purchases.
  • Listings may offer any combination of free and paid plans. Free plans are optional but encouraged. For more information, see "Setting a GitHub Marketplace listing's pricing plan."
  • Customers who cancel a paid plan purchased from GitHub Marketplace must be automatically downgraded to the app's free plan if it exists. When a customer cancels a GitHub Marketplace subscription, GitHub does not automatically uninstall the app, so the customer can expect that free features will continue to function. It's highly recommended to allow customers to re-enable their previous plan.
  • Customers must be able to upgrade from your app's UI if you provide an upgrade URL in this format:<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/<CUSTOMER_ACCOUNT_ID>
  • Customers must be able to modify which users have access to your app from your app's website if they purchased seats (per-unit pricing plan) or the plan offers unlimited collaborators.
  • Customers must be able to see the following changes to their account immediately in the billing, profile, or account settings section of the app's website:
    • Current plan and price.
    • New plans purchased.
    • Upgrades, downgrades, cancellations, and the number of remaining days in a free trial.
    • Changes to billing cycles (monthly or yearly).
    • Usage and remaining resources for flat-rate and per-unit plans. For example, if the pricing plan is per-unit, your app's site should show units used and units available.

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.