Advanced Portal Designer Documentation
Index

GitHub Setup

This page explains how to configure GitHub integration in APD.

Prerequisites

Before configuring GitHub integration:

  1. GitHub account (personal or organization)
  2. A repository with at least one file (not empty)
  3. Personal Access Token with appropriate permissions
  4. Allow HttpClient Requests enabled for APD extension

Creating a Personal Access Token

APD uses Personal Access Tokens (PAT) to authenticate with GitHub.

Classic Token (Simplest)

  1. Go to GitHub Settings
  2. Click Generate new token → Generate new token (classic)
  3. Enter a descriptive note (e.g., "APD Portal Designer")
  4. Set expiration (recommend 90 days or custom)
  5. Select scopes:
    • ✅ repo (Full control of private repositories)
  6. Click Generate token
  7. Copy the token immediately (you won't see it again!)

Fine-Grained Token (More Secure)

For enhanced security, use fine-grained tokens:

  1. Go to GitHub Settings
  2. Click Generate new token
  3. Enter token name and expiration
  4. Under Repository access, select Only select repositories
  5. Choose your portal repository
  6. Under Permissions → Repository permissions:
    • Contents: Read and write
    • Metadata: Read-only (required)
  7. Click Generate token
  8. Copy the token immediately

APD Configuration

Accessing Setup

  1. Open the Advanced Portal Designer menu page (search for it in Tell Me)
  2. Click Setup to open the APD Setup card
  3. Fill in the GitHub fields (GitHub Account Name, GitHub Personal Token, GitHub Repository, GitHub Branch)

Configuration Fields

Field Description Example
GitHub Account Name Your GitHub username or organization name mycompany
GitHub Personal Token The PAT you generated ghp_xxxx...
GitHub Repository Repository name (without owner) portal-config
GitHub Branch Branch to use for commits/pulls main

Example Configuration

GitHub Account Name:   contoso
GitHub Personal Token: ghp_1234567890abcdefghij...
GitHub Repository:     customer-portal
GitHub Branch:         main

Finding Your Values

Account Name:

  • For personal accounts: Your GitHub username
  • For organizations: The organization name
  • Example: In https://github.com/contoso/portal-config, account name is contoso

Repository:

  • Just the repository name, not the full URL
  • Example: In https://github.com/contoso/portal-config, repository is portal-config

Verifying Configuration

Test the Connection

After configuration:

  1. On the Setup page, click Commit to GitHub
  2. Confirm the action when prompted
  3. If successful, you'll see "GitHub updated!"
  4. Check your GitHub repository for the new files

Common Verification Errors

Error Solution
"Your GitHub setup is incomplete" Fill in all four GitHub fields
"Cannot publish to a complete empty repository" Add a README to your repo first
"GitHub Account Name or Repository does not seem to be correct" Verify account and repo names
"GitHub Connection failed, error (401)" Token is invalid or expired
"GitHub Connection failed, error (403)" Token lacks required permissions
"GitHub Connection failed, error (404)" Repository not found or no access

Token Management

Token Security

  • Store tokens securely
  • Never commit tokens to repositories
  • Use different tokens for different environments
  • Set appropriate expiration dates

Rotating Tokens

When tokens expire or need rotation:

  1. Generate a new token in GitHub
  2. Update the GitHub Personal Token field in APD Setup
  3. Delete the old token in GitHub

Revoking Access

If a token is compromised:

  1. Go to GitHub Token Settings
  2. Click Delete next to the compromised token
  3. Generate a new token
  4. Update APD with the new token

Repository Preparation

Required: Non-Empty Repository

APD cannot push to an empty repository. Ensure your repo has at least one file:

  1. When creating: Check Add a README file
  2. For existing empty repos: Add any file through GitHub web interface

For production branches, consider:

  1. Go to Settings → Branches
  2. Add a branch protection rule for main
  3. Consider requiring pull request reviews

For portal configurations:

  1. Keep repositories private
  2. Only grant access to authorized personnel
  3. Use organization repositories for teams

Multiple Environments

Different Branches for Environments

Configure each environment to use a different branch:

Environment Branch Purpose
Development develop Active development
Sandbox staging Testing before production
Production main Live portal

Switching Branches

To change the target branch:

  1. Open the Advanced Portal Designer menu and click Setup
  2. Change the GitHub Branch field
  3. Pull or commit to synchronize

Troubleshooting

"Allow HttpClient Requests" Error

If you see this error:

  1. Go to Extension Management
  2. Find Advanced Portal Designer
  3. Click Configure
  4. Enable Allow HttpClient Requests

Connection Timeouts

If GitHub operations timeout:

  1. Check your internet connection
  2. Verify GitHub status at githubstatus.com
  3. Try again in a few minutes

Token Expired

If operations fail with 401 errors:

  1. Check token expiration in GitHub
  2. Generate a new token
  3. Update APD configuration