import { Callout } from "zudoku/ui/Callout";

# 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.

| Scenario | You use |
|---|---|
| [Set up CI for a new product](#set-up-ci-for-a-new-product) | DevOps extension |
| [Change, build and test locally](#change-build-and-test-locally) | CLI on Windows |
| [Work from macOS, Linux or an AI agent](#work-from-macos-linux-or-an-ai-agent) | CLI or MCP server against a Windows host |
| [Gate pull requests on patch coverage](#gate-pull-requests-on-patch-coverage) | Run Tests task, CLI |
| [Release a version](#release-a-version) | DevOps extension |
| [Move a product to the next Business Central version](#move-a-product-to-the-next-business-central-version) | DevOps extension, CLI |
| [Build runtime packages without a container](#build-runtime-packages-without-a-container) | PowerShell module |
| [Find out why a dependency does not resolve](#find-out-why-a-dependency-does-not-resolve) | CLI, PowerShell module |

---

## 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](/en-us/albuild/concepts/project-config)).
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](/en-us/albuild/devops-extension).
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](/en-us/albuild/concepts/licensing)).

<Callout type="tip">
`CompileApp@0` with `requireAnalyzers: true` and `treatWarningsAsErrors: true` is the quality gate. The
same compile runs locally with `albuild app build --gate`, so a clean local build means a clean gate.
</Callout>

---

## 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.

```powershell
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](/en-us/albuild/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](/en-us/albuild/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](/en-us/albuild/concepts/code-coverage)).

---

## 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](/en-us/albuild/concepts/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](/en-us/albuild/devops-extension/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](/en-us/albuild/concepts/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.

<Callout type="note">
`dependencies.lock.json` records what was resolved; it does not pin it. The resolver solves again on
every run, and the Install Dependencies task installs exactly what the lock file names.
</Callout>

See [Dependency Resolver](/en-us/albuild/concepts/dependency-resolver).