Publish to Environment - AL-Go for GitHub

The Publish to Environment workflow enables on-demand deployment of your Business Central applications to specific environments. Unlike the automatic deployments in CI/CD, this workflow gives you full control over what version gets deployed and where.

Overview

Use this workflow to:

Deploy specific versions to any environment
Test releases before production deployment
Promote artifacts across environments (DEV → QA → PROD)
Create environments dynamically if they don’t exist
Deploy PR builds for testing specific changes

Triggering the Workflow

This workflow must be triggered manually from the GitHub Actions interface.

Navigate to Actions

Go to your repository on GitHub and click the Actions tab.

Select Publish To Environment

Click on Publish To Environment in the workflows list.

Run Workflow

Click Run workflow and configure the deployment parameters.

Workflow Parameters

appVersion

string

default:"current"

App version to deploySpecifies which version to deploy:

current: Latest build from the current branch
latest: Most recent successful build
prerelease: Latest prerelease version
draft: Latest draft release
1.0.0: Specific version number
PR_123: Build from pull request #123

Example: latest

environmentName

string

required

Environment maskTarget environment(s) for deployment:

*: All configured environments
PROD: Single environment named “PROD”
PROD*: All environments starting with “PROD”
QA,STAGING: Multiple specific environments (comma-separated)

Example: PROD

createEnvIfNotExists

boolean

default:"false"

Create environment if it does not existWhen true, creates the environment in GitHub and Business Central if missing.

Use with care. Requires environment secrets/variables to be configured:

{envName}_AuthContext
{envName}_EnvironmentName
{envName}_Scope

Example: false

Workflow Jobs

Initialization

Prepares the deployment and validates environment configuration.Actions Performed:

Reads AL-Go settings
Determines which environments match the environment mask
Validates environment configuration
Checks authentication contexts
Initiates device code flow if needed (for interactive auth)

Environment Matching: The workflow resolves environment masks to actual environments:

* matches all environments in .github/AL-Go-Settings.json
PROD* matches environments like PROD, PROD-EU, PROD-US
Specific names match exactly

If no authentication context is found for an environment, a device code flow is initiated, requiring manual authentication.

Deploy

Deploys artifacts to the matched environments.Deployment Process:

Get Artifacts: Downloads the specified version
Deploy to Business Central: Publishes apps to BC environment
Deploy to PowerPlatform: If configured, deploys PP solutions

Deployment Strategy:

Runs in parallel for multiple environments
Uses environment-specific settings and secrets
Supports both Business Central and PowerPlatform
Reports deployment URL in environment summary

Environment URL: After deployment, the workflow provides a link to the deployed environment.

Post-Process

Finalizes the workflow and reports telemetry.Always runs to ensure cleanup, even if deployment fails.

Environment Configuration

Setting Up Environments

Create GitHub Environment

In repository settings, navigate to Environments and create a new environment.Example: PROD

Add Authentication Secret

Add a secret to the environment or repository:Secret name: PROD-AuthContext or PROD_AuthContextSecret value (Service-to-Service):

{
  "tenantId": "your-tenant-id",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "scopes": "https://api.businesscentral.dynamics.com/.default"
}

Alternative (Username/Password - not recommended for production):

{
  "tenantId": "your-tenant-id",
  "username": "[email protected]",
  "password": "your-password"
}

Configure Environment Settings

Optionally add environment-specific variables:Variable name: ALGoEnvironmentSettingsVariable value:

{
  "environmentName": "MyProductionBC",
  "companyName": "CRONUS International Ltd.",
  "artifacts": "*"
}

Environment Authentication Methods

Service-to-Service (S2S)

Recommended for automationUses Azure AD app registration with client secret or certificate.

Secure and automated
No user interaction required
Supports certificate-based auth

Device Code Flow

Interactive authenticationInitiated when no auth context is found.

Requires manual login
Shows device code in workflow summary
Useful for one-time or test deployments

App Version Options

Deploying Different Versions

Latest Build
Current Branch
Specific Version
Pull Request
Prerelease

Deploy the most recent successful build:

appVersion: latest

This uses artifacts from the latest successful CI/CD workflow run.

Deploy from the current branch:

appVersion: current

Uses the latest build from the branch you’re currently on.

Deploy a specific release version:

appVersion: 1.0.0

Deploys artifacts from the GitHub release tagged 1.0.0.

Deploy from a pull request build:

appVersion: PR_42

Deploys artifacts from PR #42 (useful for testing before merge).

Deploy the latest prerelease:

appVersion: prerelease

Deploys artifacts from the most recent prerelease version.

Multi-Environment Deployment

Deploying to Multiple Environments

Use environment masks to deploy to multiple environments simultaneously:

environmentName: *

Each environment deployment runs in parallel, speeding up the process when deploying to multiple environments.

PowerPlatform Deployment

For Per-Tenant Extension repositories with PowerPlatform solutions:

Configure PowerPlatform

Ensure powerPlatformSolutionFolder is set in .github/AL-Go-Settings.json:

{
  "type": "PTE",
  "powerPlatformSolutionFolder": "PowerPlatformSolution"
}

Add PowerPlatform Auth

Include PowerPlatform credentials in the environment auth context:

{
  "tenantId": "your-tenant-id",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "scopes": "https://api.businesscentral.dynamics.com/.default",
  "ppEnvironmentUrl": "https://your-env.crm.dynamics.com"
}

Deploy

Run the workflow - PowerPlatform solutions deploy automatically after Business Central apps.

Dynamic Environment Creation

When createEnvIfNotExists is enabled, the workflow can create environments on-the-fly.

Requirements

For dynamic environment creation, configure these secrets/variables:

{envName}_AuthContext

secret

Authentication context for the environment (see format above).

{envName}_EnvironmentName

variable

Name of the Business Central environment to create.Example: MyNewEnvironment

{envName}_Scope

variable

Environment scope: Production or SandboxExample: Sandbox

Dynamic environment creation requires appropriate permissions in Business Central Admin Center.

Build Modes

The workflow respects build mode configuration for deployments:

Default: Standard build artifacts
Clean: Clean build artifacts
Translated: Localized/translated artifacts

Build mode is determined by environment-specific settings or defaults to Default.

Deployment Strategy

The workflow uses intelligent deployment strategies:

Dependency Order

Apps are deployed in dependency order:

Base/framework apps
Apps with dependencies on base apps
Apps with dependencies on other apps
Test apps (if included)

Upgrade vs. Install

Existing apps: Upgraded to new version
New apps: Installed for the first time
Removed apps: Not automatically uninstalled

Schema Sync

The deployment:

Synchronizes database schema
Runs data upgrade code
Validates compatibility

Monitoring Deployments

Workflow Output

The workflow provides detailed output:

Environment URL: Link to deployed environment
Deployment logs: Detailed logs for each app
Error messages: Clear error reporting if deployment fails
Artifact information: Which versions were deployed

GitHub Environments

Deployments appear in the Environments section:

View deployment history
See currently deployed versions
Access environment URLs
Review deployment protection rules

Permissions and Security

Required Permissions

permissions:
  actions: read          # Read workflow artifacts
  contents: read         # Read repository content
  id-token: write        # OIDC authentication
  pull-requests: read    # Read PR information (for PR builds)
  checks: read           # Read workflow check status

Environment Protection Rules

Configure protection rules in GitHub:

Required reviewers: Require approval before deployment
Wait timer: Delay deployment for a specified time
Deployment branches: Restrict which branches can deploy

Production environments should always have protection rules to prevent accidental deployments.

Example Scenarios

Scenario 1: Deploy Latest to Production

Run Workflow

appVersion: latest
environmentName: PROD
createEnvIfNotExists: false

Approve Deployment

If protection rules are configured, approve the deployment.

Verify

Check the environment URL to verify successful deployment.

Scenario 2: Test PR in Staging

Run Workflow

appVersion: PR_42
environmentName: STAGING
createEnvIfNotExists: false

Test Changes

Test the PR changes in the staging environment.

Approve PR

If tests pass, approve and merge the pull request.

Scenario 3: Deploy to All QA Environments

Run Workflow

appVersion: current
environmentName: QA*
createEnvIfNotExists: false

Monitor

Watch parallel deployments to all QA environments.

Troubleshooting

Authentication Failed

Verify the auth context secret is correctly formatted and has valid credentials. Check Azure AD app permissions.

Environment Not Found

Ensure the environment exists in GitHub settings and is listed in AL-Go-Settings.json.

Artifacts Not Found

Check that the specified appVersion exists. Verify workflow runs and releases.

Deployment Timeout

Large apps may timeout. Increase timeout or deploy in smaller batches.

Best Practices

Use Protection Rules

Always configure approval requirements for production environments.

Test Before Production

Deploy to staging/QA environments before production.

Use Specific Versions

For production, specify exact version numbers rather than “latest”.

Monitor Deployments

Watch the deployment logs and verify functionality after deployment.

Document Deployments

Use deployment comments to document what was deployed and why.

Getting Started

Setup & Configuration

Core Workflows

Development

Deployment

AppSource Publishing

Advanced Topics

Migration

​Overview

​Triggering the Workflow

​Workflow Parameters

​Workflow Jobs

​Environment Configuration

​Setting Up Environments

​Environment Authentication Methods

Service-to-Service (S2S)

Device Code Flow

​App Version Options

​Deploying Different Versions

​Multi-Environment Deployment

​Deploying to Multiple Environments

​PowerPlatform Deployment

​Dynamic Environment Creation

​Requirements

​Build Modes

​Deployment Strategy

​Dependency Order

​Upgrade vs. Install

​Schema Sync

​Monitoring Deployments

​Workflow Output

​GitHub Environments

​Permissions and Security

​Required Permissions

​Environment Protection Rules

​Example Scenarios

​Scenario 1: Deploy Latest to Production

​Scenario 2: Test PR in Staging

​Scenario 3: Deploy to All QA Environments

​Troubleshooting

Authentication Failed

Environment Not Found

Artifacts Not Found

Deployment Timeout

​Best Practices

Build docs developers (and LLMs) love

Overview

Triggering the Workflow

Workflow Parameters

Workflow Jobs

Environment Configuration

Setting Up Environments

Environment Authentication Methods

App Version Options

Deploying Different Versions

Multi-Environment Deployment

Deploying to Multiple Environments

PowerPlatform Deployment

Dynamic Environment Creation

Requirements

Build Modes

Deployment Strategy

Dependency Order

Upgrade vs. Install

Schema Sync

Monitoring Deployments

Workflow Output

GitHub Environments

Permissions and Security

Required Permissions

Environment Protection Rules

Example Scenarios

Scenario 1: Deploy Latest to Production

Scenario 2: Test PR in Staging

Scenario 3: Deploy to All QA Environments

Troubleshooting

Best Practices