Advanced Portal Designer Documentation
Index

Pulling from GitHub

This page explains how to pull portal configuration from GitHub into Business Central.

What Gets Pulled?

When you pull from GitHub, APD imports:

Component Source Action
Actions Tables/Table_APD Action.json Replaces all actions
DataItems Tables/Table_APD Action DataItem*.json Replaces configurations
Filters Tables/Table_APD DataItem Filter 2.json Replaces filters
Security Profiles Tables/Table_APD Security Profile.json Replaces profiles
Security Filters Tables/Table_APD Security Setup.json Replaces filters
Content Types Tables/Table_APD Content Type.json Replaces types
Content `Content/{lang}/*.md .html` Replaces content
Templates Templates/* Creates/updates templates

How to Pull

From APD Setup Page

  1. Open the Advanced Portal Designer menu page (search for it in Tell Me) and click Setup
  2. Click Pull from GitHub in the action bar
  3. Confirm when prompted: "Pull everything from branch {branch} in GitHub repository {repo}?"
  4. Wait for the import to complete
  5. Actions are automatically compiled after import

Pull Process

When you pull, APD:

  1. Retrieves the file list from the configured branch
  2. Downloads and parses each JSON table file
  3. Deletes existing records in the table
  4. Imports the new records
  5. Downloads and imports templates
  6. Downloads and imports content
  7. Compiles all actions

Important Warning

⚠️ Pull Replaces Everything

The pull operation replaces existing data:

  • All existing actions are deleted first
  • All existing security profiles are deleted first
  • Templates and content are overwritten

This is destructive! Any local changes not committed to GitHub will be lost.

Before Pulling

Always:

  1. Commit first if you have local changes you want to keep
  2. Verify you're pulling from the correct branch
  3. Understand that local modifications will be lost

Automatic Compilation

After pulling, APD automatically compiles all actions:

  • Template references are validated
  • Action configurations are verified
  • Errors appear in the compilation log

If compilation fails:

  1. Check the action list for errors
  2. Review template names for typos
  3. Verify all referenced templates exist

Use Cases

Synchronizing Environments

Pull to update an environment:

1. Commit from Sandbox to GitHub (develop branch)
2. Merge develop to main in GitHub
3. Pull from GitHub (main branch) to Production

Restoring from Backup

If you need to restore:

  1. Identify the commit to restore from
  2. Create a branch from that commit (in GitHub)
  3. Configure APD to use that branch
  4. Pull to restore the configuration

Setting Up New Environment

For a fresh environment:

  1. Install APD
  2. Configure GitHub settings
  3. Pull to import all configuration
  4. Review and test

Handling Conflicts

Local Changes vs GitHub

If you have uncommitted local changes:

Scenario Recommendation
Keep local Commit before pulling
Discard local Pull will overwrite
Merge manually Commit first, then review in GitHub

Template Not Found After Pull

If actions fail to compile due to missing templates:

  1. Check the Templates/ folder in GitHub
  2. Verify template names match exactly
  3. Check for language folder structure

Pull Behavior Details

Tables

For each table JSON file:

  1. Parse the JSON structure
  2. Delete all existing records in the table
  3. Insert records from JSON
  4. Field values are mapped by field number

Templates

For each template file:

  1. Check if template exists by name (and language)
  2. Create if new, update if exists
  3. Template name = filename (no extension)
  4. Language = subfolder name (empty for default)

Content

For each content file:

  1. Parse the path: Content/{language}/{name}.{ext}
  2. Create or update content record
  3. Determine style from extension (.md = Markdown, .html = HTML)
  4. Import the text content

Error Handling

"GitHub Account Name or Repository does not seem to be correct"

Verify configuration:

  1. Check GitHub Account Name matches your username/org
  2. Check Repository name is correct (without owner prefix)
  3. Ensure you have access to the repository

"GitHub Connection failed"

Network or authentication issue:

  1. Check internet connectivity
  2. Verify token is valid
  3. Check GitHub status

Compilation Errors After Pull

If actions fail to compile:

  1. From the Advanced Portal Designer menu page click Actions
  2. Look for actions with errors
  3. Use the action's Compile action to see the error detail
  4. Verify template references

Best Practices

Test in Sandbox First

Before pulling to production:

  1. Pull to sandbox environment
  2. Test all portal functionality
  3. Verify actions compile correctly
  4. Then pull to production

Backup Before Pull

Consider exporting current state:

  1. Commit current configuration first
  2. Then pull new changes
  3. This creates a recovery point

Verify Branch

Double-check you're pulling from the correct branch:

  • develop for development work
  • main for production-ready configuration

What's NOT Pulled

These items are not affected by pull:

Item Reason
User records Not stored in GitHub
Session data Transient
License info Environment-specific
Setup configuration Local settings
GitHub settings Configuration stays