Erik's ToolBox Documentation
Index

Data in GitHub Setup

Before You Begin

Before you can commit or pull Business Central data through GitHub, you must configure several components: a GitHub account with a personal access token, a GitHub repository to store your data, and the ToolBox settings that connect everything together. This chapter walks you through each step of the setup process.

If you are not familiar with what Data in GitHub is or how it works, review the Data in GitHub Overview first.

Prerequisites

To use the Data in GitHub feature, you need the following:

  • A GitHub account. You can use a free or paid GitHub account. The account must have permission to create repositories or access to an existing repository where data will be stored.
  • A GitHub personal access token. This token authenticates the ToolBox when it communicates with the GitHub API. You generate the token from your GitHub account settings.
  • A GitHub repository. You need at least one repository to store your data. The repository can be public or private, though a private repository is recommended for business data.
  • Erik's ToolBox installed and licensed. The Data in GitHub feature is part of the ToolBox app. Ensure that both the AL Compiler and Interpreter and the ToolBox app are installed in your Business Central environment.
  • Appropriate Business Central permissions. You need permission to access the ToolBox pages and the Business Central tables you intend to track.

Creating a GitHub Personal Access Token

The personal access token is how the ToolBox authenticates with GitHub on your behalf. GitHub supports two types of tokens: classic tokens and fine-grained tokens. Either type works with the ToolBox.

Option 1: Classic Token

  1. Sign in to your GitHub account at github.com.
  2. Navigate to Settings by clicking your profile picture in the top-right corner and selecting Settings.
  3. In the left sidebar, scroll down to Developer settings and click it.
  4. Click Personal access tokens, then Tokens (classic).
  5. Click Generate new token, then Generate new token (classic).
  6. Give the token a descriptive name, such as "ToolBox Business Central Integration."
  7. Set an expiration date. Choose a duration that balances security and convenience. You can always generate a new token when one expires.
  8. Under Select scopes, check the repo scope. This grants full control of private repositories, which is required for the ToolBox to read from and write to your repository.
  9. Click Generate token.
  10. Copy the token immediately. GitHub will not show it again after you navigate away from the page.

Option 2: Fine-Grained Token

  1. Follow steps 1 through 4 above, but click Fine-grained tokens instead of Tokens (classic).
  2. Click Generate new token.
  3. Give the token a descriptive name and set an expiration date.
  4. Under Repository access, select Only select repositories and choose the specific repository or repositories you will use for data storage.
  5. Under Permissions, expand Repository permissions and set Contents to Read and write. This allows the ToolBox to read files from and commit files to the repository.
  6. Click Generate token.
  7. Copy the token immediately.

Token Security

Your personal access token grants access to your GitHub repositories. Treat it with the same care as a password:

  • Do not share the token with others.
  • Do not store the token in plain text files or source code.
  • Rotate the token periodically by generating a new one and updating the ToolBox configuration.
  • If you suspect the token has been compromised, revoke it immediately from your GitHub settings and generate a replacement.

The ToolBox stores your token securely using Business Central's isolated storage mechanism, which encrypts the value at rest.

Creating a GitHub Repository

If you do not already have a repository for your Business Central data, create one:

  1. Sign in to GitHub and click the + icon in the top-right corner, then select New repository.
  2. Enter a repository name. A descriptive name such as bc-data-production or business-central-master-data is recommended.
  3. Choose the repository visibility. Private is recommended for business data to prevent unauthorized access.
  4. Optionally add a README file. This is not required but can be helpful for documenting the repository's purpose.
  5. Click Create repository.

Repository Structure

When the ToolBox commits data, it creates JSON files in the repository. The file structure is determined by the table names and branch configuration. You do not need to create any files or folders manually -- the ToolBox handles this automatically during the first commit.

Repository Recommendations

  • Use one repository per Business Central environment for clarity and access control. For example, separate repositories for production and sandbox environments.
  • Use a private repository for any data that contains business-sensitive information.
  • Add collaborators to the repository if other team members need to review data changes or pull data into their environments.

Configuring ToolBox Settings

With your GitHub account, token, and repository ready, the next step is to configure the ToolBox within Business Central.

Accessing the Setup

Open the ToolBox Setup page in Business Central. You can find it by searching for "ToolBox Setup" in the search bar. The GitHub Integration section of the setup page contains the following fields:

GitHub Account Name

Enter your GitHub username (not your email address). This is the account name that appears in your GitHub profile URL. For example, if your GitHub profile is at https://github.com/johndoe, your account name is johndoe.

If you are using an organization-owned repository rather than a personal repository, you still enter your personal GitHub username here. The token's permissions determine which repositories you can access, regardless of whether they are owned by your personal account or an organization.

GitHub Personal Token

Paste the personal access token you generated in the previous section. The ToolBox stores this value securely in Business Central's isolated storage. After you save the setup, the token is encrypted and is not displayed in plain text on the page.

If you need to update the token later (for example, after it expires and you generate a new one), you can clear the field and enter the new token.

JSON Format

Choose between Verbose and Compact format for JSON serialization:

Format JSON Keys File Size Best For
Verbose Field names (e.g., "Name", "City") Larger Human readability, diff review in GitHub, collaboration
Compact Field IDs (e.g., "1", "2") Smaller Large datasets, faster processing, storage efficiency

The Verbose format makes it easy to understand the data when viewing JSON files directly in GitHub or reviewing diffs in pull requests. The Compact format is more efficient but requires knowledge of field IDs to interpret.

You can change this setting at any time. However, changing the format affects only future commits. Existing files in the repository retain their original format until they are overwritten by a new commit.

Empty Tables Before Pull

When this option is enabled, the ToolBox deletes all existing records in a table before importing data from GitHub during a pull operation. This ensures that the table contents match the GitHub version exactly, with no leftover records from previous states.

When this option is disabled, the ToolBox imports the data from GitHub without clearing the table first. Records from GitHub are inserted or updated, but records that exist in Business Central but not in the GitHub data are left in place.

Enable this option when you want exact synchronization and your GitHub data represents the complete desired state of the table.

Disable this option when you want to merge data from GitHub with existing records, or when the GitHub data represents a partial dataset.

Monitor Start Time

The MonitorStartTime field specifies the starting point for change monitoring. Only changes that occur after this timestamp are tracked by the monitoring system. This is useful for establishing a baseline: set the monitor start time to the current date and time when you first enable monitoring, and only subsequent changes will be recorded.

If you leave this field blank or set it to a past date, all changes detected by the trigger system will be included in monitoring.

Setting Up Tables to Track

After configuring the GitHub connection settings, you need to specify which Business Central tables you want to track.

Adding Tables

  1. Open the Tables on GitHub page. You can find it by searching for "Tables on GitHub" in the Business Central search bar.
  2. The page displays a list of tables currently configured for GitHub integration.
  3. To add a new table, create a new line and select the table you want to track. You can search by table name or table ID.
  4. Repeat for each table you want to include.

Per-Table Settings

Each table in the Tables on GitHub can have individual settings that override or complement the global configuration. Review the available fields for each table entry and configure them according to your needs.

Choosing Which Tables to Track

Consider the following guidelines when deciding which tables to track:

  • Master data tables (Customers, Vendors, Items, Resources) are excellent candidates because they change infrequently but are critical to business operations.
  • Setup and configuration tables are valuable to track because they control system behavior and are difficult to reconstruct from memory.
  • Dimension values, posting groups, and reference data are good candidates because they are shared across the system and affect many processes.
  • Transaction tables (ledger entries, posted documents) are generally poor candidates because they are large, change frequently, and are better served by standard database backups.

Setting Up Change Monitoring

To track changes automatically, you need to enable change monitoring for your configured tables:

  1. On the Tables on GitHub page, select the tables you want to monitor.
  2. The Triggers codeunit integrates with Business Central's change log system to detect insert, modify, and delete operations.
  3. Once monitoring is active, the Table Monitor records changes as they occur.
  4. You can view the monitoring status at any time through the Table Monitor List page.

The Change Log Management codeunit manages the underlying change log entries. It stores a record of each detected operation in the Change Log table, providing a detailed history of what changed and when.

Repository and Branch Configuration

The Data in GitHub feature supports multiple repositories and branches, giving you flexibility in how you organize your data in GitHub.

Managing Repositories and Branches

Open the Repos/Branches page to view and manage your repository and branch configurations. Each entry in the list represents a specific repository-and-branch combination that the ToolBox can use for commits and pulls.

To add a new repository and branch:

  1. Create a new line on the Repos/Branches page.
  2. Enter the repository name in the format owner/repository (for example, johndoe/bc-data-production).
  3. Specify the branch name (for example, main, production, sandbox).
  4. Save the entry.

Mapping Tables to Branches

Use the Repos/Branches page to configure which tables are mapped to which repository branches. This mapping determines where data is committed to and pulled from for each table.

Table-to-branch mapping enables several organizational strategies:

  • All tables on one branch. The simplest approach. All tracked tables commit to and pull from the same branch (for example, main).
  • Tables grouped by category. Map master data tables to a master-data branch, configuration tables to a config branch, and reference data to a reference branch.
  • Tables separated by environment. Map tables to branches named after the source environment, such as production or sandbox.

Choose the strategy that best fits your workflow. You can always reorganize later by updating the mappings.

Branch Naming Conventions

GitHub branch names have some restrictions. Keep the following in mind:

  • Branch names cannot contain spaces. Use hyphens or underscores instead (for example, master-data or master_data).
  • Branch names are case-sensitive. Main and main are treated as different branches.
  • Use descriptive names that make the branch's purpose clear at a glance.

Verifying Your Setup

After completing the configuration, verify that everything is working correctly:

  1. Test the GitHub connection. Open the Tables on GitHub and attempt a small operation, such as committing a single table with a few records. If the commit succeeds, your account name, token, and repository configuration are correct.
  2. Check the repository. Open your GitHub repository in a web browser and confirm that a JSON file was created for the test commit. Review the file contents to verify that the data was serialized correctly in your chosen format (Verbose or Compact).
  3. Verify monitoring. If you have enabled change monitoring, make a small change to a monitored table (for example, edit a single field on a single record). Then check the Table Monitor List to confirm that the change was detected.
  4. Test a pull operation. After a successful commit, try pulling the data back. If you enabled "Empty Tables Before Pull," be aware that this will clear the table contents before importing. Consider testing with a non-critical table first.

Troubleshooting Setup Issues

If you encounter problems during setup, check the following common issues.

Authentication Failures

  • Verify that your GitHub account name is your username, not your email address.
  • Confirm that the personal access token has not expired. Check the token's expiration date in your GitHub settings.
  • Ensure the token has the correct scopes. For classic tokens, the repo scope is required. For fine-grained tokens, the Contents permission must be set to Read and write.
  • If you recently regenerated the token, make sure you updated it in the ToolBox Setup page.

Repository Access Errors

  • Confirm that the repository exists and that your GitHub account has access to it.
  • For organization-owned repositories, verify that your account has been granted the necessary permissions by an organization administrator.
  • Check that the repository name is entered correctly in the format owner/repository.

Branch Not Found

  • Verify that the branch exists in the repository. If you specified a branch that does not exist, the first commit may need to create it.
  • Check for typos in the branch name. Branch names are case-sensitive.

Empty or Incorrect Data

  • If committed data appears empty or incomplete, verify that the source table in Business Central contains data and that you have read permissions for that table.
  • If the JSON format looks unexpected, check the JSON Format setting in the ToolBox Setup.

Monitor Not Detecting Changes

  • Verify that the MonitorStartTime is set to a time before the changes you expect to see.
  • Confirm that the Triggers codeunit is active and that change monitoring is enabled for the table in question.
  • Check that the change log is configured to track the relevant operations (insert, modify, delete) for the table.

Next Steps

With your setup complete, proceed to the Data in GitHub Usage guide to learn how to commit data, pull data, monitor changes, and work with branches in your daily workflow.