Simple Object Designer Documentation
Index

GitHub Configuration

This page explains how to configure Simple Object Designer to push code to GitHub.

Enabling GitHub Integration

In Setup

  1. Open Setup page
  2. Set GitHub Integration Mode to Source Repository/AL-Go! (the only non-disabled value)
  3. Additional fields appear

The GitHub Integration Mode option values are:

Value Behavior
None GitHub integration disabled (default)
Source Repository/AL-Go! Push generated AL source to GitHub on publish; layout works for both plain source repos and AL-Go for GitHub projects

Configuration Fields

Field Description
GitHub Personal Token GitHub PAT with repo access
GitHub Account Name Your GitHub username or organisation
GitHub Repository Repository name
GitHub Branch Target branch
GitHub Subfolder Optional subfolder path within the repo (trailing / is added automatically). In Dual-App mode SOD also commits to app1/ and app2/ subfolders inside this path.

Creating a Personal Access Token

In GitHub

  1. Go to GitHub.com and sign in
  2. Click profile icon > Settings
  3. Scroll to "Developer settings"
  4. Click "Personal access tokens" > "Tokens (classic)"
  5. Click "Generate new token (classic)"

Token Configuration

Setting Value
Note "SOD Integration" (or similar)
Expiration Choose appropriate period
Scopes Select repo (full control)

After Generation

  1. Copy the token immediately
  2. Store securely (won't be shown again)
  3. Paste into SOD's Personal Access Token field

Repository Setup

Creating a Repository

If you need a new repository:

  1. Go to GitHub.com
  2. Click "+" > "New repository"
  3. Enter repository name
  4. Choose public or private
  5. Initialize with README (optional)
  6. Create repository

Using Existing Repository

If using existing repository:

  • Ensure you have push access
  • Note the exact repository name
  • Decide on branch and folder

Configuration Fields Explained

GitHub Account

Your GitHub username:

  • Case sensitive
  • Without @ symbol
  • Example: johndoe

Repository

Repository name only:

  • Not the full URL
  • Not including username
  • Example: bc-customizations

Branch

Target branch for commits:

  • Usually main or master
  • Can be feature branch
  • Must exist in repository

GitHub Subfolder

Optional subfolder:

  • Path within repository
  • Useful for monorepos
  • Example: src/extension
  • Leave blank for root
  • A trailing / is appended automatically on save — you don't have to type it
  • In Dual-App mode the two apps are committed under app1/ and app2/ inside this path

Testing the Connection

Publish to GitHub

The GitHub commit is part of the normal Publish flow — there is no separate "Publish to GitHub" action. When GitHub Integration Mode is set, SOD pushes the generated source on every publish.

  1. Configure all settings above
  2. Run the normal Publish action
  3. Check for errors
  4. Verify in GitHub

Verification

In GitHub:

  1. Open your repository
  2. Navigate to configured folder
  3. Verify files appear
  4. Check commit message

Troubleshooting Configuration

Authentication Failed

Causes:

  • Wrong username
  • Invalid/expired token
  • Token lacks permissions

Solutions:

  • Verify username spelling
  • Generate new token
  • Ensure repo scope selected

Repository Not Found

Causes:

  • Wrong repository name
  • Case sensitivity
  • No access to repository

Solutions:

  • Check exact repository name
  • Verify case matches
  • Confirm you have access

Branch Not Found

Causes:

  • Branch doesn't exist
  • Wrong branch name

Solutions:

  • Create branch in GitHub first
  • Verify branch name exactly

Subfolder Issues

Causes:

  • Invalid path format
  • Permissions issues

Solutions:

  • Use forward slashes
  • Don't start with /
  • A trailing / is appended for you, so src/extension and src/extension/ are equivalent
  • Create folder structure in GitHub first if needed

AL1043: The runtime version is not supported by the AL compiler

Symptom: an AL-Go / CI-CD build step fails with AL1043 The runtime version 'X.0' is not supported by the AL compiler.

Cause: SOD populates the runtime and application versions in the generated app.json automatically — they are not configurable in SOD's setup — and a known defect produced an incompatible combination that the AL compiler rejects.

Fix: update SOD to the current version via AppSource, then publish again. See Updating SOD.

Do not hand-edit app.json in the repository. SOD overwrites it on every publish, so the manual change is reverted and the build breaks again at the next push.

Security Considerations

Token Security

  • Don't share your token
  • Use appropriate expiration
  • Rotate tokens periodically
  • Revoke if compromised

Repository Visibility

Consider:

  • Private for proprietary code
  • Public for open source
  • Access controls for team

Token Permissions

Only grant needed permissions:

  • repo scope is typical
  • Avoid admin scopes
  • Review periodically

Best Practices

Token Management

  • Use descriptive token names
  • Set reasonable expiration
  • Rotate tokens regularly
  • Track which tokens are active

Repository Organization

  • Dedicated repository for SOD
  • Or specific folder in project
  • Clear naming conventions

Regular Pushes

  • Push after significant changes
  • Before publishing to production
  • Maintain regular backups