Automation: hooks, schedules, and pipelines

BC Atlas uses one entry point for every trigger:

bca run [app-root] --trigger pre-commit | pre-push | ci | schedule

bca run reads .bca.json, runs the features configured for that trigger, and syncs their output. Git hooks, cron jobs, GitHub Actions, and Azure Pipelines only call this command, so they all behave the same way. The easiest way to configure it is bca setup.

Configuration

{
  "automation": {
    "hooks": "husky",
    "ci": "github",
    "triggers": {
      "pre-commit": { "tasks": ["check"], "sync": "none" },
      "pre-push":   { "tasks": ["report", "docs"], "sync": "verify" },
      "ci":         { "tasks": ["check", "report", "docs"], "sync": "verify" },
      "schedule":   { "cron": "0 6 * * 1", "tasks": ["report", "docs"], "sync": "pull-request" }
    }
  },
  "report": { "outputDir": "docs/atlas" },
  "docs": { "tests": "test", "app": ".", "export": ["markdown", "html"], "as": "guide", "outputDir": "docs/guides" }
}

Task	Writes	Settings
check	nothing; fails on findings	check section
report	report.outputDir (default docs/atlas)	report section
docs	docs.outputDir (default docs/guides)	docs: tests, app, export, as, language, title
codegraph	codegraph.outputDir (default docs/codegraph)	codegraph section
diagrams	each diagrams[].output	diagrams: list of graph options, e.g. { "view": "data", "output": "docs/data.svg" }

Sync modes

Mode	Used by	Effect
none	all	Only run the tasks.
verify	hooks, pipelines	Fail when generated files differ from the commit. Run it, commit the regenerated files, and try again.
stage	Git hooks	Add regenerated files to the current commit.
artifact	pipelines	Publish generated files as a pipeline artifact.
pull-request	GitHub schedule	Open or update a pull request (bc-atlas/update) with regenerated files.
commit	pipeline schedule	Commit regenerated files to the branch.

bca run performs verify and stage itself and reports the generated paths. The pipeline steps generated by bca setup perform artifact, pull-request, and commit.

bca run exits with 1 when a task fails, check finds blocking issues, or verify finds outdated files. --format json returns tasks, results, outputs, and changed files.

Git hooks

Husky (recommended for teams): hooks live in .husky/ and are installed for everyone by npm install through the prepare script. bca setup --hooks husky adds a package.json if the repository has none.

# .husky/pre-push
npx --no-install bca run apps/sales --trigger pre-push || exit 1

Plain Git hooks need no Node.js project: hooks live in .githooks/, and each clone runs git config core.hooksPath .githooks once. The hook uses bca from PATH and falls back to npx.

Skip hooks once with git commit --no-verify or git push --no-verify.

VS Code tasks

bca setup --editor vscode adds BC Atlas: tasks to .vscode/tasks.json:

• a health check whose findings appear in the Problems panel;
• report and documentation builds;
• dry runs of the pre-commit and pre-push hooks;
• a recommendation of the BC Atlas extension in .vscode/extensions.json;
• the setup wizard.

See Guided setup.

Updates

When a package.json declares bc-atlas (always the case with Husky), generated pipelines install that version with npm ci and run npx --no-install bca, so hooks, tasks, and CI use the same version. Dependabot (bca setup --updates dependabot) proposes new versions as pull requests; bca update updates locally and regenerates the setup files. See Staying up to date.

Schedules (cron)

A schedule is a five-field cron expression in UTC, for example 0 6 * * 1 for Mondays at 06:00. With a pipeline, setup writes it into the pipeline's schedule. Without a pipeline, run it from any scheduler:

# crontab -e
0 6 * * 1 cd /repos/sales && bca run apps/sales --trigger schedule

GitHub Actions

bca setup --ci github writes .github/workflows/bc-atlas.yml:

• pull requests and pushes to main run --trigger ci;
• the cron schedule runs --trigger schedule;
• workflow_dispatch allows manual runs;
• sync steps upload an artifact, open a pull request, or commit, as configured.

You can also use BC Atlas as an action in your own workflows:

- uses: actions/checkout@v4
- id: atlas
  uses: SchulzOli/BC-Atlas@v0.7.0
  with:
    path: apps/sales        # folder with .bca.json
    trigger: ci             # or: tasks: check,report
- run: echo "Generated: ${{ steps.atlas.outputs.outputs }}"

Input	Default	Description
path	.	AL app folder with .bca.json
trigger	ci	Trigger whose tasks and sync mode are used
tasks		Comma-separated tasks instead of the trigger's tasks
sync		Override the sync mode
node-version	24	Node.js version
al-compiler	true	Install the AL Development Tools so the AL compiler resolves calls and runs the code analyzers

Outputs: outputs (generated paths) and passed (true or false).

Generated workflows and pipelines install the AL Development Tools too, so CI resolves calls and reports compiler and analyzer findings like a developer machine; "al": { "compiler": "off" } in .bca.json leaves that step out. See AL toolchain.

Code scanning

- run: npx --yes bc-atlas check app --format sarif -o bca.sarif --fail-on never
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: bca.sarif

The SARIF file holds BC Atlas findings and AL compiler and analyzer findings with their rules and help links. A pipeline that already builds the app (AL-Go, BcContainerHelper) can pass its error logs with --compiler-log instead of compiling again.

Azure Pipelines

bca setup --ci azure-devops writes azure-pipelines.bc-atlas.yml with a trigger for main, a pr trigger, and a schedules entry for the cron expression. Create a pipeline from that file in Azure DevOps. For commit sync, allow the build service to contribute to the repository.

Health summary on the job page

- name: Architecture health
  run: |
    npx --yes bc-atlas check ./app --format markdown -o health.md || status=$?
    cat health.md >> "$GITHUB_STEP_SUMMARY"
    exit ${status:-0}

Read the model from scripts

bca export ./app --view project --format json -o architecture.json
bca check ./app --format json > health.json
bca run ./app --trigger ci --format json > run.json

Run in a container

docker build -t bc-atlas .
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/workspace" bc-atlas run /workspace/app --trigger ci

Keep this project's documentation synchronized

This repository generates its table of contents and CLI capability summary from source data:

npm run docs
npm run docs:check

npm run check runs docs:check, and CI also builds the documentation website (npm run site:build), which fails on dead links.