Data in GitHub Usage

Introduction

Once you have configured your GitHub account, repository, and table tracking (see Data in GitHub Setup), you are ready to start using the Data in GitHub feature in your daily workflow. This chapter covers the core operations: committing data to GitHub, pulling data from GitHub, monitoring changes, working with branches, reviewing changes, and best practices for maintaining a reliable data versioning workflow.

If you are unfamiliar with what Data in GitHub is and how it works at a high level, start with the Data in GitHub Overview.

Committing Data to GitHub

Committing data is the process of taking a snapshot of your Business Central table data and pushing it to your GitHub repository as a JSON file. Each commit creates a versioned record in Git, preserving the exact state of the data at the time of the commit.

How to Commit

Open the Tables on GitHub page in Business Central. You can find it by searching for "Tables on GitHub" in the search bar.
The page displays all tables you have configured for GitHub integration. Each row represents a table, along with its current status and timestamps.
Select the table or tables you want to commit. You can select a single table or multiple tables at once.
Invoke the commit action from the page. The ToolBox reads the current data from each selected table, serializes it to JSON using your configured format (Verbose or Compact), and pushes the resulting file to the configured GitHub repository and branch.
After the commit completes, the last commit timestamp is updated for each committed table, giving you a clear record of when the data was last pushed.

What Happens During a Commit

When you initiate a commit, the following steps occur:

The Import/Export Management codeunit reads all records from the selected Business Central table.
The data is serialized to JSON according to the JSON Format setting (Verbose or Compact) configured in the ToolBox Setup.
The GitHub Management codeunit authenticates with the GitHub API using your personal access token.
The JSON file is committed to the specified repository and branch. If the file already exists, it is updated with the new content. If it is a new table being committed for the first time, a new file is created.
The commit timestamp and status are updated in the GitHub Table table.

Committing Multiple Tables

You can commit multiple tables in a single operation by selecting them on the Tables on GitHub page. Each table is committed as a separate JSON file in the repository. This allows you to take a coordinated snapshot of related tables at the same point in time.

For example, if you want to capture the current state of your Customer, Vendor, and Item tables together, select all three and commit them in one operation. This ensures the data snapshot is consistent across the tables.

Pulling Data from GitHub

Pulling data is the reverse of committing: you retrieve JSON data from your GitHub repository and import it into your Business Central tables. This is how you restore previous versions, synchronize data from another environment, or seed a new environment with baseline data.

How to Pull

Open the Tables on GitHub page.
Select the table or tables you want to pull data for.
Invoke the pull action from the page.
The ToolBox retrieves the JSON file for each selected table from the configured repository and branch.
If the Empty Tables Before Pull setting is enabled in the ToolBox Setup, the ToolBox deletes all existing records in the target table before importing. If disabled, the data is merged with existing records.
The JSON data is deserialized by the Import/Export Management codeunit and inserted into the Business Central table.
After the pull completes, the last update timestamp is updated for each table.

Understanding Empty Tables Before Pull

The Empty Tables Before Pull setting is critical to understand because it determines how the pull operation handles existing data:

Enabled. All records in the target table are deleted before the GitHub data is imported. After the pull, the table contains exactly the records from the GitHub version. This is the safest option for full synchronization but it is destructive -- any records that exist in Business Central but not in GitHub will be permanently removed.
Disabled. The GitHub data is imported without clearing the table first. New records from GitHub are inserted. Existing records with matching primary keys are updated. Records that exist in Business Central but not in GitHub are left unchanged. This is useful for partial imports or when the GitHub data represents a subset of the table.

Choose the setting that matches your intent for each pull operation. If you are unsure, consider testing with a non-critical table first.

Pulling Multiple Tables

Like committing, you can pull multiple tables in a single operation. Each table is processed independently, so a failure in one table does not prevent the others from completing. After the operation, review the status of each table to confirm that all pulls succeeded.

Monitoring Changes

The change monitoring system tracks modifications to your configured tables between commits. This helps you know which tables have pending changes and may need a fresh commit.

How Monitoring Works

The monitoring system relies on two components:

Triggers codeunit. This codeunit subscribes to Business Central's event system and detects insert, modify, and delete operations on tables that are configured for GitHub integration. When a change is detected, it records the event.
Change Log Management codeunit. This codeunit manages the change log entries. Each detected operation is stored in the Change Log table with details about the table, the type of operation, and the timestamp.

Together, these components maintain a running record of all data changes on your monitored tables.

Viewing the Monitor Status

Open the Table Monitor List page to see the current monitoring status. This page shows each monitored table along with indicators of whether changes have occurred since the last commit. You can use this view to quickly identify which tables need attention.

The monitor list is particularly useful in environments where multiple users modify data throughout the day. Instead of committing all tables on a fixed schedule, you can check the monitor list and commit only the tables that have actually changed.

Monitor Start Time

The MonitorStartTime setting in the ToolBox Setup determines the baseline for change detection. Only changes that occur after this timestamp are recorded. If you set the monitor start time to the current date and time when you first enable monitoring, you establish a clean baseline and avoid capturing historical changes that occurred before you started tracking.

You can adjust the monitor start time at any time. Setting it to a future time effectively pauses monitoring until that time arrives. Setting it to a past time includes all changes detected since that time.

Change Log Details

The Change Log table stores the detailed change log entries. Each entry includes:

The table ID and table name of the affected table.
The type of operation: insert, modify, or delete.
A timestamp indicating when the change occurred.

You can review these entries directly if you need to understand the specific changes that have occurred. This level of detail is useful for auditing purposes or when you want to verify that a particular change was captured before committing.

Working with Branches

The branch system in Data in GitHub allows you to organize your data across multiple Git branches within one or more repositories. This provides flexibility for managing different environments, data categories, or versioning strategies.

Understanding Branch Mappings

Each table you track can be mapped to a specific repository and branch through the Repos/Branches page. When you commit or pull data for a table, the ToolBox uses this mapping to determine the correct target location in GitHub.

If no specific mapping is configured for a table, the ToolBox uses the default repository and branch settings.

Managing Repositories and Branches

Open the Repos/Branches page to view and manage your repository and branch configurations. From this page, you can:

Add new repository-and-branch combinations.
Edit existing configurations.
Remove configurations that are no longer needed.

Each entry represents a unique combination of repository and branch. For example, you might have:

Repository	Branch	Purpose
`yourname/bc-data`	`main`	Primary data store for production master data
`yourname/bc-data`	`sandbox`	Sandbox environment data
`yourname/bc-config`	`main`	Configuration and setup tables

Switching Branches

If you need to commit to or pull from a different branch than the one currently mapped, update the mapping on the Repos/Branches page before performing the operation. This allows you to direct data to the correct branch without creating a permanent configuration change.

Branch Strategies

Consider the following strategies for organizing your branches:

Single branch. All data goes to one branch (for example, main). Simple and easy to manage. Best for small setups with a single environment.
Environment-based branches. One branch per Business Central environment (for example, production, sandbox, test). This keeps data from different environments separate and makes it easy to synchronize between specific environments.
Category-based branches. Branches organized by data category (for example, master-data, configuration, reference-data). This allows independent versioning and commit schedules for different types of data.
Snapshot branches. Branches created at specific points in time to preserve a frozen snapshot of the data (for example, year-end-2025, pre-migration). These branches are typically created once and never updated again.

Reviewing Changes

One of the primary benefits of storing data in GitHub is the ability to review changes over time using GitHub's built-in tools.

Viewing Commit History

In your GitHub repository, navigate to the file for a specific table and click the History button. This shows you every commit that modified the file, with the date, author, and commit message for each. You can click on any commit to see the exact changes made in that version.

Comparing Versions with Diffs

When you view a commit in GitHub, the diff view highlights the lines that were added, removed, or modified. Because your data is stored as JSON, each line typically represents a field-value pair or a record boundary. This makes it straightforward to see:

Which records were added (new lines in green).
Which records were removed (deleted lines in red).
Which field values changed (modified lines showing the old and new values).

The Verbose JSON format is particularly useful for diff review because the field names are human-readable. With the Compact format, you can still see diffs, but you need to know the field IDs to interpret them.

Comparing Across Branches

If you maintain data on multiple branches, you can use GitHub's branch comparison feature to see the differences between branches. This is useful for comparing production data against sandbox data, or for reviewing changes before merging one branch into another.

Using the Change Log

Within Business Central, you can review the Change Log table for detailed records of every tracked change. This provides a Business Central-native view of the changes, complementing the GitHub-based review. The change log is especially useful for identifying who or what process triggered a change, which is information that may not be captured in the Git commit message.

Import and Export Operations

The Import/Export Management codeunit handles all data serialization and deserialization operations. Understanding how it works helps you anticipate the results of commit and pull operations.

Serialization (Commit)

During a commit, the codeunit reads each record from the Business Central table and converts it to a JSON object. All fields in the table are included in the serialization. The JSON structure depends on your format setting:

Verbose. Each field is represented as a key-value pair with the field name as the key.
Compact. Each field is represented as a key-value pair with the field ID (as a string) as the key.

The complete table is represented as a JSON array of these objects, with each object being one record.

Deserialization (Pull)

During a pull, the codeunit reads the JSON file from GitHub and converts each JSON object back into a Business Central record. It matches JSON keys to fields (by name for Verbose format or by ID for Compact format) and inserts or updates the records in the target table.

If the table schema has changed since the data was committed (for example, a field was added or removed), the import handles the mismatch gracefully. Fields that exist in the JSON but not in the current table are ignored. Fields that exist in the current table but not in the JSON are left at their default values.

Timestamps and Status Tracking

The Data in GitHub feature maintains several timestamps and status indicators to help you track the state of your data operations.

Last Commit Timestamp

Each table in the Tables on GitHub displays the timestamp of its last successful commit. This tells you when the data was last pushed to GitHub. If the timestamp is old, it may indicate that the table has changed since the last commit and a new commit is needed.

Last Pull Timestamp

Similarly, each table displays the timestamp of its last successful pull. This tells you when the table was last updated from GitHub data.

Monitor Status

The Table Monitor List shows whether changes have been detected since the last commit. Tables with pending changes are highlighted, making it easy to prioritize your commit operations.

Best Practices

Follow these guidelines to get the most out of the Data in GitHub feature and maintain a reliable data versioning workflow.

Commit Regularly

Establish a regular commit schedule for your tracked tables. The more frequently you commit, the finer-grained your version history becomes. For critical master data, consider committing daily or after any significant batch of changes. For less critical reference data, weekly commits may be sufficient.

Use Verbose Format for Important Data

When human readability matters -- for master data that you review in GitHub, configuration data that you compare across environments, or any data that multiple team members need to understand -- use the Verbose JSON format. The larger file size is a worthwhile trade-off for the clarity it provides in diffs and reviews.

Use Compact Format for Large Datasets

For tables with thousands of records or many fields, the Compact format reduces file sizes significantly and speeds up both commit and pull operations. Use this format when efficiency matters more than readability.

Set Up Monitoring for Critical Tables

Enable change monitoring for your most important tables so you always know when data has changed. Use the Table Monitor List as a dashboard to review pending changes before committing. This ensures you do not miss any significant data modifications.

Review Before Pulling

Before pulling data from GitHub into a Business Central table, especially with the Empty Tables Before Pull option enabled, review the data in GitHub to confirm it represents the state you want. Pulling with empty-before-pull is a destructive operation for the existing data in the table.

Use Branches to Separate Environments

If you work with multiple Business Central environments, use separate branches for each environment. This prevents accidental data cross-contamination and makes it clear which data belongs to which environment.

Document Your Repository Structure

Maintain a README file in your GitHub repository that explains the branch strategy, which tables are stored in which branches, and any conventions your team follows. This documentation helps onboard new team members and reduces confusion when multiple people work with the same repositories.

Coordinate with Your Team

If multiple users have access to the ToolBox and the GitHub repository, establish conventions for who commits and when. Uncoordinated commits from multiple users can lead to conflicts or overwritten changes. Consider designating a primary committer for each set of tables, or establish a schedule so that commits happen in a predictable order.

Test with Non-Critical Data First

When setting up Data in GitHub for the first time, or when changing your configuration, start with a non-critical table that you can afford to lose data from. Perform a full cycle of commit, modify, commit again, and pull to verify that everything works as expected before adding your important master data tables.

Monitor Token Expiration

GitHub personal access tokens have expiration dates. Monitor when your token expires and generate a new one before it lapses. An expired token will cause all commit and pull operations to fail. Consider setting a calendar reminder for token renewal.

Troubleshooting

Commit Fails with Authentication Error

Verify that your personal access token has not expired. Check the expiration date in your GitHub settings under Developer settings > Personal access tokens.
Confirm that the token has the required permissions (repo scope for classic tokens, or Contents read/write for fine-grained tokens).
Update the token in the ToolBox Setup page if you have recently regenerated it.

Pull Imports No Data

Confirm that the JSON file exists in the repository for the selected table and branch. Navigate to the repository in a web browser to verify.
Check that the branch mapping is correct on the Repos/Branches page.
Verify that the JSON file is not empty by viewing its contents in GitHub.

Monitor Shows No Changes

Verify that the MonitorStartTime in the ToolBox Setup is set to a time before the changes you expect to see.
Confirm that change monitoring is enabled for the specific table.
Check that the Triggers codeunit is active and has not been disabled.
Make a test change to a monitored table and check the Change Log table directly for new entries.

Data Mismatch After Pull

If the pulled data does not match what you expected, verify that you are pulling from the correct branch. Check the Repos/Branches mapping for the table.
If fields are missing or empty after a pull, the table schema may have changed since the data was committed. Re-commit the data with the current schema to update the JSON file.
If extra records remain in the table after a pull, the Empty Tables Before Pull option may be disabled. Enable it if you want an exact synchronization.

Large Table Commits Are Slow

For tables with many records, commits take longer because all records must be serialized and uploaded. Consider using the Compact JSON format to reduce file sizes.
Check your network connection to GitHub. Slow upload speeds affect commit performance.
If possible, commit large tables during off-peak hours when Business Central server load is lower.

Next Steps

You are now equipped to use the full Data in GitHub workflow. For broader ToolBox configuration options, see the Setup Overview. To explore other data management features, see the Remote Packages Overview for cross-environment data transfer capabilities.