Working with Branches

This page explains how to use GitHub branches to manage different environments like sandbox and production.

Why Use Branches?

Branches allow you to:

Maintain separate configurations for each environment
Develop and test safely before production deployment
Roll back to previous states if needed
Collaborate without affecting live portals

Branch Strategy

Recommended Setup

Branch	Purpose	Environment
`main`	Production-ready configuration	Production BC
`develop`	Active development	Sandbox BC
`feature/*`	Specific features	Local/Sandbox

Branch Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                         Branch Workflow                                  │
└─────────────────────────────────────────────────────────────────────────┘

  ┌──────────┐                                           ┌──────────────┐
  │ Sandbox  │──── Commit ────►  develop  ─── Merge ───► │     main     │
  │   BC     │                                           │   (GitHub)   │
  └──────────┘                                           └──────────────┘
                                                                │
                                                                │ Pull
                                                                ▼
                                                         ┌──────────────┐
                                                         │  Production  │
                                                         │     BC       │
                                                         └──────────────┘

Setting Up Multiple Branches

Create Branches in GitHub

Go to your repository on GitHub
Click the branch dropdown (shows current branch name)
Type a new branch name (e.g., develop)
Click Create branch: develop from main

Configure Each Environment

Sandbox Environment:

Open the Advanced Portal Designer menu page and click Setup
Set GitHub Branch to develop
Commit and pull work in progress

Production Environment:

Open the Advanced Portal Designer menu page and click Setup
Set GitHub Branch to main
Only pull approved changes

Typical Workflow

Development Phase

Work in sandbox Business Central
Create/modify actions, templates, content
Test thoroughly in sandbox
Commit to GitHub (pushes to develop branch)

Review Phase

Go to GitHub repository
Create a Pull Request from develop to main
Review the changes
(Optional) Have team member approve

Deployment Phase

Merge the Pull Request in GitHub
Open production Business Central
Pull from GitHub (pulls from main branch)
Verify portal works correctly

Switching Branches

Change Branch in APD

To switch which branch APD uses:

Open the Advanced Portal Designer menu page and click Setup
Change the GitHub Branch field
Save the change

Warning: After switching branches, pull to synchronize with that branch.

Example: Check Production State

To see production configuration in sandbox:

Change branch to main
Pull from GitHub
Review the configuration
Change back to develop when done
Pull to restore development state

Merging Branches

Using GitHub Web Interface

Go to your repository
Click Pull requests → New pull request
Set base: main and compare: develop
Review the changes
Click Create pull request
Add description of changes
Click Merge pull request

Using GitHub Desktop

Open GitHub Desktop
Switch to main branch
Click Branch → Merge into current branch
Select develop
Click Create a merge commit
Push to GitHub

Handling Conflicts

What Causes Conflicts?

Conflicts occur when:

Same file changed in both branches
Changes to same action in different environments
Templates modified in multiple places

Resolving Conflicts

Open the Pull Request in GitHub
Click Resolve conflicts
Review the conflicting files
Choose which version to keep (or combine)
Mark as resolved
Complete the merge

Preventing Conflicts

Best practices to avoid conflicts:

Make all changes in sandbox first
Never modify production directly
Commit frequently
Communicate with team members

Advanced: Feature Branches

For larger changes, use feature branches:

Create Feature Branch

In GitHub, create branch feature/new-dashboard from develop
In sandbox, switch to feature/new-dashboard
Develop the new feature
Commit regularly

Merge Feature Branch

Create Pull Request: feature/new-dashboard → develop
Review and test
Merge to develop
Delete the feature branch

Environment Mapping

Simple Setup (2 Environments)

Environment	Branch
Sandbox	`develop`
Production	`main`

Complex Setup (Multiple)

Environment	Branch
Development	`develop`
QA/Testing	`qa`
Staging	`staging`
Production	`main`

Per-Customer Portals

Customer	Branch
Contoso Production	`main`
Contoso Sandbox	`develop`
Fabrikam Production	`fabrikam-main`
Fabrikam Sandbox	`fabrikam-dev`

Rollback Procedures

Revert a Merge

If a deployment causes issues:

In GitHub, go to the merge commit
Click Revert to create a revert commit
Pull in production to apply the revert

Restore from Previous Commit

Find the last known good commit in GitHub
Create a new branch from that commit
Merge that branch to main
Pull in production

Manual Rollback

In sandbox, switch to main branch
Pull the current production state
Make necessary fixes
Commit back to develop
Go through normal merge process

Best Practices

Commit Messages

Use clear descriptions in your external tracking:

✅ Good:
- Added customer dashboard with orders
- Fixed security profile for vendors
- Updated header template with new logo

❌ Avoid:
- Updates
- Fixed stuff
- Changes

Branch Hygiene

Delete merged feature branches
Keep develop and main clean
Regularly merge main back to develop to stay current

Testing Checklist

Before merging to production:

All actions compile successfully
Templates render correctly
Forms work as expected
Security restrictions apply properly
Content displays correctly