
CEO & Co-founder of Visivo
How to Track Changes with Pull Requests in Analytics
Apply pull request workflows to analytics for better quality control, collaboration, and change tracking using Visivo's YAML-based configurations.

Pull requests gave software teams a place to review and discuss a change before it ships. Analytics teams can get the same thing by applying PR workflows to dashboards and data transformations. VentureBeat reports that "87% of data science projects never make it to production," and a missing change-management and review process is a common reason.
Because a Visivo project is YAML in a Git repository, the same branch, review, and merge workflow applies to analytics.
The challenge of managing analytics changes
When several analysts edit the same reports at once, work gets overwritten, dashboards break, and metrics change with no record of why. Stakeholders notice, and trust goes with it. Gartner research puts the cost of data quality issues at "an average of $12.9 million annually," and uncontrolled changes to analytics systems are a common source.
Three scenarios most data teams will recognize:
The midnight metric mystery: A revenue dashboard shows different numbers on Monday than it did on Friday. Nobody remembers making a change, but three analysts had access over the weekend. Which edit broke the calculation? Without version control, the team spends hours rebuilding the original logic.
The overwrite incident: Sarah updates the customer segmentation dashboard while Mike edits the same calculations. Sarah's save overwrites a week of Mike's work. Neither notices until stakeholders question the conflicting numbers in Monday's executive meeting.
The production panic: A new dashboard looks perfect in development and breaks in production, because it references tables that do not exist in the live environment. The team finds out during a board presentation.
A pull request puts a review and an approval between a change and production. That is the foundation for reliable BI insights for stakeholders and for managing staging production environments.
Why analytics needs pull request workflows
Traditional BI tools encourage editing directly in production, a practice software teams abandoned decades ago. MIT research found that "Companies using data-driven strategies have 5-6% higher productivity," and that advantage depends on change control that holds up.
When anyone can change a live dashboard instantly, the team loses:
- Change tracking: no record of who changed what, or why
- Review: no quality check before a change goes live
- Testing: no proof that the change works
- Rollback: no easy way to undo a bad change
- Discussion: no written record of why business logic changed
Pull requests restore all five, and treat dashboards and data transformations as the business infrastructure they are.
Applying pull requests to a Visivo project
In a Visivo project, every part of the analytics stack (sources, models with their metrics and dimensions, Insights, charts, and dashboards) is a YAML file under version control. Every change, from a metric formula to a dashboard layout, can go through a PR. This is the practical form of BI version control best practices and developer-first BI workflows.
Creating an analytics PR
A typical workflow for changing a revenue calculation:
# Analyst workflow for revenue calculation update
git checkout -b update/revenue-calculation-refunds
# Edit the Visivo project configuration
vim project.visivo.yml
The analyst modifies the revenue model to subtract refunds:
# project.visivo.yml (after)
name: example_project
models:
- name: monthly_revenue
sql: |
SELECT
DATE_TRUNC('month', o.order_date) AS month,
SUM(o.amount) - COALESCE(SUM(r.refund_amount), 0) AS total_revenue,
COALESCE(SUM(r.refund_amount), 0) AS total_refunds,
COUNT(*) AS order_count
FROM orders o
LEFT JOIN (
SELECT order_id, SUM(amount) AS refund_amount
FROM refunds
GROUP BY order_id
) r ON r.order_id = o.order_id
WHERE o.status = 'completed'
GROUP BY DATE_TRUNC('month', o.order_date)
The analyst tests locally and commits the changes:
# Test the changes locally
visivo serve --port 3000
# Verify the revenue calculation includes refunds
# Check that all dependent dashboards still work
# Commit the tested changes
git add project.visivo.yml
git commit -m "Update revenue calculation to subtract refunds
- Modified monthly_revenue model to join with refunds table
- Added refund_amount subtraction from total_revenue
- Added total_refunds column for transparency
- Tested against Q4 2024 data, matches finance calculations"
git push origin update/revenue-calculation-refunds
PR templates for analytics changes
A good analytics PR explains the business impact, what was tested, and which stakeholders signed off. A template keeps that consistent:
## Analytics Change Request
### ๐ฏ What changed?
- Updated `monthly_revenue` model to subtract refunds from total revenue
- Added `total_refunds` column for refund amount transparency
- Modified revenue calculation logic in all dependent dashboards
### ๐ค Why this change?
Finance team requested alignment with GAAP accounting standards where refunds must be subtracted from gross revenue to calculate net revenue. Current calculation overstates actual revenue by approximately 3%.
### ๐งช Testing Performed
- [x] Validated against Q4 2024 financial statements
- [x] Compared calculations with finance team spreadsheets
- [x] Tested all dependent dashboards render correctly
- [x] Verified historical data consistency back to 2023
- [x] Performance tested on production data volumes
### ๐ Impact Analysis
**Dashboards Affected:**
- Executive Dashboard (main revenue KPI)
- Sales Performance Dashboard (revenue trends)
- Financial Reporting Dashboard (monthly summaries)
**Expected Changes:**
- Executive dashboard revenue will decrease by ~3%
- Historical trends will show more accurate revenue progression
- New refunds metric available for analysis
**Stakeholder Communication:**
- [x] Finance team approved calculation logic
- [x] Executive team notified of upcoming change
- [ ] Sales team briefed on revised numbers
### ๐ฏ Rollback Plan
If issues arise, revert commit `abc123` and redeploy previous version. Original calculation preserved in `monthly_revenue_legacy` model for emergency rollback.
### ๐ธ Screenshots
[Attach before/after dashboard screenshots showing revenue changes]
Advanced PR workflows for Visivo projects
Multi-file analytics changes
Larger changes span several files. A Visivo project can be split across them, with each file pulled into project.visivo.yml through includes, so one PR can carry a commit per concern:
# Complex dashboard redesign affecting multiple files
git checkout -b feature/executive-dashboard-redesign
# Modify data sources
vim config/sources.visivo.yml
# Update data models
vim models/finance.visivo.yml
vim models/operations.visivo.yml
# Create new insights
vim insights/executive-kpis.visivo.yml
# Update dashboard layout
vim dashboards/executive.visivo.yml
# Test the complete changes
visivo serve
# Commit with descriptive organization
git add config/sources.visivo.yml
git commit -m "Add Snowflake data source for executive metrics"
git add models/
git commit -m "Update finance and operations models for KPI calculations"
git add insights/executive-kpis.visivo.yml
git commit -m "Create executive KPI insights with target comparisons"
git add dashboards/executive.visivo.yml
git commit -m "Redesign executive dashboard layout and styling"
git push origin feature/executive-dashboard-redesign
Data quality validation in PRs
A Visivo project can carry its own data quality tests, which is the core of test before dashboard deployment. A test asserts on the data behind an Insight, and visivo test runs every test in the project:
# tests/data-quality.visivo.yml
insights:
- name: monthly-revenue
props:
type: bar
x: ?{ ${ref(monthly_revenue).month} }
y: ?{ ${ref(monthly_revenue).total_revenue} }
- name: monthly-refunds
props:
type: bar
x: ?{ ${ref(monthly_revenue).month} }
y: ?{ ${ref(monthly_revenue).total_refunds} }
tests:
- name: revenue-never-negative
assertions:
- ">{ numpy.min( ${ref(monthly-revenue).props.y} ) >= 0 }"
- name: refunds-never-negative
assertions:
- ">{ numpy.min( ${ref(monthly-refunds).props.y} ) >= 0 }"
- name: at-least-a-year-of-history
assertions:
- ">{ len( ${ref(monthly-revenue).props.x} ) >= 12 }"
Automated testing in CI/CD
GitHub Actions can run those tests on every PR, which is the first step of a CI/CD analytics implementation:
# .github/workflows/test-analytics-changes.yml
name: Test Analytics Changes
on:
pull_request:
paths:
- "**.visivo.yml"
- "models/**"
- "insights/**"
- "dashboards/**"
jobs:
test-visivo-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Visivo CLI
run: pip install visivo
- name: Validate the project
run: visivo compile
- name: Run queries
run: visivo run
- name: Run data quality tests
run: visivo test
- name: Deploy a preview of this branch
run: visivo deploy -s ${{ github.head_ref }}
env:
VISIVO_TOKEN: ${{ secrets.VISIVO_TOKEN }}
Reviewing analytics PRs
Technical review checklist
An analytics PR needs a different checklist than application code:
Data Logic Review:
- [ ] SQL queries use correct joins and aggregations
- [ ] Date logic handles edge cases (month boundaries, timezones)
- [ ] Calculations match business requirements and definitions
- [ ] Edge cases considered (null values, zero amounts, etc.)
Performance Review:
- [ ] Queries will perform acceptably on production data volumes
- [ ] Indexes exist for join and filter columns
- [ ] No unnecessary full table scans
- [ ] Query execution time tested with realistic data
Business Logic Review:
- [ ] Calculations align with business requirements
- [ ] Metric definitions match stakeholder expectations
- [ ] Historical data impact understood and communicated
- [ ] Dependent dashboards won't break
Configuration Review:
- [ ] YAML syntax is valid and follows project conventions
- [ ] References to models, insights, and sources are correct
- [ ] Environment-specific configurations properly separated
- [ ] No hardcoded values that should be parameters
Stakeholder review
Many analytics changes need sign-off from outside the data team. A GitHub CODEOWNERS file requests the right reviewers for each part of the project:
# .github/CODEOWNERS
models/finance.visivo.yml @your-org/finance-analytics
dashboards/executive.visivo.yml @your-org/data-leads
Handling emergencies without skipping the PR
Even with careful review, a production dashboard sometimes needs a fix in the next ten minutes. Because the project is in Git, the fix can be fast and still leave an audit trail:
Emergency hotfix
# Production dashboard showing incorrect numbers
# Need immediate fix during business hours
# Create emergency hotfix branch
git checkout main
git checkout -b hotfix/revenue-calculation-fix
# Make minimal fix to resolve immediate issue
vim project.visivo.yml
# Fix the specific calculation error
# Test quickly but thoroughly
visivo run
visivo test
# Commit with clear emergency context
git commit -m "HOTFIX: Correct revenue calculation error
Critical fix for production dashboard showing 10x inflated revenue.
Error: missing WHERE clause filter for completed orders only.
Tested: confirms numbers match finance reports.
Requires: immediate deployment to fix executive dashboard."
# Create emergency PR with fast-track review
git push origin hotfix/revenue-calculation-fix
gh pr create --title "HOTFIX: Revenue calculation error" --body "Emergency fix for production issue. Requires immediate review and deployment."
# Deploy immediately after minimal review
visivo deploy -s production
After the emergency
Once the fix is live, write the retrospective while the details are fresh:
## Emergency Response Retrospective
### Incident Summary
Production revenue dashboard showed 10x inflated numbers due to missing WHERE clause filter for completed orders only.
### Root Cause
Developer removed WHERE clause during optimization but didn't notice impact on revenue calculation logic.
### Response Timeline
- 10:15 AM: Issue reported by CFO
- 10:20 AM: Data team identified root cause
- 10:25 AM: Emergency fix committed
- 10:30 AM: Fix deployed to production
- 10:35 AM: Dashboard confirmed accurate
### Process Improvements
1. Add automated test for revenue calculation accuracy
2. Require finance team review for any revenue-related changes
3. Add production monitoring alerts for metric anomalies
4. Create emergency response runbook for similar issues
What PR-based analytics gets you
PR workflows with Visivo improve analytics reliability and team collaboration. That matters because Forrester research found that between 60% and 73% of enterprise data goes unused for analytics, often because nobody trusts its quality.
Quality and reliability
Reviews catch mistakes before deployment, so fewer broken dashboards, wrong metrics, and emergency hotfixes reach production. With CI in the loop, 100% of changes are tested before deployment, with automated validation of data quality and business logic and performance testing with production-scale data.
Collaboration and knowledge sharing
PR discussions record why each change was made and who agreed to it. New team members read that history and learn the business logic, the conventions, and the requirements behind each dashboard without having to ask.
Compliance and auditability
Every change records who made it, when, why, what was tested, and who approved it. For financial reporting, that is the audit trail: documented changes, approval workflows for sensitive metrics, rollback for mistakes, and the ability to reconstruct the project at any point in time.
Getting started with analytics pull requests
Phase 1: basic Git workflow (week 1-2)
Start with plain version control:
- Initialize Git repository for your Visivo project
- Commit existing dashboards to establish baseline
- Create feature branches for all new changes
- Require PRs for merging to main branch
# Initialize Git workflow for existing Visivo project
cd your-analytics-project
git init
git add project.visivo.yml dashboards/ models/ insights/
git commit -m "Initial commit: existing Visivo analytics configuration"
# Set up main branch protection
git push origin main
# Configure GitHub to require PRs for main branch
Phase 2: review process (week 3-4)
Add review requirements:
- Create PR templates for analytics changes
- Establish review criteria and checklists
- Train team members on review best practices
- Set up CODEOWNERS for stakeholder approval
Phase 3: automated testing (week 5-8)
Automate validation:
- Add data quality tests to Visivo project
- Set up CI/CD pipeline with GitHub Actions
- Configure preview deployments for PR testing
- Add performance and regression testing
Phase 4: advanced workflows (week 9-12)
Round out the process:
- Implement emergency hotfix procedures
- Add monitoring and alerting for deployed changes
- Create automated rollback capabilities
- Establish retrospective processes for continuous improvement
Conclusion
Pull requests turn analytics from a pile of individual edits into a reviewed, tested engineering discipline. Because a Visivo project is YAML in Git, nothing about the workflow is new: branch, open a PR, review, test, merge.
The payoff shows up quickly:
- Fewer errors reach production
- Analysts and stakeholders discuss a change before it ships, not after
- Every change has an audit trail for compliance and debugging
- Problems are found and reverted faster
- The PR history teaches the next hire how the metrics work
Teams that hold their analytics to the same standard as their application code find that reliable dashboards follow. Pull requests do not slow analytics down. They remove the rework that uncontrolled changes create.
For related reading, see dashboard version control collaboration, faster feedback cycles, and visualizations as code.
If you want to try this on a real project, /get-started takes you from install to a running dashboard in a few minutes. Put that project in Git, and the first PR is the next step.