Downtime Credits - Sagai

module-name: "downtime-credits"
maintainers:
  - ffarukh

Overview

Some customers have guaranteed SLAs as part of their GitLab contracts. As part of that, customers can request credits when we are in breach of the contract-defined SLA. Customers need to reach out to support to request downtime credits, and support needs to be able to validate their claim as well as answer any questions the customer may have or request help from Engineering on validation outcome. The validated claims are then moved to and processed in batch by the Billing team at the end of every month.

This training module covers the workflow for processing customer requests for credits due to GitLab.com and GitLab Dedicated downtime. Credits are available to eligible customers when monthly uptime threshold (generally, 99.9%)

Goal: Understand and feel proficient to work on the Downtime credits requests from customers.

Important: This workflow applies only to Ultimate GitLab.com or GitLab Dedicated customers. Self-Managed customers are not eligible. Some Premium customers have SLA in their contracts which will be noted in the Zendesk Org notes.

Length: 1-2 hours

Objectives: By the end of this training, you should be able to:

  1. Understand the role of Support in the downtime credits workflow
  2. Identify eligible customers for downtime credits
  3. Validate downtime credit claims using monitoring data
  4. Handle edge cases and escalations appropriately

Stage 0: Create Your Module

  1. Create an issue using this template by making the Issue Title: Downtime Credits - <your name>.
  2. Add yourself and your trainer (if applicable) as the assignees.
  3. Set milestones, if applicable, and a due date to help motivate yourself!

Stage 1: Important Definitions

  1. Read the Downtime definition for our SLA.
  2. Take note of the features and services covered by our SLA:
  3. Understand SLA Coverage:
    • SLA explicitly covers failing requests (5xx errors)
    • Some outages may NOT be captured: application bugs without 5xx errors, Sidekiq outages, infrastructure issues affecting user experience
    • If customer describes such issues, escalate to Engineering via RFH
  4. Review Eligibility Requirements for downtime credits request - the customer must meet ALL of the following:
    • New or renewed Ultimate subscription with start date after 2025-12-01 on GitLab.com or GitLab Dedicated, OR the Zendesk Org Notes indicates This customer has a signed SaaS Addendum which includes provisions surrounding: Downtime credits.
    • Submits claim within 30 days after affected month ends
    • No previous claim for the same month
    • Monthly uptime below 99.9%
  5. Review Processing Timeline:
    • Support validation: Within 1 business day
    • Billing calculation: Within 3 business days
    • Credit application: Monthly batch (first week of following month)
    • Total timeline: Up to 60 days

Stage 2: Ticket Submissions

  1. Review this test ticket in Zendesk Sandbox to see the ticket structure.
    • Take note of the Uptime claim - month, Uptime claim - product, and Namespace fields on the left side. You will need this data to validate the credit claim.
  2. Understand that customers submit requests for downtime credits via the Downtime Credit Request Zendesk form
  3. Note: One month per ticket - if a customer claims credits for multiple months in one ticket, request the customer to create separate tickets for each month.
  4. The SLA to validate the claims for downtime credits is 24 hours.
  5. Optional: Create a personal Zendesk view to quickly spot the Downtime Credit Request tickets.

Stage 3: Validation Steps

  1. Read the validation workflow steps in order:
    • Duplicate Check: Search for existing tickets from same customer for same month
    • Timing Validation: Confirm the ticket has been opened within 30-day window after the end of the claimed month
    • Subscription Eligibility:
    • Verify it is a GitLab.com or GitLab Dedicated customer.
    • Verify Ultimate subscription with start date after 2025-12-01.
    • If it is a Premium customer, verify they have an exception noted in their org notes. The Org note would state This customer has a signed SaaS Addendum which includes provisions surrounding: Downtime credits.
  2. Review the Support::Downtime Credits::Claim Rejected macro for failed validation. You are required to edit the macro and leave the appropriate reason for rejection only.
  3. Monitoring Data Retrieval: Watch the demo video on retrieving uptime data
  4. Practice: Open the calculation spreadsheet
  5. Make a copy to the Downtime credits spreadsheets folder and set the title as GitLab-2025-06-<YourName> as the title
  6. Try the validation steps using gitlab-com namespace and 2025-06 (June 2025) in the spreadsheet
  7. Refresh the data. If you don't have access, ping @ffarukh or @reprazent in a comment in this issue to assist
  8. Check the outcome and note the uptime percentage
  9. Threshold Check: If the uptime percentage is < 99.9%, the claim is validated and passed to Billing. Otherwise, the claim is refused. NOTE: The customer can dispute this outcome which will then follow the RFH escalation process.
  10. Delete the spreadsheet you created above with the title GitLab-2025-06-<YourName>
  11. NOTE: DO NOT delete the spreadsheet created for a customer ticket. The spreadsheet for a customer claim should be left intact with the data and uptime calculation in case it will be needed for future reference.

Stage 4: Escalation Paths

  1. Review the RFH templates: one for GitLab.com and one for GitLab Dedicated
    • GitLab.com: Observability team RFH
    • GitLab Dedicated: Environment Automation team RFH
  2. Take note of the following situations that may need us to escalate to Engineering via RFH:
    • Customer disputes the validation outcome
    • Monitoring data is missing or incomplete
    • Customer describes issues not captured by monitoring (Sidekiq failures, application bugs without 5xx errors)
    • Customer has questions you can't answer
    • Need to verify if an incident counts as downtime

Stage 5: Passing to Billing

  1. Read Step 3 of the workflow
  2. Understand the process:
    • Use Support::Downtime Credits::Claim Validated macro to notify customer
    • Use General::Forms::Incorrect form used macro
    • Delete the contents of the incorrect form macro
    • Use Support::Downtime Credits::Pass to Billing macro to add internal note with:
      • Customer name
      • Monthly Uptime percentage
      • Namespace Path or Instance URL
      • Month (YYYY-MM)
      • Link to uptime spreadsheet copy
    • Submit as Open
  3. Review the macros used in the workflow:
    • Support::Downtime Credits::Claim Validated - for passed validation
    • Support::Downtime Credits::Pass to Billing - internal note for Billing team with validation details

Stage 6: Get an Overview of Billing's Role

Note

This section is only for information purposes. The billing workflow is owned by Billing and subject to change. Refer back to the billing workflow in case of any questions (TODO).

  1. Review Billing's responsibilities:
    • Calculate credit amount based on subscription fee and uptime percentage
    • Notify customer with Amount Calculated macro
    • Add tag: credit_claim_billing_reviewed
    • Monthly batch processing of credits
    • Send final confirmation and solve ticket

Stage 7: FAQs

  1. Review the flowchart to get an overview and summary of the workflow
  2. Read the FAQs in the workflow
  3. Key points to remember:
    • This workflow DOES NOT cover CI/CD minutes overusage issues because long running jobs would not affect availability.
    • Claims for a month are processed only after the month ends because the required data is only available after the calendar month ends.
    • Separate tickets are required for multiple months, we process one month per ticket.
    • Engineering's monitoring data is authoritative but use RFH in case of any disputes.
  4. Ask any questions in #3x9s-availability Slack channel

Stage 8: Contribute

  1. Manager: schedule a call (or integrate into 1:1) to review how the module went once you have reviewed this issue.
  2. Submit MRs to improve the Downtime Credits Workflow based on your experience
  3. Submit an MR for this Issue Template with any improvements that you have noticed.
Edited by Sagai Taylor