Data in GitHub Overview
Erik's ToolBox includes a powerful GitHub integration feature called Data in GitHub that brings version control concepts to your Business Central table data. Instead of relying solely on backups or manual exports, you can store snapshots of your table data as JSON files in a GitHub repository, track changes over time, and pull data back when needed.
Whether you need to maintain a change history for master data, roll back to a previous state after an error, compare data between environments, or synchronize configuration data across tenants, Data in GitHub provides the tools to do it directly from within Business Central.
What Is Data in GitHub?
Data in GitHub is a set of pages, tables, and codeunits within Erik's ToolBox that connect your Business Central environment to one or more GitHub repositories. The feature allows you to select specific Business Central tables, serialize their data to JSON, and commit that JSON to a GitHub repository. You can also pull data from GitHub back into Business Central, effectively using GitHub as a versioned data store.
The core idea is straightforward: GitHub excels at tracking changes to text-based files over time. By representing your Business Central table data as JSON files, you gain all the benefits of Git version control -- commit history, diffs, branching, and collaboration -- applied to your data rather than source code.
Why Use Data in GitHub?
Traditional approaches to managing Business Central data outside the application have significant limitations. Database backups capture everything at once and are not granular. Manual exports require discipline and produce files with no built-in change tracking. Data in GitHub addresses these gaps by providing a structured, automated, and version-controlled approach.
Change History
Every time you commit data to GitHub, a new version is recorded. You can review the full history of commits to see exactly what changed, when it changed, and who made the commit. This is invaluable for auditing and compliance scenarios where you need to demonstrate that data changes are tracked and attributable.
Rollback Capability
If a data change causes problems -- whether from a bulk update gone wrong, a misconfigured import, or a user error -- you can pull a previous version of the data from GitHub to restore the table to a known good state. This is faster and more targeted than restoring an entire database backup.
Data Comparison
Because GitHub stores data as JSON text files, you can use GitHub's built-in diff viewer to compare any two versions of your data side by side. This lets you see exactly which records were added, modified, or deleted between commits, down to the individual field level.
Cross-Environment Synchronization
If you maintain multiple Business Central environments -- for example, a production environment and a sandbox, or environments for different tenants -- you can use Data in GitHub to synchronize data between them. Commit data from one environment, then pull it into another. This is particularly useful for configuration data, reference data, and master data that should be consistent across environments.
Data Recovery
In scenarios where individual tables lose data due to processing errors, extension upgrades, or other issues, you can recover the affected tables from GitHub without touching the rest of the database. This surgical approach to data recovery avoids the disruption of a full database restore.
How It Works
The Data in GitHub feature follows a straightforward workflow that mirrors common version control practices. Here is an overview of the process from configuration through daily use.
Step 1: Configure Which Tables to Track
You start by opening the Tables on GitHub page in Business Central and adding the tables you want to track. Each table you add becomes a candidate for data commits and pulls. You can add as many tables as you need, from a single configuration table to dozens of master data tables.
Step 2: Monitor Changes
Once tables are configured, the ToolBox can monitor changes to those tables through the change log trigger system. The Triggers codeunit integrates with Business Central's change tracking to detect insert, modify, and delete operations on your monitored tables. The Table Monitor records which tables have pending changes since the last commit.
You can view the current monitoring status through the Table Monitor List page, which shows you at a glance which tables have changed and may need a fresh commit.
Step 3: Commit Data Snapshots to GitHub
When you are ready to capture the current state of your data, you commit it to your GitHub repository. The GitHub Management codeunit handles the serialization and communication with GitHub. It reads the table data, converts it to JSON format, and pushes it to the configured repository and branch.
Each commit creates a versioned snapshot in GitHub. Over time, these snapshots build up a complete history of your data's evolution.
Step 4: Pull Data from GitHub
When you need to restore data or synchronize from another environment, you pull from GitHub. The pull operation retrieves the JSON files from the specified repository and branch, deserializes the data, and imports it into the corresponding Business Central tables.
If the Empty Tables Before Pull option is enabled in your configuration, the ToolBox clears the target table before importing, ensuring a clean synchronization. If disabled, the pulled data is merged with existing records.
Key Components
The Data in GitHub feature is built from several AL objects that work together to provide the full workflow.
Pages
| Page | Purpose |
|---|---|
| Tables on GitHub | The primary interface for managing which tables are tracked, committing data, and pulling data from GitHub. |
| Table Monitor List | Displays the change monitoring status for tracked tables, showing which tables have pending changes. |
| Repos/Branches | Manages the list of GitHub repositories and branches available for data operations. |
| Repos/Branches | Configures the mapping between Business Central tables and specific repository branches. |
Tables
| Table | Purpose |
|---|---|
| GitHub Table | The core table that stores the list of Business Central tables configured for GitHub integration, along with their settings and status. |
| Table Monitor | Tracks change monitoring data for each configured table, recording which tables have pending changes since the last commit. |
| Change Log | Stores change log entries generated by the trigger system, recording insert, modify, and delete operations on monitored tables. |
| GitHub Repo/Branch | Stores the repository and branch configurations that define where data is stored in GitHub. |
Codeunits
| Codeunit | Purpose |
|---|---|
| GitHub Management | The main integration codeunit that handles all communication with the GitHub API, including authentication, data serialization, committing, and pulling. |
| Change Log Management | Manages the change log system that tracks data modifications, providing the foundation for monitoring which tables have changed. |
| Import/Export Management | Handles the serialization of Business Central data to JSON and the deserialization of JSON back to Business Central records. |
| Triggers | Integrates with Business Central's event system to detect insert, modify, and delete operations on monitored tables and record them in the change log. |
JSON Format Options
When data is serialized to JSON for storage in GitHub, you can choose between two format options. This choice affects readability, file size, and how diffs appear in GitHub.
Verbose Format
The Verbose format uses human-readable field names as JSON keys. For example, a Customer record might look like this:
{
"No.": "10000",
"Name": "Adatum Corporation",
"City": "Atlanta",
"Country/Region Code": "US"
}This format is ideal when you want to review data directly in GitHub, compare changes in pull requests, or share data files with colleagues who may not know the field IDs. The trade-off is larger file sizes, especially for tables with many fields or long field names.
Compact Format
The Compact format uses field IDs as JSON keys instead of field names. The same Customer record would look like this:
{
"1": "10000",
"2": "Adatum Corporation",
"5": "Atlanta",
"35": "US"
}This format produces smaller files and is faster to process, making it better suited for large datasets or environments where transfer speed and storage efficiency matter more than human readability. The trade-off is that reviewing the raw JSON requires knowledge of the field IDs.
You configure the JSON format in the ToolBox Setup under the GitHub Integration section. The setting applies globally to all table exports, so choose the format that best matches your primary use case.
Branch Support
Data in GitHub supports mapping different tables or configurations to different Git branches within your repositories. This is managed through the Repos/Branches and Repos/Branches pages.
Branch support enables several useful patterns:
- Environment separation. Store production data on a
productionbranch and sandbox data on asandboxbranch. This keeps data from different environments organized and prevents accidental cross-contamination. - Table grouping. Map master data tables to one branch and configuration data tables to another. This allows you to commit and pull different categories of data independently.
- Staged rollouts. Commit new configuration data to a staging branch, review it, and then merge or pull it into production when ready.
- Historical snapshots. Create branches for specific points in time (for example,
year-end-2025) to preserve data snapshots that should not be modified by ongoing commits.
Common Use Cases
The following scenarios illustrate how different Business Central professionals use Data in GitHub in practice.
Master Data Versioning
You maintain a set of master data tables -- Customers, Vendors, Items, G/L Accounts -- that form the backbone of your Business Central configuration. By committing these tables to GitHub regularly, you build a versioned history of your master data. When a question arises about when a customer address changed or when a new item was added, you can review the commit history in GitHub for the answer.
Configuration Backup
Your Business Central environment contains numerous setup tables that control how the system behaves. By committing these configuration tables to GitHub, you create a reliable backup that is independent of database backups. If an upgrade or customization disrupts your configuration, you can pull the last known good version from GitHub.
Audit Trail
For compliance scenarios that require a verifiable record of data changes, Data in GitHub provides an external audit trail stored outside of Business Central. Because Git commits are immutable and timestamped, they serve as a trustworthy record of what data looked like at any point in time.
Migration Between Environments
When setting up a new Business Central environment or tenant, you can pull data from GitHub to seed the new environment with the correct master data and configuration. This is faster and more reliable than manual data entry or custom migration scripts.
Data Recovery
If a processing error, a runaway script, or an extension upgrade damages data in a specific table, you can pull the last good commit from GitHub to restore just that table. This targeted recovery avoids the overhead and risk of restoring an entire database.
Next Steps
If you are new to Data in GitHub, the recommended path is:
- Follow the Data in GitHub Setup guide to configure your GitHub account, repository, and ToolBox settings.
- Proceed to Data in GitHub Usage to learn how to commit, pull, and monitor your data.
- Review the Setup Overview for broader ToolBox configuration options that complement the GitHub integration.