Delivery Targets - AL-Go for GitHub

Delivery Targets in AL-Go for GitHub enable you to automatically publish your Business Central applications to various package repositories and storage systems. This facilitates app distribution, dependency management, and partner collaboration.

Overview

AL-Go supports delivery to multiple target types:

GitHub Packages

Free NuGet feed provided by GitHub for each organization. Ideal for internal distribution and dependency management.

Custom NuGet Feeds

Azure DevOps Artifacts, private NuGet servers, or other custom NuGet v3 feeds.

Azure Storage

Publish artifacts to Azure Storage accounts for archival or custom distribution workflows.

Microsoft AppSource

Submit applications to Microsoft AppSource for public distribution.

NuGet and GitHub Packages delivery is currently experimental. While stable and used in production, the package structure and configuration may change in future versions.

Delivery Targets Concept

Each delivery target is configured through:

Context Secret: A secret named <DeliveryTarget>Context containing connection information
Delivery Script: An optional PowerShell script named DeliverTo<DeliveryTarget>.ps1 for custom logic
Settings: Optional configuration in AL-Go settings files

Supported Targets

Target	Purpose	Context Secret	Status
GitHubPackages	GitHub Packages NuGet feed	`GitHubPackagesContext`	✅ Experimental
NuGet	Custom NuGet feed	`NuGetContext`	✅ Experimental
Storage	Azure Storage Account	`StorageContext`	✅ Stable
AppSource	Microsoft AppSource	`AppSourceContext`	✅ Stable

GitHub Packages Setup

GitHub Packages provides a free NuGet feed for each GitHub organization, making it the recommended approach for most Per-Tenant Extension (PTE) scenarios.

Create Personal Access Token

Generate a token with package permissions:

Navigate to GitHub Personal Access Tokens
Create a Classic Personal Access Token (fine-grained tokens don’t support packages yet)
Select the following scopes:
- write:packages - Required for publishing packages
- read:packages - Required for consuming packages
- repo - Required if your repositories are private
Set an appropriate expiration date
Generate and copy the token

Store the token securely. You won’t be able to see it again after leaving the page.

Create GitHubPackagesContext Secret

Create an organizational or repository secret:

Navigate to Settings → Secrets and variables → Actions
Click New organization secret (or New repository secret)
Name: GitHubPackagesContext
Value: Compressed JSON with token and server URL

{"token":"ghp_<your_token>","serverUrl":"https://nuget.pkg.github.com/<your_org>/index.json"}

Replace:

<your_token>: Your personal access token
<your_org>: Your GitHub organization name

Use the BcContainerHelper function New-ALGoNuGetContext to generate correctly formatted JSON:

New-ALGoNuGetContext -token "ghp_..." -serverUrl "https://nuget.pkg.github.com/myorg/index.json"

Configure Repository Settings (Optional)

Control delivery behavior in your AL-Go settings file:

{
  "DeliverToGitHubPackages": {
    "ContinuousDelivery": true,
    "Branches": ["main", "release/*"]
  }
}

Configuration options:

ContinuousDelivery: Enable automatic delivery on successful builds
Branches: Array of branch patterns that trigger delivery

See DeliverTo settings for all options.

Verify Setup

After creating the secret:

Push a commit to a configured branch
Monitor the CI/CD workflow run
Look for “Deliver to GitHubPackages” job
Check your organization’s Packages tab for published packages
Verify package metadata and version

Consuming GitHub Packages

GitHub Packages are automatically available for dependency resolution. When your apps reference dependencies published to your organization’s GitHub Packages feed, AL-Go will automatically resolve and download them. No additional configuration required - AL-Go uses the GitHubPackagesContext secret for both publishing and consuming packages.

Custom NuGet Feed Setup

For Azure DevOps Artifacts, private NuGet servers, or other custom feeds:

Obtain Feed Credentials

Get authentication credentials for your NuGet feed:Azure DevOps:

Navigate to User Settings → Personal Access Tokens
Create new token with Packaging: Read & write scope
Copy the token value

Private NuGet Server:

Use API key or credentials provided by your server administrator

Get Feed URL

Locate your NuGet v3 feed URL:Common formats:

Azure DevOps: https://pkgs.dev.azure.com/<org>/<project>/_packaging/<feedName>/nuget/v3/index.json
GitHub Packages: https://nuget.pkg.github.com/<org>/index.json
NuGet.org: https://api.nuget.org/v3/index.json
Private server: Contact your administrator

Create NuGetContext Secret

Create a repository or organization secret:Name: NuGetContextValue: Compressed JSON with credentials

{"token":"<YOUR_NUGET_TOKEN>","serverUrl":"https://pkgs.dev.azure.com/<org>/<project>/_packaging/<feed>/nuget/v3/index.json"}

Example for Azure DevOps:

{"token":"abc123xyz","serverUrl":"https://pkgs.dev.azure.com/contoso/BusinessCentral/_packaging/BC-Apps/nuget/v3/index.json"}

Configure Dependency Resolution (Optional)

Unlike GitHub Packages, custom NuGet feeds are not automatically used for dependency resolution. Add your feed to trustedNuGetFeeds:

{
  "trustedNuGetFeeds": [
    {
      "url": "https://pkgs.dev.azure.com/<org>/<project>/_packaging/<feed>/nuget/v3/index.json",
      "authTokenSecret": "NuGetContext",
      "patterns": ["*"]
    }
  ]
}

Parameters:

url: NuGet feed URL
authTokenSecret: Name of the secret containing credentials
patterns: Array of package name patterns (e.g., ["Contoso.*", "Fabrikam.*"])

Configuration Examples

Example 1: GitHub Packages for PTE Organization

Scenario: A company developing Per-Tenant Extensions wants to automatically publish apps to GitHub Packages for internal distribution. Organizational Secret: GitHubPackagesContext

{"token":"ghp_1234567890abcdef","serverUrl":"https://nuget.pkg.github.com/contoso/index.json"}

AL-Go-Settings.json:

{
  "DeliverToGitHubPackages": {
    "ContinuousDelivery": true,
    "Branches": ["main"]
  }
}

Result: Every successful build on the main branch automatically publishes packages to GitHub Packages.

Example 2: Azure DevOps Artifacts for PTE Development

Scenario: A partner with existing Azure DevOps infrastructure wants to deliver PTEs to Azure DevOps Artifacts. Repository Secret: NuGetContext

{"token":"<AZURE_DEVOPS_PAT>","serverUrl":"https://pkgs.dev.azure.com/contoso/BusinessCentral/_packaging/BC-Apps/nuget/v3/index.json"}

AL-Go-Settings.json:

{
  "DeliverToNuGet": {
    "ContinuousDelivery": true,
    "Branches": ["main", "release/*"]
  },
  "trustedNuGetFeeds": [
    {
      "url": "https://pkgs.dev.azure.com/contoso/BusinessCentral/_packaging/BC-Apps/nuget/v3/index.json",
      "authTokenSecret": "NuGetContext",
      "patterns": ["Contoso.*"]
    }
  ]
}

Result: Packages are published to Azure DevOps Artifacts and available for dependency resolution.

Example 3: Multi-Environment PTE Setup

Scenario: Publish development builds to GitHub Packages and production releases to a private NuGet feed. Secrets:

GitHubPackagesContext: For development builds
NuGetContext: For production releases

AL-Go-Settings.json:

{
  "DeliverToGitHubPackages": {
    "ContinuousDelivery": true,
    "Branches": ["develop", "feature/*"]
  },
  "DeliverToNuGet": {
    "ContinuousDelivery": true,
    "Branches": ["main"]
  },
  "trustedNuGetFeeds": [
    {
      "url": "https://pkgs.dev.azure.com/contoso/BC/_packaging/Production/nuget/v3/index.json",
      "authTokenSecret": "NuGetContext",
      "patterns": ["Contoso.*"]
    }
  ]
}

Result:

Development branches → GitHub Packages
Main branch → Private NuGet feed

Example 4: Multiple Feed Configuration

Scenario: Use multiple NuGet feeds for different package sources. AL-Go-Settings.json:

{
  "trustedNuGetFeeds": [
    {
      "url": "https://nuget.pkg.github.com/contoso/index.json",
      "authTokenSecret": "GitHubPackagesContext",
      "patterns": ["Contoso.*"]
    },
    {
      "url": "https://pkgs.dev.azure.com/contoso/BC/_packaging/External/nuget/v3/index.json",
      "authTokenSecret": "AzureDevOpsContext",
      "patterns": ["External.*", "Partner.*"]
    },
    {
      "url": "https://api.nuget.org/v3/index.json",
      "patterns": ["Newtonsoft.*"]
    }
  ]
}

Result: AL-Go resolves dependencies from multiple feeds based on package name patterns.

Custom Delivery Scripts

For advanced scenarios, create custom delivery scripts to implement specialized delivery logic.

Create Delivery Script

Create a PowerShell script in your .github folder:File: .github/DeliverToCustomFeed.ps1

Param(
    [Parameter(Mandatory = $true)]
    [HashTable] $parameters
)

# Extract parameters
$project = $parameters.project
$projectName = $parameters.projectName
$type = $parameters.type
$appsFolder = $parameters.appsFolder

# Custom delivery logic
Write-Host "Delivering project '$projectName' (type: $type) to custom feed"

if ($appsFolder) {
    Get-ChildItem -Path $appsFolder -Filter "*.app" | ForEach-Object {
        Write-Host "Processing app: $($_.Name)"
        # Your custom delivery logic here
    }
}

Create Context Secret

Create a secret named CustomFeedContext with your custom configuration:

{"customField1":"value1","customField2":"value2"}

Access the secret in your script:

$context = $parameters.context | ConvertFrom-Json
$customValue = $context.customField1

Configure AL-Go Settings

Enable continuous delivery to your custom target:

{
  "DeliverToCustomFeed": {
    "ContinuousDelivery": true,
    "Branches": ["main"]
  }
}

Script Parameters

Your delivery script receives a hashtable with the following parameters:

Parameter	Type	Description
`project`	string	Project path (escaped for artifact naming)
`projectName`	string	Project name (sanitized for paths)
`type`	string	Delivery type: “CD” or “Release”
`appsFolder`	string	Path to folder containing .app files
`testAppsFolder`	string	Path to test app files (if available)
`dependenciesFolder`	string	Path to dependency files (if available)
`appsFolders`	string[]	Array of all app folders from different build modes
`testAppsFolders`	string[]	Array of all test app folders
`dependenciesFolders`	string[]	Array of all dependency folders

Folder parameters may be $null if no artifacts of that type were found. Use null checks before accessing folders.

Branch-Specific Delivery

Configure different delivery targets for different branches:

{
  "DeliverToGitHubPackages": {
    "ContinuousDelivery": true,
    "Branches": ["develop", "feature/*"]
  },
  "DeliverToNuGet": {
    "ContinuousDelivery": true,
    "Branches": ["main", "release/*"]
  },
  "DeliverToStorage": {
    "ContinuousDelivery": true,
    "Branches": ["main"]
  }
}

Use cases:

Feature branches: Deliver to development feed for testing
Main branch: Deliver to production feed
Release branches: Deliver to staging feed for validation

Troubleshooting

Missing Context Secret

Error: Secret 'GitHubPackagesContext' not foundSolutions:

Verify secret exists at organization or repository level
Check secret name matches exactly (case-sensitive)
Ensure repository has access to organization secrets
Confirm secret is not expired (for PATs)

Authentication Failed

Error: 401 Unauthorized when publishing packagesSolutions:

Verify PAT has correct scopes (write:packages, read:packages)
Check if token has expired
Ensure token has access to target organization
Confirm server URL is correct
Validate JSON format (must be compressed)

Package Not Found

Error: Unable to find package during dependency resolutionSolutions:

Verify package was published successfully
Check trustedNuGetFeeds configuration
Ensure package name matches app.json dependencies
Confirm package version exists
Verify feed URL is accessible

Curly Brackets Masked

Error: Seeing *** instead of JSON in logsSolutions:

Ensure JSON is compressed (single line)
Remove all newlines and extra whitespace
Use New-ALGoNuGetContext to generate correct format
Validate JSON syntax before creating secret

Debugging Steps

Check Workflow Logs

Review the CI/CD workflow for delivery job:

Navigate to Actions → Select workflow run
Look for “Deliver to [Target]” job
Review step outputs for errors
Check for authentication failures

Verify Package Publication

Confirm packages were published:

GitHub Packages: Organization → Packages tab
Azure DevOps: Artifacts → Feed → Packages
Custom feed: Use feed’s web interface

Test Dependency Resolution

Verify dependency resolution works:

Check workflow logs for “Resolving Dependencies”
Look for “Installing app dependencies” messages
Verify correct package versions are downloaded
Check for authentication errors

Validate Secret Format

Use PowerShell to validate JSON:

# Test JSON parsing
$json = '{"token":"test","serverUrl":"https://example.com"}'
$json | ConvertFrom-Json

# Generate correct format
New-ALGoNuGetContext -token "ghp_..." -serverUrl "https://..."

Security Best Practices

Token Scopes

Grant minimum permissions:

GitHub Packages: write:packages, read:packages only
Azure DevOps: Packaging (Read & Write) scope
Avoid granting repo scope unless necessary
Use fine-grained tokens when available

Secret Storage

Use appropriate secret levels:

Organization secrets for shared feeds
Repository secrets for project-specific feeds
Environment secrets for environment-specific delivery
Azure Key Vault for sensitive credentials

Token Rotation

Regular credential updates:

Rotate PATs every 90 days
Set expiration dates on all tokens
Monitor token usage
Revoke unused tokens

Access Control

Limit feed access:

Use dedicated service accounts
Implement feed permissions
Audit package access
Monitor download patterns

Limitations and Considerations

Known Limitations:

Fine-grained tokens: GitHub Packages doesn’t support fine-grained PATs yet (use classic tokens)
Package visibility: GitHub Packages inherit repository visibility
Retention policies: Consider feed retention policies and storage costs
Version conflicts: Duplicate versions may cause resolution issues
Feed limits: Some feeds have package count or size limits

Best Practices

Use semantic versioning: Follow semver (e.g., 1.2.3) for all packages
Test in isolation: Validate delivery configuration in test repositories first
Monitor package sizes: Be aware of feed storage limits
Document dependencies: Maintain clear dependency documentation
Implement cleanup: Set up package retention and cleanup policies
Version consistency: Ensure app.json versions match package versions
Feed organization: Use separate feeds for dev, test, and production

Next Steps

Continuous Deployment

Learn about automated deployment strategies

Sandbox Environment

Set up sandbox environments for testing

AL-Go Settings

Explore all configuration options

AL-Go Secrets

Learn about secret management

Getting Started

Setup & Configuration

Core Workflows

Development

Deployment

AppSource Publishing

Advanced Topics

Migration

​Overview

GitHub Packages

Custom NuGet Feeds

Azure Storage

Microsoft AppSource

​Delivery Targets Concept

​Supported Targets

​GitHub Packages Setup

​Consuming GitHub Packages

​Custom NuGet Feed Setup

​Configuration Examples

​Example 1: GitHub Packages for PTE Organization

​Example 2: Azure DevOps Artifacts for PTE Development

​Example 3: Multi-Environment PTE Setup

​Example 4: Multiple Feed Configuration

​Custom Delivery Scripts

​Script Parameters

​Branch-Specific Delivery

​Troubleshooting

Missing Context Secret

Authentication Failed

Package Not Found

Curly Brackets Masked

​Debugging Steps

​Security Best Practices

Token Scopes

Secret Storage

Token Rotation

Access Control

​Limitations and Considerations

​Best Practices

​Next Steps

Continuous Deployment

Sandbox Environment

AL-Go Settings

AL-Go Secrets

Build docs developers (and LLMs) love

Overview

Delivery Targets Concept

Supported Targets

GitHub Packages Setup

Consuming GitHub Packages

Custom NuGet Feed Setup

Configuration Examples

Example 1: GitHub Packages for PTE Organization

Example 2: Azure DevOps Artifacts for PTE Development

Example 3: Multi-Environment PTE Setup

Example 4: Multiple Feed Configuration

Custom Delivery Scripts

Script Parameters

Branch-Specific Delivery

Troubleshooting

Debugging Steps

Security Best Practices

Limitations and Considerations

Best Practices

Next Steps