Technical note
Git for Analytics Teams
Git is often introduced to analytics teams as a developer tool.
Branches. Commits. Pull requests. Merge conflicts. Reviews.
That can make it feel like ceremony imported from software engineering.
For Reporting Trust, Git has a simpler purpose:
It makes changes to business logic reviewable and reversible.
If a revenue definition changes, the business should be able to see what changed, why it changed, who reviewed it, and when it reached production reporting. That should not depend on a Slack memory, a dashboard edit history, or one analyst remembering which query they changed.
Git gives reporting logic a history.
The symptom: nobody knows when the number changed
At Brightside Bikes, revenue has several legitimate versions:
- Shopify Net Revenue for weekly trading
- Finance Revenue for board and month-end reporting
- Contribution Margin for operating decisions
- Revenue bridge variance for reconciliation
If someone changes the SQL that excludes refunded orders, updates the SKU cost mapping, or adjusts the definition of Active Accessory Buyer, the effect can reach dashboards, board packs, and marketing decisions.
Without Git, that change may be hard to trace.
The team may ask:
- When did the dashboard number change?
- Was this a source issue or a logic change?
- Who approved the definition change?
- Can we compare the old and new SQL?
- Can we roll back safely?
If the answer is unclear, the reporting process is carrying hidden risk.
Git protects the reporting contract
A reporting contract defines what a metric means, who owns it, which caveats matter, and when it is safe to use.
Git helps protect that contract in the implementation layer.
The contract may say:
Shopify Net Revenue excludes tax, shipping, cancelled orders, fully voided orders, and immediate refunds.
The implementation may live in:
- A dbt model
- A Dataform SQLX file
- A semantic layer metric
- A YAML source definition
- A test file
- A documentation page
Git connects those files to a controlled change process.
When the logic changes, the team can review the change before it affects the business.
What belongs in version control
For analytics engineering, version control should include the things that define or protect reporting logic.
At Brightside, that might include:
- SQL models
- dbt or Dataform project files
- Source definitions
- Tests
- Metric definitions
- Documentation
- Macros or reusable SQL patterns
- CI/CD configuration
- Orchestration definitions when managed as code
- Dashboard-as-code files if the BI tool supports them
Not everything belongs in Git.
Raw data exports, local credentials, build artifacts, dependency folders, and generated caches should stay out. The goal is to version the logic and configuration, not every temporary by-product.
Branches create a safe place to change logic
A branch is a workspace for a change.
For Brightside, a branch might be:
fix/revenue-refund-timing
or:
add/active-bike-owner-definition
The branch should have a clear purpose. It should not contain unrelated changes across revenue, inventory, marketing, and documentation unless the work genuinely belongs together.
Focused branches make review easier.
They also reduce the risk that a small reporting fix accidentally ships with an unrelated dashboard or model change.
Pull requests are business logic review points
A pull request should not be treated as a rubber stamp.
For analytics work, a good pull request answers:
- What business question or reporting contract does this change support?
- Which models, tests, and dashboards are affected?
- Has the metric definition changed?
- Has the source-to-report path changed?
- What reconciliation was run?
- What should reviewers inspect?
- What is the rollout or rollback plan?
The reviewer does not need to inspect every line of SQL with equal intensity.
They need enough context to decide whether the change is safe for the reporting path.
For example, a Brightside pull request that changes refund handling should tag the Finance Lead as business owner and the Analytics Engineer as technical owner. It should include before-and-after revenue bridge totals and explain whether the Weekly Operating Performance Report will change.
That is Git as Reporting Trust infrastructure.
Commit messages should explain intent
Bad commit message:
fix query
Better commit message:
Exclude voided Shopify orders from weekly trading revenue
Best commit message when the change is sensitive:
Exclude voided Shopify orders from weekly trading revenue
Then in the pull request body:
- Why the change was needed
- Which reporting contract field it supports
- What totals changed
- Who approved the business meaning
Commit messages do not need to be long, but they should make future investigation easier.
When a board pack number changes unexpectedly, commit history is often the fastest way to distinguish a genuine business movement from a logic change.
What to inspect first
If an analytics team is new to Git, start with one important reporting path.
Ask:
- Is the SQL for the metric in version control?
- Are tests and documentation in the same review flow?
- Do changes happen through branches and pull requests?
- Are business owners included when definitions change?
- Can the team trace when a metric changed?
- Can the team roll back a bad change?
- Are secrets, data exports, and build artifacts excluded?
- Are pull requests small enough to review properly?
If the answer is no, Git may exist, but it is not yet protecting Reporting Trust.
What good looks like
Good Git usage for analytics teams is practical.
It does not require overcomplicated branching models or heavy ceremony.
For trusted reporting, good looks like this:
- Important reporting logic is version controlled.
- Every change has a branch.
- Pull requests explain business impact.
- Tests run before merge.
- Business definition changes get owner review.
- Commit history is readable.
- Rollback is possible.
- Generated files and credentials are ignored.
Git does not make a metric correct.
It makes the path of change visible.
That visibility matters because Reporting Trust is not only about what the number is today. It is also about whether the business can understand how and why the number changed.