Skip to main content
Online development environments enable rapid application development by providing cloud-based Business Central sandboxes configured specifically for your AL-Go project. These environments integrate seamlessly with VS Code for debugging and testing.

​
Overview

AL-Go supports two methods for creating online development environments:

From VS Code

Run a PowerShell script locally to create and configure an environment directly from your development machine.

From GitHub

Use a GitHub Actions workflow to create environments through automated processes.
Important: Two developers cannot share a single online environment. Each developer needs their own dedicated environment.

​
Create Environment from VS Code

This method uses a PowerShell script to create an environment with interactive authentication.
1

Run the cloudDevEnv script

Open your AL-Go project in VS Code and navigate to the .AL-Go folder.Locate and run the cloudDevEnv.ps1 script.
./.AL-Go/cloudDevEnv.ps1
The script will prompt you for:
  • Environment name (if not specified as a parameter)
  • Whether to reuse or recreate the environment if it already exists
2

Authenticate with device code flow

The script needs access to the Business Central Admin Center API and initiates a device code login.When prompted:
  1. Open https://aka.ms/devicelogin in your browser
  2. Enter the code displayed in the PowerShell terminal
  3. Sign in with your Business Central admin credentials
  4. Accept the PowerShell authentication request
3

Wait for environment setup

The script performs several operations:
  • Creates or reuses the specified environment
  • Compiles all apps in your project
  • Publishes apps to the online environment using development scope
  • Configures VS Code launch.json for the new environment
This process may take several minutes depending on the number of apps and dependencies.
4

Start developing

Once the script completes, VS Code is ready for rapid application development:
  1. Make changes to your app code
  2. Press F5 to debug
  3. Select the Cloud Sandbox with your environment name
  4. Your changes are immediately available in the online environment
The launch.json file is updated with your new environment. You can choose to:
  • Commit the changes to share the environment configuration
  • Keep it local for personal use only

​
Create Environment from GitHub

This method uses GitHub Actions workflows to create environments, useful for automated or unattended setup.

​
Authentication Setup

The workflow requires authentication to the Business Central Admin Center API.
Admin Center API Credentials Required: You must provide authentication credentials either as a GitHub Secret or in Azure Key Vault.

​
Option 1: Unattended Authentication

For fully automated workflow execution, create a secret called AdminCenterApiCredentials.
1

Generate a refresh token

On a machine with BcContainerHelper installed, run:
New-BcAuthContext -includeDeviceLogin | New-ALGoAuthContext | Set-Clipboard
This copies a JSON authentication context to your clipboard.
2

Create the GitHub secret

Navigate to your repository Settings → Secrets and variables → Actions.Create a new secret named AdminCenterApiCredentials with the format:
{"refreshtoken":"your_refresh_token_here"}
At the time of writing, the Admin Center API does not support S2S authentication, so the refresh token format is required.

​
Option 2: Interactive Device Flow

If you don’t provide the AdminCenterApiCredentials secret, the workflow initiates a device code flow.
1

Start the workflow without credentials

Run the Create Online Dev. Environment workflow without the secret configured.The workflow pauses and waits for authentication.
2

Get the device code

Inspect the workflow run details and open the job:Check AdminCenterApiCredentials / Initiate Device Login (open to see code)The device code is displayed in the job logs.
3

Complete authentication

  1. Navigate to https://aka.ms/devicelogin
  2. Enter the device code from the workflow logs
  3. Sign in with admin credentials
  4. The workflow continues automatically after successful authentication

​
Run the Workflow

1

Start the workflow

On GitHub.com, navigate to Actions → Create Online Dev. Environment.Click Run workflow and provide:
  • Environment name: Name for your development environment
  • Reuse environment: Whether to reuse an existing environment with the same name
Click Run workflow to start.
2

Review the pull request

When the workflow completes, it creates a pull request with changes to launch.json.The pull request includes:
  • New launch configuration for the online environment
  • Server URL and authentication settings
  • Environment-specific configuration
{
  "type": "al",
  "request": "launch",
  "name": "Your Online Dev Environment",
  "server": "https://businesscentral.dynamics.com",
  "environmentName": "YourEnvName",
  "tenant": "your-tenant-id"
}
3

Merge and start developing

Review and merge the pull request.Developers can now:
  1. Pull the latest changes to get the updated launch.json
  2. Use the new environment for debugging and development
  3. Press F5 in VS Code to connect to the online environment

​
Development Workflow with Online Environments

​
Rapid Application Development (RAD)

Online environments enable a fast development cycle:
1

Make code changes

Edit your AL code in VS Code as usual.
2

Debug in the cloud

Press F5 and select your online environment from the launch configuration list.VS Code:
  • Compiles your changes
  • Publishes to the development scope
  • Launches the debugger attached to the online environment
3

Test immediately

Your changes are live in the Business Central web client.Test functionality, verify UI changes, and debug issues in real-time.
4

Iterate quickly

Make additional changes and press F5 again.No need to rebuild containers or wait for local environment startup.

​
Best Practices

​
Environment Management

One Environment Per Developer

Each developer should have their own dedicated environment to avoid conflicts and ensure isolation.

Name Environments Clearly

Use descriptive names like “dev-johnsmith” or “feature-newcheckout” to identify purpose and owner.

Clean Up Unused Environments

Delete environments when features are complete or developers leave the team to save resources.

Separate Dev and Test

Keep development environments separate from formal test/staging environments.

​
Security Considerations

Protect Refresh Tokens: The AdminCenterApiCredentials secret contains sensitive authentication tokens. Store it securely in GitHub Secrets or Azure Key Vault, never in code.
  • Use Azure Key Vault for production setups
  • Rotate refresh tokens periodically
  • Limit who can access the secrets
  • Audit secret usage regularly

​
Launch Configuration Management

Local vs. Committed:
  • Commit launch.json changes to share environment configurations with the team
  • Keep local if the environment is for personal development only
  • Use .gitignore to exclude personal launch configurations if needed
// .vscode/launch.json - Can be committed for team use
{
  "configurations": [
    {
      "name": "Team Dev Environment",
      "type": "al",
      "request": "launch",
      "environmentName": "TeamDev"
    }
  ]
}

​
Performance Tips

Apps published in development scope load faster and can be unpublished easily. This is ideal for rapid iteration during development.
  • Keep test data sets reasonably sized
  • Archive old development environments instead of deleting
  • Use the “reuse environment” option when possible to save setup time
  • Monitor environment performance and upgrade if needed

​
Troubleshooting

​
Authentication Issues

If device code login fails:
  • Verify you have Business Central admin rights
  • Check that your tenant allows the Admin Center API
  • Ensure you’re using a work/school account, not a personal Microsoft account
  • Try clearing browser cache and cookies

​
Environment Creation Fails

Common issues:
  • Insufficient licenses: Ensure you have available development licenses
  • Name conflicts: Use a unique environment name
  • Region restrictions: Verify your tenant supports the selected region
  • Quota limits: Check if you’ve reached environment limits

​
Connection Problems

If VS Code can’t connect:
  • Verify the environment is running in Business Central Admin Center
  • Check launch.json has correct server and tenant information
  • Ensure your account has access to the environment
  • Try regenerating the authentication context

​
Next Steps

Configure Dependencies

Learn how to set up dependencies on apps from other repositories

Versioning Strategy

Understand version numbering and release management

Build docs developers (and LLMs) love

Get started for freeTalk to us