Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Associating a subscription with a namespace & troubleshooting errors

On this page

Provisioning subscriptions for reseller customers

L&R and people working in the gitlab.com queue have been tasked with assisting customers who don't have access to the customers portal in their provisioning steps for setting up a new gitlab.com subscription. You can read more about the change in this issue.

Note that the requests will come in as a response to this provisioning email. Reseller customer and sales-assisted customers will receive this email.

You can verify reseller customers by looking at the edit page for their customers portal account - you will see Login activated field is unchecked.

Take the following steps for this provisioning request:

  1. Login into the customers portal with admin permissions
  2. Log into gitlab.com with admin login
  3. Impersonate user on gitlab.com
  4. Impersonate user in customers portal
  5. In Customer portal, go to My account drop-down -> select Account details -> go to Your GitLab.com account section -> select Link my Gitlab.com account button
  6. You should now have linked the user's GitLab.com account because you impersonated them on GitLab.com
  7. Go to Manage purchases page
  8. Select Change linked namespace button
  9. Select the namespace the subscription should be applied to from the drop-down (the customer should give you this info) If the namespace isn't on the list, it means the user doesn't have owner level permissions on the group they are trying to link. Ask the customer to get themselves added to the group as an owner.
  10. Proceed to checkout if there is no outstanding fee to be paid
  11. You should see the namespace linked to the subscription card
  12. Send the customer a confirmation email, you can use the following snippet:

I have successfully provisioned your subscription and it has been associated with your account and namespace. Please navigate to your group's billing page for confirmation: https://gitlab.com/groups/GROUPNAME/-/billings

If there is an outstanding fee at step 10, go to the admin view > namespaces tab. You should see the namespace and a drop-down for the plans. Select the relevant plan and click the Update button. This should successfully associate the subscription.

Use the Associate namespace transactions issue type in ZD and set the ticket to Pending.

Troubleshooting 502 errors while provisioning the subscrpition

While handling the subscription provisioning requests, we might encounter a 502 error while impersonating the user on the customer portal, this occurs when an admin accidentally links their GitLab.com admin account with the customer portal account, due to which the customer portal tries to fetch all the groups that are accessible to the admin user on GitLab.com and eventually returns a 502 error.

To fix this, we should completely unlink the GitLab.com account with the customer portal account using the unlink_customer console function

Force Associate SaaS Subscription

While handing the subscription provisioning requests, we'll face some cases where it's not possible to associate the subscription by following the normal procedure(the workflow mentioned above) using the customer portal admin

Proceed as follows:

Use the force Associate subscription form - Open this page and enter the Namespace and Subscription ID details and submit the form. This will create an internal issue and updates the issue description with the response of the force association script

Please note: when using the force associate tool, ensure that a gitlab.com user (with owner role in the relevant namespace) has been linked to the customersdot account that the subscription is associated with. If an association is made, but no gitlab.com user is linked, then any subsequent changes to the subscription will either not reflect on the namespace in gitlab.com or it will downgrade the namespace to Free.

Clear Subscription

While associating the subscription with a namespace if there are any errors(example: errors like: unable to associate the subscription as the destination namespace is already associated with a subscription), we can unlink the subscription associated with that namespace.

Clear subscription form is used to clear the subscription associated with that namespace. Please follow the below steps:

Navigate to the Clear subscription form page -> enter the Subscription Name and submit the form. This will create an internal issue and updates the issue description with the response of the force association script


FYI: If interested, you can find more information about the L&R's Mechanizer tools here.

Customer self-serve: associating the subscription and namespace

If the user has access to and sees a subscription in CustomersDot but doesn't see the paid plan details showing on their billing page on GitLab.com, have the user associate the group with the subscription via CustomersDot.

Associating a group with a subscription in CustomersDot:

  1. Log into: https://customers.gitlab.com/customers/sign_in
  2. Navigate to Manage Purchases
  3. Select Change linked namespace
  4. Select the desired group from the namespace dropdown
  5. Check your billing information and proceed with Confirm purchase

Note: if the relevant namespace is greyed out or not on the namespace drop-down list, they should not proceed and they will need assistance from Support to complete the association.

If the user doesn't see a subscription in CustomersDot:

  1. Log into Salesforce using the generic email. Password is stored in 1Password.
  2. Using the global navigation search on the top right, enter the email address associated with the purchase
  3. Select the appropriate account (note that Type = Customer)
  4. Copy the SFDC Account ID from the page's URL to a clipboard note: this is the number appended to end of the URL after gitlab.my.salesforce.com/
  5. From the Quotes related list, select the Quote record with the proper susbcription term and with Status = Sent to Z-Billing
  6. Copy the Zuora Account ID to a clipboard
  7. Log into the CustomersDot using the generic email. Password is stored in 1Password.
  8. Locate the proper account in the CustomersDot and navigate to the Edit page
  9. Enter the Zuora ID and Salesforce Account ID in the fields and select Save
  10. Walk the user through the steps for Associating a group with a subscription noted above
Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license