Copy page

ALbuild

Use Cases

Eight situations ALbuild is built for, each as the sequence of steps that solves it. The steps name the commands and tasks; their inputs and options are documented on the reference pages linked from each scenario.

---

Set up CI for a new product

Situation: a product repository has an app and a test app and needs a pipeline that compiles, tests and packages it on every change.

1. Add an albuild.json at the repository root with the feeds the product's dependencies come from and, where they differ from the defaults, the analyzers and the coverage settings (Project Configuration).
2. Build the pipeline from the tasks in this order: GetBcArtifact@0 → StampBuildVersion@0 → CreateBcContainer@0 → ResolveDependencies@0 → CompileApp@0 → SignBcApp@0 → CreateNuGetPackage@0 → InstallDependencies@0 → PublishApp@0 → RunBcTests@0 → PublishTestResults@2 (testResultsFormat: JUnit) → RemoveBcContainer@0. The complete YAML is on the DevOps extension overview.
3. Sign before packaging: SignBcApp@0 signs the .app in place, so a package created first ships the unsigned file.
4. Install the licence key as the ALBUILD_LICENSE_KEY environment variable on the agent if the pipeline uses licensed tasks (Licensing & Tiers).

---

Change, build and test locally

Situation: you changed AL code on a Windows machine with Docker and want the same answer the pipeline would give, before you push.

Code
albuild app check --project ./app                     # fast compile, no container
albuild app build --workspace . --gate                # the quality gate's compile
albuild container new --project ./app --country de    # container with the app's dependencies
albuild app deploy --container <name> --project ./app --coverage --coverage-path ./CodeCoverage
albuild coverage delta --path ./CodeCoverage --target dev --min 80
albuild translation sync --check
albuild ids check --workspace . --ninja
albuild container remove --container <name> --yes

• app deploy --project builds the app and the test app locally, uploads them with their dependencies and runs the tests, here with coverage for the delta check. --codeunit and --test narrow the run; --expect-declared fails when fewer tests ran than the test apps declare.
• A run in which no test ran is a failure (NO_TESTS_RUN), not a green build. Use --allow-no-tests only where that is expected.
• Remove the containers you created. Only remove containers whose name you know is yours.

Command reference: CLI commands.

---

Work from macOS, Linux or an AI agent

Situation: Business Central containers need a Windows host, but you or an agent work elsewhere.

1. On the Windows host, run the MCP server where other machines can reach it: albuild mcp serve --http --host 0.0.0.0 --port 5020, with bearer tokens configured (ALBUILD_MCP_TOKENS). Without tokens, authentication is off and every request runs as one agent.
2. On your machine, point the CLI at it once: albuild mcp configure --url http://<host>:5020/mcp --server team --default, and put the token in ALBUILD_MCP_TOKEN. An agent that speaks MCP uses the .mcp.json the same command writes.
3. Work as on Windows. Container commands run on the host; app build and translation commands run locally and need PowerShell 7 and the module; app deploy --project builds locally and uploads the result.

Setup details: MCP Server – Get Started.

---

Gate pull requests on patch coverage

Situation: overall coverage moves slowly; you want every pull request to test the lines it changes.

1. In the pull-request pipeline, give RunBcTests@0 the inputs minDiffCoverage (the percentage the changed lines must reach) and diffCoverageTargetBranch (for example dev). With failOnDiffCoverageBelow: true (the default) the task fails below the minimum, and it sets bcPatchCoverage for later steps.
2. Before pushing, check the same thing locally with albuild coverage delta --path <coverage> --target dev --min 80 --out ./coverage-delta; the report lists the uncovered changed lines with their source.

[NonDebuggable] procedures cannot be measured and are listed separately instead of being counted (Code Coverage & Test Quality).

---

Release a version

Situation: a built and tested version goes to customers.

• Version and build branch: StampBuildVersion@0 stamps the version; with continuousBuildNumber: true the build number keeps counting across a version bump (Build Versioning).
• Package feed: SignBcApp@0 → CreateNuGetPackage@0 → PublishPackage@0.
• AppSource: SubmitMarketplace@0 submits the app to Partner Center (autoPromote controls whether it goes live after validation).
• A customer's online environment: PublishPerTenantExtension@0 with the environment name.
• A customer's on-premises server: PublishOnPremApp@0 on an agent next to the server instance.

Publishing to AppSource, an online environment or an on-premises server needs a licence; inputs are on Release Tasks.

---

Move a product to the next Business Central version

Situation: the next major version is in preview and the product must compile and pass its tests on it before release.

1. Run the build against it: GetBcArtifact@0 with select: NextMajor, or locally albuild container new --select NextMajor.
2. Let CompileApp@0 install the AL tool (installAlTool: true, the default). It picks a compiler that can target the app's runtime; a compiler builds its own runtime and every older one.
3. Fix what the new version breaks, then run the tests as usual.

---

Build runtime packages without a container

Situation: customers on many Business Central versions need runtime packages, and a container per version costs minutes and gigabytes.

• New-BcRuntimePackageFromSource emits a runtime package from the app's source with the compiler of a cached artifact; Build-BcProductRuntimePackages builds every outstanding package of one product that way. Both need PowerShell 7.
• The container-based BuildRuntimePackages@0 task and Build-BcRuntimePackages remain for versions the source route does not cover.

See Runtime Packages.

---

Find out why a dependency does not resolve

Situation: a build fails because a dependency is missing or a version does not fit.

1. albuild deps plan --project ./app --bc-version 28 shows the closure the resolver would install, with the versions it chose.
2. albuild deps check --project ./app --container <name> compares the manifest, the container and the feeds.
3. In PowerShell, Resolve-BcDependencies gives the same answer with full detail.

See Dependency Resolver.