Overview

Often, Business Central environments have vital configuration or setup data that must be tracked just as thoroughly as source code. By integrating setup data with GitHub, you can:

• View a clear history of changes (who changed what, when).
• Branch and merge data for different environments or testing scenarios.
• Maintain consistency and speed when moving configuration data from one environment to another.

What you need to get started

1. Erik’s Toolbox for Business Central

   Make sure you have installed and configured Erik’s Toolbox in your Business Central environment. (See the Toolbox documentation or AppSource listing for details on installation.)

2. GitHub Account

   Have a GitHub account to create and manage repositories.
   Decide whether your repository should be private or public.

Step 1: Create or Select a GitHub Repository

• Create a new repository in GitHub (or select an existing one).
  
  
• Initialize the repository with a README file so it’s not completely empty (this helps avoid errors when connecting from the toolbox).
  
  
• Set the repository’s privacy to either public or private, depending on your needs.
  
  

Step 2: Connect Erik’s Toolbox to Your GitHub Repository

• Open Erik’s Toolbox in Business Central from the Business Central role center or search function, open the Toolbox.

• Navigate to “Data in GitHub” In newer versions, “Data in GitHub” appears in the Toolbox menu.

• Select “New” to create a new connection record. Provide a name for your connection (e.g., “Demo Data”) or something descriptive of its purpose.

• Specify GitHub settings
  Enter the GitHub repository owner (your GitHub username or organization).
  Enter the repository name (must match exactly).
  Provide a valid personal access token (if required) for private repos.

• Click “Get Branches” to retrieve the available branches in your chosen repo.
  Select which branch you want to use (e.g., main or master, or any existing feature branch).

Tip: If you do not see any branches, ensure your GitHub token and repo details are correct, and that the repo contains at least one commit (e.g., your README).

Step 3: Select Which Tables to Track

• In the “Data in GitHub” page, add one or more tables to track.
  This might include critical setup tables like Table 79 (Company Information), Table 3 (Payment Terms), or any other table that holds configuration data you need to version-control.

• Save your selection. You can edit or remove these tracked tables at any time.

Step 4: Commit Data to GitHub

• Click “Commit” in the Data in GitHub list.
  The toolbox will export the data from the selected tables into JSON files and push them to your GitHub repository.

• Verify the commit in GitHub
  Open your GitHub repository.
  Check the commit history: you’ll see JSON files, each file corresponding to a table and containing the data from Business Central.

• Review the JSON
  The default JSON format includes field names and types for readability.
  If you prefer shorter JSON files (useful for large tables), switch to compact JSON in the Toolbox setup.

Step 5: Edit and Pull Changes

Editing in GitHub

• Open any JSON file in the GitHub interface (or clone the repo and edit locally).
  
  
• Make changes to the data (e.g., updating phone numbers or addresses).
  
  
• Commit these changes in GitHub with a descriptive message.
  
  

Pulling Changes into Business Central

• Return to the Data in GitHub page in Erik’s Toolbox.
  
  
• Select the relevant table(s) whose data you wish to refresh.
  
  
• Click “Pull” to retrieve and overwrite records in Business Central with the updated JSON from GitHub.
  
  

Note: In Toolbox Setup, you can enable “Empty Tables Before Pull.” This ensures the table is cleared before data is re-imported. Turn this off if you only want to overwrite or merge existing rows (rather than fully clearing them first).

Step 6: Branch Management

Branching allows you to maintain multiple versions of your setup data—for instance, one branch for Production data, one for Testing, and another for new feature experiments.

• Create a new branch in GitHub or via your preferred Git client.
  
  
• In Business Central, click “Get Branches” in the Data in GitHub page to refresh available branches.
  
  
• Select the branch you want to switch to, and choose “Switch to Branch.”
  If prompted, confirm whether you want to overwrite data in your local tables with the branch’s data.
  
  

Once you switch branches, all “Pull” and “Commit” operations will apply to that branch. You can:

• Commit new data changes to a feature branch without affecting main.
  
  
• Merge or create pull requests in GitHub to bring changes from a feature branch back into main.
  
  
• Quickly switch between branches to restore a different data state in Business Central.
  
  
  

Examples & Use Cases

• Development & QA
  Maintain one branch with production-like settings (for QA/testing) while actively updating a separate branch for new feature development.
  
  
• Scheduled Backups
  Periodically commit your configuration data (daily/weekly) so any changes are captured in version history, acting like a partial change log.
  
  
• Collaborative Editing
  Multiple team members can propose changes to key configuration tables via GitHub, ensuring all modifications go through pull requests before being deployed.
  
  

Additional Settings

• JSON Format
  Verbose (Default): Field names, numbers, and types are included for readability.
  Compact: Only field numbers and values are stored, reducing file size.

• Empty Tables Before Pull
  Off (Default): Only updated or new rows are overwritten/inserted.
  On: Clears all rows from the table before re-importing data.

Best Practices

• Commit Descriptions: Use descriptive commit messages to log the purpose or nature of data changes.
  
  
• Restrict Write Permissions: If the data is sensitive, secure your private GitHub repository and manage who can commit or modify the data.
  
  
• Regular Commits: The more frequently you commit, the more granular your change history — and easier it is to roll back if needed.
  
  
• Test in Sandbox: Before pulling data into production, test changes in a sandbox or test branch.

Troubleshooting & FAQs

• No Commits Appear in GitHub
  Confirm your GitHub credentials in Toolbox Setup and ensure the repo has at least one initial commit (e.g., a README).
  
  
• Branch Not Appearing
  Use “Get Branches” in the Data in GitHub page to refresh.
  Confirm the branch exists on GitHub and isn’t deleted or renamed.
  
  
• Pull Warnings
  If “Empty Tables Before Pull” is off, your data may partially merge. Check your table contents to ensure the correct result.