Creating and maintaining license keys for customers

Sourcegraph requires site administrators to input a license key to have access to various paid features. This page explains how to create, use, and maintain license keys for prospects and customers.

Valid license keys can only be generated by site administrators on Sourcegraph.com.

License keys are created and managed on Sourcegraph.com in the Site-admin > Subscriptions page.

For a new trial, create a new subscription. You will only use this for the trial. (Follow the instructions below from start to finish.)

When the customer converts, create a new subscription; do not reuse the trial subscription. (Follow the instructions below from start to finish.) This is to ensure data accuracy for the Sales Ops team.

How to reissue a license key for an expiring license

In most circumstances, license keys match the renewal dates on an account contract and are generated well ahead of time. Sometimes, license keys deviate from this format due to product trials and other special circumstances. If a license key is imminently expiring or has expired, follow these steps:

  1. If possible, check with the account’s Customer Engineer & Account Executive, as well as the account running notes. This will help you understand any special context surrounding the current license key tags and expiration dates. The account team may opt to extend a product trial key for a specific amount of time.
  2. Grab the contract end date by going to the Account page in Salesforce to look up the "Active Contract Period End".
  3. Follow the process below for generating a renewal license key. Unless otherwise noted during Step 1, use the same exact tags and user count as the existing key (make sure to comma separate each tag) and use the "Active Contract Period End" as the expiration date.
  4. Send the new license key to the customer (follow the process outlined below).

How to create a license key for a renewal or upgrade

If an existing company or customer needs a new license key for any reason (e.g., they purchase more seats, they upgrade product tiers, or they simply renew), add a new license key to the existing subscription. In that circumstance, do not click Create a product subscription; find the existing subscription on that page and then once viewing it, click Generate new license manually.

Visit the Site-admin > Subscriptions page, find the existing subscription, click into it, and follow the steps below (from the “Click Generate new license manually” step onwards).

How to create a license key for a new prospect or new customer

The CE should first create a Sourcegraph.com user account for the prospect/customer. Assuming there is not one already. The username of the account should have the following format CompanyName-UniqueId. This is format is described below. The email of the account should be left blank. Once that is available, follow the steps below.

  1. Sign in to sourcegraph.com.
  2. If the customer does not have a license yet, navigate to the users page and create new user account.
  3. Create an account with the username CompanyName-UniqueId. Replace CompanyName with the company name, and use the Unique ID from the Unique Account ID field on the Account record in Salesforce.
  4. Navigate to the subscriptions page. If the user needs a new product subscription (new prospect doing a trial, or an existing prospect purchasing a production license for the first time), click Create product subscription. Search for the user you just created.
  5. Otherwise (renewals or expansions), just search for the user associated with the company, and click into the subscription ID (left-most column).
  6. In either case, click Generate new license manually. Fill out the license end date and tags. For tags, see License Key Tags for a list you can just copy. Tags should be separated by commas, with no spaces. You will need to include:
  • plan:enterprise-0 or plan:team-0 for Enterprise or Teams customers, respectively.
  • true-up to allow the company to go over the user limit on the license. No tag is needed for hard cap.
  • mau to indicate that the company is on a monthly usage-based billing model.
  • trial to show an indicate in Sourcegraph that the company is on a trial.
  • batch-changes for Batch Changes (formerly campaigns)
  • code-insights for Code Insights
  • acls for external Permission syncing from the code host. (Add this to all licenses.)
  • private-extension-registry to allow for a private Extension registry. All Enterprise licenses should have this added.
  • remote-extensions-allow-disallow to allow for the admin to enable/disable remote extensions. All Enterprise licenses should have this added.
  • monitoring - Monitoring. All licenses should have this added.
  • internal for licenses used for internal sites (dotcom, k8s, etc.)
  • dev for internal developer licenses
  • The company’s name (with dashes instead of spaces), to make it easy to search for a given license key in the future.
  1. Set the licensed number of users (note that if you added the true-up tag above, the company will be able to exceed this count, but administrators will see a warning) and the number of days that the license should be valid, and click Generate license.
  2. Finally, copy the license key, and send it to the relevant contact at the company. You can link them to the following docs for instructions on where to add the key: Updating your license key

License Keys for Managed Instances

As part of the Managed Instance creation process, the CE should create a license key for the new instance. Per our steps we ask CE to create the license. However, the CE needs to provision additional licenses to account for Sourcegraph administrators. The number of additional licenses is determined by the number of members of the cloud team but we reccomend a standard buffer of 10.

License key tags

  • Enterprise Licenses: plan:enterprise-0,acls,private-extension-registry,remote-extensions-allow-disallow,monitoring, plus the customer name, should be added to every Enterprise license. Optionally add true-up, mau, trial, batch-changes, and code-insights based on the context of the license.
  • Teams Licenses: Only applicable for team license renewals. Add plan:team-0,acls,monitoring, plus the customer name, to all Teams licenses.

Sourcegraph License Builder

Legacy tags

The enterprise tag is a legacy tag that should not be used anymore. It gives access to all features, including batch-changes. Similarly, a license with no plan: tag (no plan:team-0, plan:enterprise-0) allows acess to all features.

Future state

These tags are supported but not currently saleable: - branding: Whether custom branding of this Sourcegraph instance has been purchased. - backup-and-restore: Whether builtin backup and restore on this Sourcegraph instance has been purchased.

If no plan:* tag is supplied, the license will be treated as legacy enterprise tier which has unlimited access to all features.

How to delete a license key

Unfortunately, once a license key is created, it cannot be disabled or deleted.

If the company hasn’t yet received or seen the license key, it’s easy to hide it. Users can only ever see the latest key associated with their subscription. So just re-follow the steps above (from the “Click Generate new license key manually” step onwards) and they will never be able to see the previous key.

However, if a company has already accessed and copied the key, there is nothing we can do to change it. As a result, try to minimize the duration and user count on keys to only that which is actually necessary. As an example, if you want to create an “unlimited” license for a company that has 100 employees, don’t create a key that allows 999,999,999 to achieve that. This minimizes any risks of the key becoming exposed. Instead, create one that is close to the actual total, as we can always create a new, larger key for them in the future.

Viewing current license keys

All license keys can be found in a complete list or in the individual instance views.

Finding usernames

Our user search doesn’t search emails—so, you may miss the user you’re trying to find. If you can’t find the username associated with the customer/prospect, you can run the following API query:

query{
  user(email: "THEIR EMAIL") {
    username
    emails {
      email
      verified
    }
  }
}

That should return their username, email(s) and whether the email address is verified.

Gating issues

If you come across an issue with the gating system, the first step is to check the license of the customer. Make sure that it was created following the guidelines above.

Many reported issues are due to:

  • The customer has a legacy license. If it is a legacy license, gates may not be enforced. This is easily fixed by creating a new license with updated tags for the customer, usually at renewal given they will need a new license at that time.
  • The customer is on version 3.26 or below. The current gating system was introduced in 3.27, so older versions may not be gated properly.

If the problem you are observing is none of the cases above, please submit it as a product gap. If unsure, ask in #wg-gating.