Advanced Portal Designer Documentation
Index

Committing to GitHub

This page explains how to push your portal configuration to GitHub.

What Gets Committed?

When you commit to GitHub, APD pushes:

Component Folder Notes
Actions Tables/Table_APD Action.json All action definitions
DataItem configs Tables/Table_APD Action DataItem*.json Table and field mappings
DataItem filters Tables/Table_APD DataItem Filter 2.json Filter configurations
Security Profiles Tables/Table_APD Security Profile.json Profile definitions
Security Filters Tables/Table_APD Security Setup.json Table-level security
Content Types Tables/Table_APD Content Type.json Content categorization
Content metadata Tables/Table_APD Page Content.json Content properties
Templates Templates/* HTML template files
Content Content/{lang}/*.md or .html Markdown/HTML content

How to Commit

From APD Setup Page

  1. Open the Advanced Portal Designer menu page (search for it in Tell Me) and click Setup
  2. Click Commit to GitHub in the action bar
  3. Confirm the prompt ("Commit everything to branch {branch} in GitHub repository {repo}?")
  4. A second dialog (Commit to GitHub) prompts for the Commit message — edit the default or accept it
  5. Wait for the operation to complete
  6. Success message: "GitHub updated!"

Commit Process

When you commit, APD:

  1. Collects all portal configuration data
  2. Serializes tables to JSON format
  3. Exports templates as individual files
  4. Exports content with appropriate extensions
  5. Creates a single commit with all changes
  6. Pushes to the configured branch

Commit Details

Commit Message

APD prompts you for the commit message before each push. The default message — pre-filled in the dialog — is:

Commit from Business Central

Edit the field to write something meaningful (e.g. "Add customer dashboard action") before confirming. The dialog is the Commit to GitHub standard dialog page; cancelling it aborts the push with Commit cancelled..

Automatic Handling

APD automatically:

  • Creates new files for new items
  • Updates existing files for changes
  • Deletes template files that no longer exist in BC

Note: Table JSON files are never deleted, even if empty. Only template files are deleted when removed from Business Central.

File Formats

Table JSON Structure

Table data is stored as JSON with field references:

{
  "Table": "APD Action",
  "No": 70310502,
  "Records": [
    {
      "F1": {"value": "HOME"},
      "F2": {"value": "Home Page"},
      "F3": {"value": 0},
      "F10": {"value": "home"}
    }
  ]
}

Field numbers (F1, F2, etc.) correspond to Business Central field IDs.

Template Files

Templates are stored as plain HTML/text:

Templates/home
Templates/header
Templates/footer
Templates/ENU/welcome

Language-specific templates are in language code subfolders.

Content Files

Content uses file extensions based on style:

Content/0/privacy-policy.md      # Markdown (language 0)
Content/0/terms.html             # HTML (language 0)
Content/1033/welcome.md          # Markdown (English US)

Viewing Commits

In GitHub

After committing:

  1. Go to your GitHub repository
  2. Click on Commits or navigate to your branch
  3. See the latest commit "Commit from Business Central"
  4. Click the commit to see changed files

Comparing Changes

Use GitHub's diff view to:

  • See exactly what changed
  • Compare with previous versions
  • Review template modifications

Best Practices

Commit Regularly

  • Commit after significant changes
  • Commit before major modifications
  • Commit before testing in other environments

Review Before Commit

Before committing:

  1. Verify all actions compile correctly
  2. Test templates in the portal
  3. Ensure content is finalized

Write Meaningful Commit Messages

Use the commit-message dialog to describe what changed instead of accepting the default:

  • One short sentence summarising the change ("Add CUSTOMER-LIST action and template")
  • Reference a GitHub issue when applicable
  • Avoid generic messages like "Updates" or "Fixed stuff"

Handling Errors

"Cannot publish to a complete empty repository"

The repository needs at least one file:

  1. Go to your GitHub repository
  2. Add a README.md file through the web interface
  3. Try committing again

"Your GitHub setup is incomplete"

Verify all fields are filled:

  • GitHub Account Name
  • GitHub Personal Token
  • GitHub Repository
  • GitHub Branch

"GitHub Connection failed, error (401)"

Authentication failed:

  1. Verify your token hasn't expired
  2. Generate a new token if needed
  3. Update the GitHub Personal Token field

"GitHub Connection failed, error (403)"

Permission denied:

  1. Check token permissions (needs repo scope)
  2. Verify you have write access to the repository
  3. Check if branch protection prevents direct pushes

"Failed to update GitHub, error: ..."

General error:

  1. Review the error message details
  2. Check GitHub status
  3. Verify repository and branch exist
  4. Ensure branch is not protected against direct pushes

What's NOT Committed

The following are never stored in GitHub:

Item Reason
User records Security - contains passwords
Session data Transient data
License info Environment-specific
Setup configuration Contains sensitive settings
GitHub credentials Security

Overwriting Warning

Important: Commit operations overwrite files in GitHub.

If you have local changes in GitHub that haven't been pulled:

  1. Those changes may be overwritten
  2. Consider pulling first if uncertain
  3. Use branches to protect work in progress