Customer License Key Management

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.

License keys are created and managed on Sourcegraph.com in the Site-admin > Subscriptions page. Valid license keys can only be generated by site administrators on Sourcegraph.com.

This page covers the following related to license key management:

Prospective Customer Trials

For a new Sales-led trial, create a new subscription. You will only use this for the trial. (Follow the instructions for issuing a new license from start to finish.).

A note on Sales-led cloud (managed instance) trials: as part of the Managed Instance creation process, the CE should create a license key for the new instance.

Converting a Prospect to a New Customer

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

Note: if the prospect was a PLG Cloud trial customer, do not reuse the plg-trial tag on their production, paid license. This is for prospects only.

Creating a new license key

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 instance does not have an account yet, navigate to the users page and create new user account. (You can also check for a user already exists following the instructions in the Internal Licensing FAQ document.)
  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. Create a new subscription if this is a new customer. Create a new subscription for each customer instance as well. Click Create product subscription. Search for the user that was created above.
  5. Click Generate new license manually.
    1. Fill out the customer name in lowercase. Fill spaces with the - character.
    2. Fill out the Salesforce Subscription ID and Salesforce Opportunity ID based on the data for this customer/opportunity from Salesforce. Filling these fields will allow automated billing.
    3. Fill out the license subscription plan name. See the plans section.
    4. Fill out the licensed number of users. Note that if you added the true-up tag, the customer will be able to exceed this count, but administrators will see a warning.
  6. If this is a license key for a test/dev instance
    1. consider what would be a good user limit on the license key. The recommendation is to keep it low to prevent abuse, e.g. 5 users.
    2. Add trial and instance:test or instance:whatever_name_is_appropriate tags, so that we can identify which license keys are test and which are not
  7. Fill out the number of days the license should be valid for. Most typically this should match the end date of the contract itself.
  8. Fill in the appropriate license tags. For tags, see the License Key Tags section. Note that licenses for Cloud trial managed instance requests should inclue the plg-trial tag. Remember: Tags must be separated by commas. You can see a list of tags generated under the tags input. If a tag is not recognized, it will be red and a warning will appear.
  9. Click Generate license.
  10. Map the license key to the Salesforce instance for usage data tracking following these directions.
  11. 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

Handling renewals or upgrades

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), the TA will 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).

  1. Sign in to sourcegraph.com and visit the Site-admin > Subscriptions page.
  2. Search for the user associated with the company, and click into the existing subscription ID (left-most column). (You can also check for a user already exists following the instructions in the Internal Licensing FAQ document.)
  3. Click Generate new license manually. Fill out the license end date (most typically to match the contract terms) and fill in the appropriate license tags. For tags, see License Key Tags section. Tags must be separated by comma (spaces are ignored).
  4. Set the licensed number of users (note that if you added the true-up tag, the company will be able to exceed this count, but administrators will see a warning) and the end date for which the license should be valid, and click Generate license.
  5. 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

Reissuing Expired Licenses

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. Check with the account’s Technical Advisor & Account Executive, as well as the Salesforce Account record and the account running notes. This will help you understand any special context surrounding the current license key tags and expiration dates.
  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).

Revoking an active license

In extreme circumstances, it may be required to revoke a customer’s active Sourcegraph license. This will mark the license as invalid on Sourcegraph.com, and license verification checks from the customer’s Sourcegraph instance will fail, ultimately disabling all Sourcegraph Enterprise features.

To revoke an active license, follow these steps:

  1. Sign in to sourcegraph.com and visit the Site-admin > Subscriptions page.
  2. Navigate to the license that needs to be revoked.
  3. Click on the red Revoke button and provide a reason for the revocation.

The next time the customer’s instance performs a license verification check, the verification will fail and the customer’s Enterprise features will be disabled.

License Key Sharing Policy

Within Sourcegraph we use 1Password for managing our credentials, including license keys. Follow these steps for safely sharing licensing credentials with customers.

  1. Create a new record in your private Vault (type = software license).
  2. Name the entry the customers’ name, enter the license key, and enter the admin’s email address. Click Save.
  3. Go to the newly created record and click Share. A prompt will be displayed with sharing options. Set the link to expire after 7 days, make it available only to some people, check the box for “Can be viewed only 1 time per person”, and enter the admin’s email address. Click Get Link to Share.
  4. Copy the private link that is generated and send to the admin. (Note: they must verify their email address to access the link).

Out of Contract License Extensions

In select circumstances, such as a bridge extension being requested due to the renewal process not aligning with license expiration, Sales must receive approval from the VP of Finance and VP of Sales to issue a licensing exception. This approval is granted via request in #deal-desk. If an AE requests a deviation from their contract licensing terms, please validate that the necessary approvals have been granted before making any changes to a customers’ license key.

Plans

Below is a list of supported plans:

  • enterprise-air-gap-0 (from 5.1 onwards) for Enterprise customers that need to run Sourcegraph in an air-gapped environment
  • enterprise-1 (from 4.0 onwards) for Enterprise customers, code-insights and batch-changes included

    [!NOTE] this should be the default plan for most of the enterprise customers.

  • enterprise-0 (until 4.0) for Enterprise customers, features above only included if tags of same name are added
  • business-0 for Business customers, code-insights and batch-changes included
  • team-0 (until 4.0) for a handful of customers on the Team plan
  • free-0 for legacy Free plan (until 4.5) customers, for which we need to generate a license to keep them using the existing feature set
  • free-1 for new Free plan (from 4.5 onwards). We should not generate licenses with this plan at the moment, because it is automatically assigned when no license key is given

License key tags

The tags that relate to license itself (you might need to add these to the license, depending on the customer contract)

  • 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.

    [!NOTE] For any MAU-based customers, the true-up tag must also be added as we do not have the ability to hard-cap MAU-based plans.

  • trial to show an indicate in Sourcegraph that the company is on a trial.
  • plg-trial to indicate that a Cloud trial managed instance has been requested through signup.sourcegraph.com.
  • dev for internal developer licenses
  • internal for licenses used for internal sites (dotcom, k8s, etc.)
  • allow-air-gapped for licenses where periodic license verification is not required and pings are not sent back to sourcegraph.com. This is essential for customers that run Sourcegraph in an air-gapped environment without an external internet connection. For the enterprise-air-gap-0 plan, this tag is not required as it is included in the plan. Prefer selecting the enterprise-air-gap-0 plan instead of adding the tag.

Feature override tags are listed below. These tags enable specific features on top of what the license plan allows:

  • acls for repository permissions from the code host.
  • batch-changes for unlimited Batch Changes (formerly campaigns).
  • code-insights for unlimited Code Insights.
  • private-extension-registry to allow for a private Extension registry.
  • remote-extensions-allow-disallow to allow for the admin to enable/disable remote extensions.
  • monitoring - Adds support for running Grafana monitoring. DEPRECATED as of Sourcegraph 5.0

Example license key tags:

  • Enterprise Licenses: usually no need to add additional tags for Sourcegraph 5.0+

    • Optionally add true-up, mau, trial based on the context of the license.
    • batch-changes and code-insights tags should only be added to legacy enterprise-0 plan or other plans that do not automatically add the feature. enterprise-1 plan alreadty contains both.
    • monitoring tag should only be added for instances on version 4.x and lower.

  • Non-enterprise Licenses: these depend on the contract & specified features.

    [!NOTE] only add batch-changes and code-insights tags if the contract specifies unlimited usage of these features.

  • Teams Licenses: Only applicable for team license renewals. Add plan:team-0,acls,monitoring, plus the customer name, to all Teams licenses.

See our Sourcegraph License Builder for more information or help compiling the correct license tag values.

Legacy tags

We used to tag each license with the customer name. Since the form to create licenses was revamped, we expect the customer tag to be in the format of customer:customer-name. However this tag is now autogenerated from the form, if the customer name is filled in. No need to fill it in manually as a tag anymore.

Similarly, we now add a tag for the license subscription plan automatically, no need to specify that as a tag anymore.

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-1) allows access to all features.

plan:enterprise-0 represents our legacy enterprise pricing plan. plan:enterprise-1 was launched in with Sourcegraph 4.0.

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.

Internal licensing FAQ

In case you have a question regarding licensing that is not discussed on this page, check if it is answered in the internal licensing FAQ.