# al-build

> Build and test AL/Business Central projects. Use after modifying AL code or tests to verify the build gate passes. Runs compilation, publishing, and test execution in a single command. Required gate before committing AL changes.

- Author: Flemming Bakkensen
- Repository: FBakkensen/bc-agentic-dev-tools
- Version: 20260105204401
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/FBakkensen/bc-agentic-dev-tools
- Web: https://mule.run/skillshub/@@FBakkensen/bc-agentic-dev-tools~al-build:20260105204401

---

---
name: al-build
description: Build and test AL/Business Central projects. Use after modifying AL code or tests to verify the build gate passes. Runs compilation, publishing, and test execution in a single command. Required gate before committing AL changes.
---

# AL Build

Self-contained build system for AL/Business Central development. No external task runners required.

## Project Setup (First Time)

**Required Steps**:
1. **Initialize config**: Run `/al-build:init` to create `al-build.json`
2. **Customize config** (especially `testAppName` to match your test app)
3. **Run provision** (one-time): Run `/al-build:provision`

**Config Priority** (highest to lowest):
1. Script parameters (e.g., `-AppDir "custom"`)
2. Environment variables (e.g., `ALBT_APP_DIR`)
3. Project config (`al-build.json` in repo root)

## Canonical Gate

After modifying AL code or tests, run:

```powershell
pwsh "<skill-folder>/scripts/test.ps1"
```

**Prerequisites:**
- Project config exists and customized (`al-build.json`)
- Provision completed (run `provision.ps1` once)
- Docker container healthy

**Requirements:**
- Zero warnings, zero errors
- Faster iteration: `pwsh "<skill-folder>/scripts/test.ps1" -TestCodeunit <id>`
- Force republish: `pwsh "<skill-folder>/scripts/test.ps1" -Force`

**Outputs:**
- `.output/TestResults/last.xml` — JUnit test results
- `.output/TestResults/telemetry.jsonl` — merged telemetry

## Running Tests in Subtask (Recommended)

Use the Task tool with `subagent_type: general-purpose` to run tests. This keeps verbose build output contained and returns only essential results to the main conversation.

**Task tool invocation:**
```
subagent_type: general-purpose
prompt: |
  IMPORTANT: This is a READ-ONLY task. Do NOT edit any files.

  Run the AL build gate:
  pwsh "<skill-folder>/scripts/test.ps1"

  Report back:
  1. Build result: success or failure
  2. Test result: pass count, fail count
  3. If failures: include the relevant error messages and stack traces
  4. If warnings: list them
  5. If failures and telemetry is relevant: include key entries from .output/TestResults/telemetry.jsonl

  Do not include full console output - only the summary above.
```

**Why subtask?**
- Build/test output is verbose (compilation logs, test runner output)
- Main task only needs results and actionable error context
- Keeps conversation focused on the development task

## Troubleshooting

### Build fails and no config exists

If `/al-build:test` fails and `al-build.json` doesn't exist in repo root:
1. Run `/al-build:init` to create config
2. Customize settings as needed
3. Run `/al-build:provision` once
4. Re-run `/al-build:test`

### Config Issues

1. **Config not loading**: Ensure `al-build.json` is in git repo root (same level as `.git/`)
2. **Provision not found**: Run `/al-build:provision` (one-time)
3. **Wrong test app**: Update `testAppName` in `al-build.json` to match your test app

### Build Failures

1. Check compiler output for error messages
2. Ensure symbols are provisioned (user runs: `pwsh provision.ps1`)
3. Verify container is healthy: `docker ps`

### Test Failures

1. Check `.output/TestResults/last.xml` for assertion failures
2. Use telemetry for debugging: see `telemetry-first-test-debugging` skill
3. Run specific codeunit: `pwsh "<skill-folder>/scripts/test.ps1" -TestCodeunit <id>`

### Container Issues

1. Check container health: `docker inspect <name> --format '{{.State.Health.Status}}'`
2. View container logs: `docker logs <name>`