Advanced Portal Designer Documentation
Index

GitHub Integration Overview

APD includes built-in GitHub integration that allows you to version control your entire portal configuration. This enables backup, collaboration, and environment synchronization.

What Gets Synchronized?

GitHub integration synchronizes all portal components:

Component Storage Location Format
Actions Tables/ folder JSON
DataItem configurations Tables/ folder JSON
Security Profiles Tables/ folder JSON
Security Filters Tables/ folder JSON
Content Types Tables/ folder JSON
Content Items Content/ folder .md or .html
Templates Templates/ folder HTML

Repository Structure

When you commit to GitHub, APD creates this folder structure:

your-repo/
├── Tables/
│   ├── Table_APD Action.json
│   ├── Table_APD Action DataItem.json
│   ├── Table_APD Action DataItem Col. 2.json
│   ├── Table_APD DataItem Filter 2.json
│   ├── Table_APD Security Profile.json
│   ├── Table_APD Security Setup.json
│   ├── Table_APD Content Type.json
│   ├── Table_APD Page Content.json
│   └── Table_APD Report Action Filter.json
├── Templates/
│   ├── header
│   ├── footer
│   ├── home
│   ├── customer-list
│   └── ENU/              # Language-specific templates
│       └── welcome
├── Content/
│   ├── 0/                # Default language (0)
│   │   ├── privacy-policy.md
│   │   └── faq.md
│   └── 1033/             # English (US) language
│       └── welcome.md

Key Benefits

Version Control

  • Track all changes over time
  • Review who changed what and when
  • Revert to previous versions if needed
  • Compare different versions

Backup & Recovery

  • Automatic off-site backup
  • Easy disaster recovery
  • Clone repository for new environments

Environment Synchronization

  • Use branches for different environments
  • Push from sandbox to production
  • Keep development and production in sync

Collaboration

  • Multiple developers can work together
  • Use pull requests for review
  • Document changes in commit messages

Workflow Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        Development Workflow                          │
└─────────────────────────────────────────────────────────────────────┘

┌──────────────┐     Commit     ┌──────────────┐     Pull      ┌──────────────┐
│   Sandbox    │  ──────────►   │    GitHub    │  ──────────►  │  Production  │
│   (develop)  │                │   (main)     │               │   (main)     │
└──────────────┘                └──────────────┘               └──────────────┘
       ▲                               │
       │                               │
       └───────────────────────────────┘
                  Pull (update local)

Security Considerations

What's NOT Synchronized

For security, these items are NOT stored in GitHub:

  • User records and passwords
  • Session data
  • License information
  • GitHub credentials
  • Setup configuration (except portal structure)

Token Security

  • Use Personal Access Tokens (PAT) with minimal permissions
  • Rotate tokens periodically
  • Consider using fine-grained tokens
  • Never share tokens

Prerequisites

Before setting up GitHub integration:

  1. GitHub Account - Personal or organization account
  2. Repository - An existing repository (can be private)
  3. Personal Access Token - With appropriate permissions
  4. HttpClient Access - Must be enabled for the extension

Getting Started

  1. Create a GitHub repository
  2. Generate a Personal Access Token
  3. Configure APD GitHub settings
  4. Make your first commit

Creating a Repository

  1. Go to github.com
  2. Click + → New repository
  3. Enter repository name (e.g., my-company-portal)
  4. Choose Private for internal portals
  5. Check Add a README file (required - cannot push to empty repo)
  6. Click Create repository

Important: The repository must have at least one file. APD cannot push to a completely empty repository.

Use Cases

Single Environment

For simple setups with one environment:

Business Central → GitHub (main branch)
  • Use as backup
  • Track changes over time

Sandbox to Production

For controlled deployments:

Sandbox ──► GitHub (develop) ──► GitHub (main) ──► Production
  • Develop in sandbox
  • Commit to develop branch
  • Merge to main when ready
  • Pull from main to production

Multiple Portals

For organizations with multiple portals:

Portal A → Repo A
Portal B → Repo B
  • Separate repositories per portal
  • Or use folders within one repository