Author Image

CTO & Co-founder of Visivo

BI Version Control Best Practices for Reliable Dashboards

Master version control best practices for BI to ensure reliable dashboards through proper Git workflows, code reviews, and change tracking.

Version control workflow for BI

Version control turns business intelligence from an undocumented pile of dashboards into a system with a history. The GitLab DevSecOps report shows that version control adoption increases team productivity by 40%. But putting files in Git is not enough. The gains come from the practices around it, the ones that make every change tracked, reviewed and reversible. Those practices are what separate teams that ship analytics from teams that spend the week fighting fires.

Why BI needs version control

Without version control, BI teams operate in the dark. Who changed that calculation? When did this dashboard break? How do we restore the working version? According to Gartner analyst Nick Heudecker, 85% of big data projects fail, often for exactly these reasons. Questions nobody can answer turn into finger-pointing, lost time and less trust in the numbers.

Version control answers them:

  • Every change is tracked with who, what, when, and why
  • Previous versions can be restored instantly
  • Multiple team members can work without conflicts
  • Changes undergo review before affecting users

Teams without version control spend their time investigating issues and recovering from mistakes. Teams with it spend that time building. The DORA State of DevOps Report found that elite performers deploy 208x more frequently than low performers with better reliability.

Practices that hold up

Keep every BI artifact in Git. Dashboards, queries, metric definitions, tests and docs all belong in the repository. The Git reference lives at git-scm.com. A layout that works:

# Complete BI repository structure
analytics/
├── dashboards/
│   ├── executive/
│   │   ├── revenue-overview.yml
│   │   └── kpi-summary.yml
│   ├── operational/
│   │   ├── daily-metrics.yml
│   │   └── alerts-dashboard.yml
│   └── README.md
├── queries/
│   ├── shared/
│   │   ├── customer-segments.sql
│   │   └── revenue-calculations.sql
│   └── optimized/
│       └── materialized-views.sql
├── metrics/
│   ├── definitions.yml
│   └── calculations.yml
├── tests/
│   ├── data-quality/
│   └── dashboard-validation/
├── docs/
│   ├── onboarding.md
│   └── metrics-glossary.md
└── .gitignore

Never store these in Git:

# .gitignore for BI projects
# Credentials and secrets
*.env
config/secrets.yml
credentials/

# Generated files (visivo run writes to target/, visivo dist to dist/)
*.cache
target/
dist/

# Large data files
*.csv
*.parquet
data/

# Personal IDE settings
.vscode/
.idea/

Name branches for what they change. A branch name should tell a reviewer what to expect before they open the diff:

# Good branch names
feature/add-customer-retention-dashboard
fix/revenue-calculation-error
refactor/consolidate-date-filters
test/performance-improvements
docs/update-metric-definitions

# Bad branch names
johns-branch
dashboard-update
fix
new-stuff
test123

Protect the branches that deploy:

# Branch protection settings (configure these in your Git host)
protection_rules:
  main:
    required_reviews: 2
    dismiss_stale_reviews: true
    require_up_to_date: true
    required_status_checks:
      - ci/build
      - ci/test
      - ci/security-scan

  develop:
    required_reviews: 1
    required_status_checks:
      - ci/build
      - ci/test

Write commit messages that explain why. Six months from now the diff shows what changed. Only the message says why:

# Good commit messages
git commit -m "Add year-over-year comparison to revenue dashboard

- Calculate YoY growth percentage
- Add visual indicators for positive/negative growth
- Include tooltip with detailed breakdown
- Update tests for new calculation

Fixes #234"

# Bad commit messages
git commit -m "Update dashboard"
git commit -m "Fix"
git commit -m "WIP"
git commit -m "asdfasdf"

A commit template keeps the format consistent across the team:

# .gitmessage template
# <type>: <subject>
#
# <body>
#
# <footer>

# Type should be one of:
# - feat: New feature
# - fix: Bug fix
# - docs: Documentation change
# - style: Formatting change
# - refactor: Code restructuring
# - test: Test addition/modification
# - chore: Maintenance task

Code review

Code review catches errors, spreads knowledge and keeps standards consistent. Three pieces make it work.

Checks on every pull request. Run the project and its tests on every pull request, so a broken query or a wrong number fails the check before a reviewer looks at it. With Visivo that is visivo run followed by visivo test:

# .github/workflows/pr-checks.yml
name: PR checks

on: pull_request

jobs:
  visivo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - run: pip install visivo

      - name: Run and test the project
        run: |
          visivo run
          visivo test
        env:
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

Automated pre-review checks. Catch naming, credential and SQL lint problems by script, so the human reviewer spends their time on the logic:

# automated-review-checks.py
def pre_review_checks(pr):
    """Automated checks before human review"""

    checks = []

    # Check file naming
    for file in pr.changed_files:
        if not follows_naming_convention(file):
            checks.append(f"File {file} doesn't follow naming convention")

    # Check for credentials
    for file in pr.changed_files:
        if contains_credentials(file):
            checks.append(f"CRITICAL: {file} contains credentials")

    # Check SQL quality
    sql_files = [f for f in pr.changed_files if f.endswith('.sql')]
    for sql_file in sql_files:
        errors = lint_sql(sql_file)
        if errors:
            checks.append(f"SQL errors in {sql_file}: {errors}")

    return checks

Written review guidelines. Put the expectations in the repository, next to the code they apply to:

## Code Review Guidelines

### For Reviewers

1. Check business logic correctness
2. Verify performance implications
3. Ensure consistent styling
4. Look for security issues
5. Suggest improvements, don't just find problems

### For Authors

1. Self-review before requesting others
2. Keep PRs small and focused
3. Respond to all comments
4. Update based on feedback
5. Thank reviewers for their time

### Review Checklist

- [ ] Business logic is correct
- [ ] Calculations are accurate
- [ ] Error handling is appropriate
- [ ] Documentation is updated
- [ ] Tests cover new functionality

What reliability looks like

Each practice above pays out in a specific way when something goes wrong.

An audit trail for every change. The history answers who, what and when without a meeting:

# Investigate dashboard issues
git log --oneline dashboards/revenue.yml
# a1b2c3d Fix: Correct tax calculation
# d4e5f6g Feat: Add quarterly comparison
# g7h8i9j Refactor: Simplify date logic

# See who made specific changes
git blame dashboards/revenue.yml
# a1b2c3d (Tim 2024-09-01) tax_rate: 0.08
# d4e5f6g (Jane 2024-08-15) quarter_calc: QUARTER(date)

# Find when issue was introduced
git bisect start
git bisect bad HEAD
git bisect good v1.0.0
# Git automatically finds the problematic commit

Fast rollback. A bad change is one revert away from gone:

# Dashboard showing wrong numbers after recent deploy

# 1. Identify the problematic commit
git log --oneline -5
# xyz789 (HEAD) Update customer segmentation
# abc456 Modify revenue calculation  <-- This one!
# def123 Add new KPI

# 2. Revert the change
git revert abc456

# 3. Deploy the fix
git push origin main
# CI/CD automatically deploys

# Total time to fix: < 5 minutes

Parallel work without collisions. Two people change two dashboards on two branches and merge both:

# Developer A: Working on sales dashboard
git checkout -b feature/sales-dashboard-update

# Developer B: Working on marketing dashboard
git checkout -b feature/marketing-metrics

# Both can work independently
# Merge without conflicts since they touch different files

Reasoning that outlives the author. The commit records why the number changed, not just that it did:

Adjust revenue recognition timing

Per finance team request, revenue is now recognized
at shipment rather than order placement. This aligns
with new accounting standards (ASC 606).

Testing: Validated against last 6 months of data
Impact: ~2% difference in monthly revenue timing
Stakeholders: @finance-team @accounting

None of this is optional for BI you intend to trust. A dashboard outside Git is work you can lose, a calculation you cannot explain and a change you cannot prove to an auditor. The practices above cost little to adopt, and they pay back the first time someone asks what changed.

Visivo was built for this workflow. A project is YAML and SQL in a repository, so every practice in this post applies to it without translation. /get-started takes you from install to a dashboard in Git in a few minutes, and the full reference lives at docs.visivo.io.

Install command copied