Author Image

CTO & Co-founder of Visivo

Dashboard Version Control to Improve BI Collaboration

Implement version control for dashboards to enable seamless team collaboration, change tracking, and rollback capabilities.

Dashboard version control system

Dashboards built in a GUI are a solo activity: one person edits, everyone else waits. Version control makes them a team activity. The GitLab DevSecOps report shows that version control adoption increases team productivity by 40%, and MIT research finds that "Companies using data-driven strategies have 5-6% higher productivity" when they implement systematic collaboration practices.

Treat dashboards as code and put them in Git, and the team can work in parallel, review each change and keep a full history. In Visivo, every dashboard, chart and model is YAML, so the workflow your engineers already use applies to analytics without anything new to learn.

Why dashboard version control matters

In a traditional BI tool, one person edits a dashboard while others wait. Changes overwrite each other. Previous versions disappear. Mistakes cannot be undone. Teams duplicate effort and drift apart.

Gartner analyst Nick Heudecker put the failure rate of big data projects at 85%, and VentureBeat reports that "87% of data science projects never make it to production." Collaboration problems are a common cause in both.

Visivo removes the root cause by making every part of the project a text file:

  • Dashboard layouts become YAML configurations
  • Chart definitions become explicit Insight specifications
  • Data transformations become documented SQL models
  • Dependencies become explicit ${ref()} relationships

When everything is code, everything gets a diff, a review and a history. That matters because Gartner puts the cost of data quality issues at "an average of $12.9 million annually," and uncontrolled, unreviewed changes are a large part of that.

The Git reference at git-scm.com covers the mechanics. For the practices that matter in BI, see BI version control best practices.

Implementing dashboard version control with Visivo

Project structure for collaboration

Split the project into files by object type, so two people rarely edit the same one:

# Team-friendly project structure
analytics-project/
├── project.visivo.yml          # Main project configuration
├── sources/
│   ├── production.visivo.yml   # Production data sources
│   └── staging.visivo.yml      # Development data sources
├── models/                     # Models, metrics, dimensions, relations
│   ├── orders.visivo.yml
│   ├── customers.visivo.yml
│   └── revenue_analysis.visivo.yml
├── insights/
│   ├── revenue_insights.visivo.yml
│   ├── customer_insights.visivo.yml
│   └── product_insights.visivo.yml
└── dashboards/
    ├── executive.visivo.yml
    ├── sales.visivo.yml
    └── operations.visivo.yml

Initial repository setup

# project.visivo.yml - Main configuration
name: Company Analytics

defaults:
  source_name: postgres

includes:
  - path: sources/
  - path: models/
  - path: insights/
  - path: dashboards/

Keep build output and secrets out of Git:

# .gitignore
.env
*.db
__pycache__/
target/
node_modules/

Version controlled dashboard configuration

A complete dashboard, as it lives in the repository:

# dashboards/sales.visivo.yml
dashboards:
  - name: Sales Performance Dashboard
    description: "Revenue, conversion, and team performance metrics"
    rows:
      # Header with key metrics
      - height: small
        items:
          - width: 1
            chart:
              insights:
                - ${ref(monthly-revenue-kpi)}
              layout:
                title:
                  text: "Monthly Revenue"
          - width: 1
            chart:
              insights:
                - ${ref(conversion-rate-kpi)}
              layout:
                title:
                  text: "Conversion Rate"
          - width: 1
            chart:
              insights:
                - ${ref(new-customers-kpi)}
              layout:
                title:
                  text: "New Customers"

      # Main analysis charts
      - height: large
        items:
          - width: 2
            chart:
              insights:
                - ${ref(revenue-trend)}
                - ${ref(revenue-forecast)}
              layout:
                title:
                  text: "Revenue Trend & Forecast"
                showlegend: true
          - width: 1
            chart:
              insights:
                - ${ref(top-products)}
              layout:
                title:
                  text: "Top Products"

      # Detailed breakdown
      - height: medium
        items:
          - width: 3
            table:
              name: sales-detail-table
              columns:
                - ${ref(sales_detail).order_date} as Date
                - ${ref(sales_detail).product_name} as Product
                - ${ref(sales_detail).revenue} as Revenue
                - ${ref(sales_detail).units_sold} as Units

# Associated insights in insights/revenue_insights.visivo.yml
insights:
  - name: monthly-revenue-kpi
    props:
      type: indicator
      mode: number+delta
      value: ?{ ${ref(monthly_kpis).current_month} }[0]
      delta:
        reference: ?{ ${ref(monthly_kpis).previous_month} }[0]
        relative: true
      number:
        prefix: "$"
        font:
          size: 24
    interactions:
      - filter: ?{ ${ref(monthly_kpis).metric_name} = 'revenue' }

  - name: revenue-trend
    props:
      type: scatter
      mode: lines+markers
      x: ?{ ${ref(monthly_revenue).month} }
      y: ?{ ${ref(monthly_revenue).revenue} }
      name: "Actual Revenue"
      line:
        color: "#2E86C1"
        width: 3

  - name: revenue-forecast
    props:
      type: scatter
      mode: lines
      x: ?{ ${ref(revenue_forecast_model).month} }
      y: ?{ ${ref(revenue_forecast_model).forecasted_revenue} }
      name: "Forecast"
      line:
        color: "#E74C3C"
        dash: "dash"
        width: 2

Every row, chart and column is text, so every change to it is a diff.

Team collaboration workflows

Branch-based development

Three people, three branches, no waiting:

# Feature branching for analytics development
git checkout main
git pull origin main

# Alice works on new customer segmentation
git checkout -b feature/customer-segmentation
# Edit models/customers.visivo.yml
# Edit insights/customer_insights.visivo.yml
# Edit dashboards/customer_analytics.visivo.yml

# Bob fixes revenue calculation bug
git checkout -b fix/revenue-calculation-bug
# Edit models/revenue_analysis.visivo.yml
# Update insights that use the model

# Carol adds forecasting capabilities
git checkout -b feature/add-forecasting
# Create models/revenue_forecast.visivo.yml
# Add new insights and charts
# Update executive dashboard

# Development and testing
visivo serve
# Test changes locally before committing

Pull request workflow for analytics

A pull request gives analytics the same review step as application code. We go into the practice in track changes with pull requests:

# Example: Revenue calculation fix PR
# Files changed:
# - models/revenue_analysis.visivo.yml
# - tests/revenue_tests.visivo.yml

# models/revenue_analysis.visivo.yml
# Previous version (problems with refunds):
models:
  - name: revenue_analysis
    sql: SELECT order_date, order_amount, refund_date FROM orders
    metrics:
      - name: revenue
        expression: "SUM(order_amount)" # Bug: includes refunded orders

The fixed version:

# models/revenue_analysis.visivo.yml
models:
  - name: revenue_analysis
    sql: SELECT order_date, order_amount, refund_date FROM orders
    metrics:
      - name: revenue
        # Fixed: excludes refunded orders
        expression: "SUM(CASE WHEN refund_date IS NULL THEN order_amount ELSE 0 END)"

The pull request description:

Fix revenue calculation to exclude refunded orders

Problem: Current revenue calculation includes orders that were later refunded
Solution: Add CASE statement to exclude refunded orders

Impact: Will reduce reported revenue by ~2-3% (expected)
Testing: Added Visivo tests for refund scenarios

Handling merge conflicts in analytics

When two branches touch the same dashboard, the conflict is readable YAML:

# Conflict in dashboards/executive.visivo.yml
dashboards:
  - name: Executive Dashboard
    rows:
      - height: small
        items:
<<<<<<< HEAD (main)
          - width: 1
            chart:
              insights:
                - ${ref(quarterly-revenue)}
              layout:
                title:
                  text: "Quarterly Revenue"
=======
          - width: 1
            chart:
              insights:
                - ${ref(monthly-revenue)}
              layout:
                title:
                  text: "Monthly Revenue"
>>>>>>> feature/monthly-reporting

# Resolution discussion:
# Team decides monthly reporting provides better granularity
# Final resolution:
          - width: 1
            chart:
              insights:
                - ${ref(monthly-revenue)}
              layout:
                title:
                  text: "Monthly Revenue"

Code review best practices for analytics

An analytics review checks three things:

  1. Data Logic Validation:
name: visivo_project
# Reviewer checklist:
# ✓ SQL logic is correct
# ✓ Joins are appropriate (INNER vs LEFT)
# ✓ Filters make business sense
# ✓ Aggregations are accurate
# ✓ Date ranges are appropriate
  1. Performance Considerations:
name: visivo_project
# Review for efficiency:
# ✓ Indexes are being used
# ✓ Unnecessary computations are avoided
# ✓ Large table scans are minimized
# ✓ Complex queries are documented
  1. Visualization Appropriateness:
name: chart_example
# Chart type matches data:
# ✓ Line charts for trends
# ✓ Bar charts for categories
# ✓ Scatter plots for correlations
# ✓ KPIs for single metrics

Advanced collaboration patterns

Environment-specific configurations

Developers need a database to work against that is not production. Define both sources and choose one when you start the server, following managing staging and production environments:

name: example_project

defaults:
  source_name: production_warehouse

sources:
  - name: production_warehouse
    type: postgresql
    database: analytics
    host: ${env.PROD_DB_HOST}
    username: ${env.PROD_DB_USER}
    password: ${env.PROD_DB_PASSWORD}

  - name: dev_warehouse
    type: postgresql
    database: analytics_dev
    host: ${env.DEV_DB_HOST}
    username: ${env.DEV_DB_USER}
    password: ${env.DEV_DB_PASSWORD}

Each developer keeps credentials in a local .env file. To work against the development database, override the default source when you start the server:

visivo serve -s dev_warehouse

Component libraries and reusability

Shared models and Insights live in one file that several dashboards reference. This is the same idea behind visualizations as code and customizable embedded analytics:

name: example_project

models:
  - name: example_model
    sql: SELECT * FROM example_table

insights:
  - name: revenue_kpi_template
    props:
      type: scatter
      x: ?{ ${ref(example_model).date_column} }
      y: ?{ ${ref(example_model).value_column} }

charts:
  - name: example_chart
    insights:
      - ${ref(revenue_kpi_template)}

dashboards:
  - name: executive_dashboard
    rows:
      - height: medium
        items:
          - chart: ${ref(example_chart)}

Documentation as code

Documentation lives next to the thing it documents, which is how it stays true and how you deliver reliable BI insights for stakeholders:

# Add documentation directly in configurations
# Customer Lifetime Value calculation based on:
# - Historical purchase behavior (24 months)
# - Average order frequency
# - Predicted churn probability
#
# Used by:
# - Executive dashboard (CLV KPI)
# - Customer segmentation analysis
# - Marketing campaign targeting
#
# Maintained by: Data Engineering Team
models:
  - name: customer_lifetime_value
    sql: |
      -- CLV = (AOV * Purchase Frequency * Gross Margin) / Churn Rate
      SELECT
        customer_id,
        (avg_order_value * purchase_frequency * 0.3) / churn_probability as clv,
        last_updated
      FROM customer_base_metrics
      WHERE customer_tenure_months >= 6
    metrics:
      - name: average_clv
        expression: "AVG(clv)"
        description: "Average projected lifetime value of customers with 6+ months of tenure"

Benefits of version-controlled analytics

Elimination of development conflicts

Before (Traditional BI):

  • Alice overwrites Bob's dashboard changes
  • Carol can't work while Dave is editing
  • Changes are lost without backups
  • No way to see what changed

After (Visivo + Git):

  • Parallel development without conflicts
  • Complete change history
  • Easy rollback of problematic changes
  • Transparent change tracking

Knowledge sharing and learning

The commit log explains why a model looks the way it does:

# Learning from commit history
git log --oneline models/revenue_analysis.visivo.yml

# Example output:
a1b2c3d Fix quarterly revenue aggregation logic
d4e5f6g Add seasonal adjustment for retail metrics
g7h8i9j Optimize query performance for large datasets
j1k2l3m Initial revenue analysis model

# See specific changes:
git show d4e5f6g
# Shows exactly what seasonal adjustment logic was added

Audit trail and compliance

Every change is tracked with:

  • Who made the change (Git author)
  • When it was made (Git timestamp)
  • What was changed (Git diff)
  • Why it was changed (Commit message)
# Compliance audit queries
git log --author="alice@company.com" --since="2024-01-01"
git log --grep="revenue" --since="2024-Q4"
git blame models/customers.visivo.yml  # See who wrote each line

Rollback and recovery

A bad change is one command from gone:

# Rollback problematic changes
git revert abc123  # Undo specific commit
git reset --hard HEAD~1  # Undo last commit
git checkout main -- models/broken_model.visivo.yml  # Reset single file

# Deploy previous version
git checkout v1.2.3
visivo run
visivo deploy --stage production

Example: three analysts on one dashboard

Here is how three analysts might build a quarterly business review dashboard over four weeks:

# Week 1: Foundation (Alice)
git checkout -b feature/qbr-dashboard
# Create base models and KPIs
visivo serve  # Test locally
git commit -m "Add base QBR models and KPIs"

# Week 2: Visualizations (Bob)
git checkout feature/qbr-dashboard
git pull origin feature/qbr-dashboard
# Add charts and insights
visivo serve  # Test combined work
git commit -m "Add QBR charts and visualizations"

# Week 3: Polish (Carol)
git checkout feature/qbr-dashboard
git pull origin feature/qbr-dashboard
# Add formatting, filters, and layout improvements
visivo serve  # Final testing
git commit -m "Polish QBR dashboard layout and formatting"

# Week 4: Review and Deploy
git push origin feature/qbr-dashboard
# Create pull request
# Team reviews changes
# Merge to main
visivo run
visivo deploy --stage production

Getting started with analytics version control

Step 1: Initialize Git repository

# Set up version control for existing Visivo project
cd analytics-project
git init
git add .
git commit -m "Initial analytics project"

# Add remote repository
git remote add origin https://github.com/company/analytics.git
git push -u origin main

Step 2: Establish team workflow

# Create team branches
git checkout -b development
git push -u origin development

# Set up protection rules (GitHub/GitLab)
# - Require pull request reviews
# - Require status checks (visivo compile and visivo test)
# - Restrict direct pushes to main

Step 3: CI/CD integration

# .github/workflows/analytics.yml
name: Analytics CI/CD
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Visivo
        run: pip install visivo
      - name: Validate Configuration
        run: visivo compile
      - name: Run Queries
        run: visivo run
        env:
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
      - name: Run Tests
        run: visivo test

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Visivo
        run: pip install visivo
      - name: Run Queries
        run: visivo run
        env:
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
      - name: Deploy to Production
        run: visivo deploy --stage production
        env:
          VISIVO_TOKEN: ${{ secrets.VISIVO_TOKEN }}

Version control turns dashboard development from a solo, error-prone process into one a team can run. Because a Visivo project is text, nothing new is needed: branches, pull requests, CI and rollback all work the way they do for the rest of your code.

Related reading: developer-first BI workflows, faster feedback cycles, and CI/CD analytics implementation.

If your dashboards are not in Git yet, the fastest way to feel the difference is to put one there. /get-started takes you from install to a project you can commit.

Install command copied