Manage Staging Release Validation¶
Use this runbook after the BetterFleet Manage release branch has been deployed to staging and before the production promotion decision.
The goal is to prove two things:
- every shipped merge request has been validated in staging through the normal MR label process
- the staged release candidate is operational as a whole
This is not a full regression pass. Feature-specific acceptance checks remain owned by the merge requests that introduced those changes.
When To Run¶
Run this between the staging deployment and the production release decision for each weekly Manage release candidate.
Run it again if a material hotfix or release-branch change is deployed into staging after the first validation pass.
Record The Validation¶
Create one Linear execution-only issue for the release, using Kind: validation.
The issue is the per-release execution record. Copy the checklist from
Linear Issue Template into the issue body so the
release keeps an exact record of what was checked that week.
GitLab remains the source for merge request labels, pipelines, deployments, and environment evidence. Linear records the operator-facing checklist, owner, notes, exceptions, and final staging outcome.
Suggested title:
Gate 1: MR Staging Validation¶
Open the staging validation query and confirm there are no unresolved merge
requests missing the Validated in Staging label:
Merged staging MRs missing Validated in Staging
If the query is not empty, do not treat staging as release-ready until each remaining merge request is either:
- validated and labelled
- explicitly excluded from the release decision with a short reason
- blocked and tracked as a release blocker
Gate 2: Deployment Identity¶
Confirm staging is running the intended release candidate:
- the staging deploy pipeline passed
- the relevant downstream deployment jobs completed successfully
manage-staging.betterfleet.comloads- the deployed build, commit, or release branch matches the intended release
- backend/API health checks pass
- database migrations completed successfully, if applicable
Gate 3: Core Manage Smoke¶
Run the smoke checks against a dedicated smoke-test workspace and depot. Do not use customer data, and do not use workspaces reserved for depot simulation unless the release owner has explicitly approved it.
These checks prove the critical operational capabilities, not just whether pages
render. A check only passes when the page loads, the data is meaningful for the
selected staging depot, and there is no visible application error, empty state
that should not be empty, undefined value, stale timestamp, or obviously
incorrect unit.
Minimum checks:
- login succeeds for a normal admin user
- region, workspace, and depot selection work
- Overview loads real operational data for the selected depot
- Incidents list and incident detail load, with status and timestamp fields populated where incidents exist
- Chargers list and charger detail load, with each sampled charger showing a
coherent operational state, connectors, last-known communication/status data,
and no unexpected
undefined, blank, or impossible values - Vehicles list and vehicle detail load
- Load management is meaningful:
- the Load or Power page loads for the selected depot
- charts render with labelled axes, values, and a sensible time range
- site/depot load, capacity, allocation, or limit values are present where the selected depot is configured for load management
- charger allocation or constraint values are internally consistent, with no negative, over-capacity, missing, or obviously stale values unless recorded as expected for the staging dataset
- any active limit, circuit, or fail-safe state visible in the UI matches the expected staging scenario or is explicitly recorded as not applicable
- Settings loads
- one safe smoke-only setting can be changed and reverted, if a safe setting is available
- one representative report loads
- one representative report export or download works
- release notes or help page loads
- logout works
If a smoke check is not applicable for the staging dataset, mark it as not applicable in the Linear issue and explain why.
Gate 4: Release-Specific Add-Ons¶
Only run deeper checks for areas touched by the release candidate. Use the MR list, release notes, feature flags, and known release risk to decide which add-ons apply.
Common add-ons:
- Auth or SSO changes: validate the affected login path, region selection, and error state.
- Permission changes: validate the affected role or access boundary with the relevant user type.
- Feature flag changes: confirm the intended GitLab feature-flag stage and audience.
- Load management changes: run the core load-management smoke plus one focused check for the changed circuit, charger, fail-safe, limit, or allocation behavior.
- Roaming changes: validate the affected access, group, tariff, or session path.
- Reports changes: validate the affected report table and export.
- Migration or data-shape changes: confirm the migration completed and existing staging data still renders in the affected surface.
Record each add-on as completed, not required, or blocked in the Linear issue.
Gate 5: Monitoring¶
After the smoke pass, check for obvious staging health regressions:
- no obvious new Sentry spike for the staging environment
- no obvious backend error/log spike
- no repeated frontend runtime error on core pages
- any known warnings are recorded and accepted
If monitoring is noisy, record the specific signal checked and the reason it was accepted or escalated.
Outcome¶
Staging is ready for production promotion only when:
- the MR staging validation query is empty or fully triaged
- deployment identity is confirmed
- core Manage smoke passes
- required release-specific add-ons pass
- monitoring shows no obvious new release-blocking issue
- failures, exceptions, and accepted gaps are recorded in the Linear issue
If any gate fails, do not proceed to production promotion. Record the blocker in the Linear issue and link the relevant GitLab merge request, pipeline, incident, or follow-up issue.
Linear Issue Template¶
Copy this template into the per-release Linear validation issue.
## Staging Release Validation
Release: 2026.xx
Environment: https://manage-staging.betterfleet.com
Release owner:
Validation date:
Runbook: docs/operations/runbooks/manage-staging-release-validation.md
## Gate 1: MR Staging Validation
- [ ] GitLab query has no unresolved MRs missing `Validated in Staging`
- [ ] Any remaining MRs are explicitly excluded, blocked, or labelled with a note
## Gate 2: Deployment Identity
- [ ] Staging deploy pipeline passed
- [ ] Relevant downstream deployment jobs completed successfully
- [ ] `manage-staging.betterfleet.com` loads
- [ ] Staging is running the intended release branch/build
- [ ] Backend/API health checks pass
- [ ] Database migrations completed successfully, if applicable
## Gate 3: Core Manage Smoke
- [ ] Login succeeds for a normal admin user
- [ ] Region/workspace/depot selection works
- [ ] Overview loads real operational data for the selected depot
- [ ] Incidents list and incident detail load, with status/timestamp fields populated where incidents exist
- [ ] Chargers list and charger detail load, with sampled chargers showing coherent operational state, connector data, and last-known communication/status data
- [ ] Sampled charger values contain no unexpected `undefined`, blank, stale, or impossible operational values
- [ ] Vehicles list and vehicle detail load
- [ ] Load/Power page loads for the selected depot
- [ ] Load/Power charts render with labelled axes, values, and a sensible time range
- [ ] Site/depot load, capacity, allocation, or limit values are present where the depot is configured for load management
- [ ] Charger allocation or constraint values are internally consistent, with no negative, over-capacity, missing, or obviously stale values unless recorded as expected
- [ ] Active limit, circuit, or fail-safe state visible in the UI matches the expected staging scenario or is explicitly recorded as not applicable
- [ ] Settings page loads
- [ ] One safe smoke-only setting can be changed and reverted, or marked not applicable
- [ ] One representative report loads
- [ ] One representative report export/download works
- [ ] Release notes/help page loads
- [ ] Logout works
## Gate 4: Release-Specific Add-Ons
- [ ] Auth/SSO checks completed or not required
- [ ] Permission/role checks completed or not required
- [ ] Feature flag rollout checks completed or not required
- [ ] Load management checks completed or not required
- [ ] Roaming checks completed or not required
- [ ] Reports/export checks completed or not required
- [ ] Migration/data checks completed or not required
## Gate 5: Monitoring
- [ ] No obvious new staging Sentry spike
- [ ] No obvious backend error/log spike
- [ ] No repeated frontend runtime error on core pages
- [ ] Known warnings are recorded and accepted
## Outcome
- [ ] Staging release candidate is ready for production promotion
- [ ] Blocked: issue(s) recorded below
Validated by:
Date/time:
Workspace/depot used:
Pipeline/deployment links:
Notes: