[Bug]: Deploy Reference Documentation fails for CI/CD

[HazardMK]

AL-Go version

7.3

Describe the issue

Deploy Reference Documentation fails for CI/CD. Issue started from October 1st.

Error: Unexpected error when running action. Error Message: Searching custom plugins in directory C:\Users\runneradmin.dotnet\tools.store\docfx\2.75.3\docfx\2.75.3\tools\net8.0\any... 7 plug-in(s) loaded. 3 schema driven document processor plug-in(s) loaded. C:\Users\runneradmin\AppData\Local\Temp\4d172fae-0164-4c26-8c42-260418b6f495\reference\sp-lemora-base\Module\SP-LEMORA-Base.yml: error ViolateSchema: [/groups/0/symbols] minItems: Value should have at least 1 items Building 2 file(s) in TocDocumentProcessor(BuildTocDocument)... Building 1 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>ValidateConceptualDocumentMetadata)... Building 1 file(s) in BusinessCentralNamespace(BuildSchemaBasedDocument=>ApplyOverwriteFragments=>ApplyOverwriteDocument)... Building 90 file(s) in BusinessCentralApplicationObject(BuildSchemaBasedDocument=>ApplyOverwriteFragments=>ApplyOverwriteDocument)... Applying templates to 94 model(s)... XRef map exported. Build failed. 0 warning(s) 1 error(s) ExitCode: -1 Commandline: docfx build --output "D:\a\SP-LEMORA-Base\SP-LEMORA-Base.aldoc" --logLevel Info "C:\Users\runneradmin\AppData\Local\Temp\4d172fae-0164-4c26-8c42-260418b6f495\docfx.json", StackTrace: at CmdDo, D:\a_actions\microsoft\AL-Go-Actions\v7.3\Github-Helper.psm1: line 298 <- at GenerateDocsSite, D:\a_actions\microsoft\AL-Go-Actions\v7.3\BuildReferenceDocumentation\BuildReferenceDocumentation.HelperFunctions.ps1: line 262 <- at <ScriptBlock>, D:\a_actions\microsoft\AL-Go-Actions\v7.3\BuildReferenceDocumentation\BuildReferenceDocumentation.ps1: line 110 <- at <ScriptBlock>, D:\a_temp\45e9c3f5-2665-45a7-bfe2-be94d6545bae.ps1: line 3 <- at <ScriptBlock>, D:\a_actions\microsoft\AL-Go-Actions\v7.3\Invoke-AlGoAction.ps1: line 21 <- at <ScriptBlock>, D:\a_temp\45e9c3f5-2665-45a7-bfe2-be94d6545bae.ps1: line 2 <- at <ScriptBlock>, <No file>: line 1

Expected behavior

Build Reference Documentation not failing and CI/CD finished without errors.

Steps to reproduce

1. Enabled setting in AL-Go-Settings.json: { "alDoc": { "continuousDeployment": true } }

2. In github repository Settings -> Pages "Build and deployments" source is set to "GitHub Actions".

3. Run CI/CD workflow, check Build Reference Documentation step - it gives an error.

4. Repeat in different repository. Same error.

Additional context (logs, screenshots, etc.)

Adding two logs - one with _failed prefix, one with the last successful CI/CD _success prefix.

logs_46676152377_success.zip logs_46681137961_failed.zip Internal work item: AB#608993

[mazhelez]

Thanks for reporting this issue, @HazardMK

We will take a look!

[louagej]

@mazhelez ,

I have the same issue since yesterday

The only difference I see between the last successful documentation build and today, is the artifact being downloaded of aldoc:

• Sept 30, 2025 Last successful Deploy Reference Documentation

  Locating aldoc
  Downloading Platform index to D:\a\_temp\bcContainerHelper.platform.json
  Downloading core index to D:\a\_temp\bcContainerHelper.core.json
  Downloading aldoc
  Downloading artifact /sandbox/26.5.38752.40230/core
  Downloading C:\Users\runneradmin\AppData\Local\Temp\04158fd4-660f-4df3-bf3c-082b49b703ba.zip
  Unpacking artifact to tmp folder using 7zip
  Extracting aldoc
  Installing/Updating docfx
  You can invoke the tool using the following command: docfx
  Tool 'docfx' (version '2.75.3') was successfully installed.

• Todays Failed build

  Locating aldoc
  Downloading Platform index to D:\a\_temp\bcContainerHelper.platform.json
  Downloading core index to D:\a\_temp\bcContainerHelper.core.json
  Downloading aldoc
  Downloading artifact /sandbox/27.0.38460.40418/core
  Downloading C:\Users\runneradmin\AppData\Local\Temp\4949dbb9-8724-49e5-a79c-9b6c1d93496f.zip
  Unpacking artifact to tmp folder using 7zip
  Extracting aldoc

  Installing/Updating docfx
  You can invoke the tool using the following command: docfx
  Tool 'docfx' (version '2.75.3') was successfully installed.

I hope this helps you a bit

[spetersenms]

I can confirm this is an issue in the latest version of AlDoc. We are working with the respective team to get it fixed. This issue will unfortunately affect all versions of AL-Go, since we always pull the latest version of AlDoc. I'll discuss with the AL-Go team on Monday and consider if we need to ship a hotfix, depending on the time it takes to get AlDoc fixed.

[louagej]

@spetersenms ,

Thanks for looking into this matter. Maybe adding an artifact property to the alDoc as workaround let's the setting decide the exact version to download is a workaround.

[navdotnetreqs]

Spent a lot of time digging into this issue as well. The doc generation works for me in a repo that utilizes namespaces, but for another with no namespaces it fails with this error. I created a test repo, fails with no namespaces, but when I added namespaces for everything the docs are created.

[spetersenms]

This is a confirmed bug in AlDoc, we are currently awaiting a fix from the owning team. I am looking into a workaround within AL-Go. Currently we always use the latest non-insider version of AlDoc, and will likely change that to instead use the version shipped with the artifact defined in your AL-Go settings.

[navdotnetreqs]

Any news or workarounds for this?

[spetersenms]

We have merged a fix for some cases which is scheduled for preview early this week. This will change the AlDoc version to match the BC artifact version used for building apps instead of always using the latest non-insider. Since the issue appeared in 27.0, this means the fix will only work if your artifact setting is using 26.x or lower. We are working with another team internally to get the AlDoc bug fixed asap.

[navdotnetreqs]

@spetersenms thanks for the heads up

[navdotnetreqs]

@spetersenms was this shipped? Still fails with AL-Go 8.3, and I tried putting "artifact": "//26.0//latest" in settings.json

  Update index.md
  index.md:
  ## Reference documentation
  This is the generated reference documentation for [bctesting/athletic-fuu](https://github.com/bctesting/athletic-fuu).
  You can use the navigation bar at the top and the table of contents to the left to navigate your documentation.
  You can change this content by creating/editing the **.aldoc/index.md** file in your repository or use the alDoc:defaultIndexMD setting in your repository settings file (.github/AL-Go-Settings.json)
  invoke doxfx build --output "D:\a\athletic-fuu\athletic-fuu\.aldoc" --logLevel Info "C:\Users\runneradmin\AppData\Local\Temp\56c2bc55-b198-44ef-a7bd-cc36b6311b28\docfx.json"
  Error: Unexpected error when running action. Error Message: Searching custom plugins in directory C:\Users\runneradmin\.dotnet\tools\.store\docfx\2.75.3\docfx\2.75.3\tools\net8.0\any\... 7 plug-in(s) loaded. 3 schema driven document processor plug-in(s) loaded. C:\Users\runneradmin\AppData\Local\Temp\56c2bc55-b198-44ef-a7bd-cc36b6311b28\reference\bc-testing-athletic-fuu\Module\BC-testing-athletic-fuu.yml: error ViolateSchema: [/groups/0/symbols] minItems: Value should have at least 1 items  Building 1 file(s) in BusinessCentralNamespace(BuildSchemaBasedDocument=>ApplyOverwriteFragments=>ApplyOverwriteDocument)... Building 2 file(s) in TocDocumentProcessor(BuildTocDocument)... Building 1 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>ValidateConceptualDocumentMetadata)... Building 24 file(s) in BusinessCentralApplicationObject(BuildSchemaBasedDocument=>ApplyOverwriteFragments=>ApplyOverwriteDocument)... Applying templates to 28 model(s)... XRef map exported.   Build failed.      0 
  Error: Process completed with exit code 1.

[spetersenms]

Hi @navdotnetreqs, this is still in preview, and will ship to stable when we release AL-Go 8.1. We are working with the internal team that owns AlDoc, which has already fixed another AlDoc related issue and are currently working on a permanent fix for this.

[navdotnetreqs]

Hi @spetersenms , appreciated, thanks.

[spetersenms]

Hi @navdotnetreqs. The AlDoc bug should be fixed and shipped with the latest version of the BC 27 artifact. Could you give that a try and let me know if it works as intended for you please?

[louagej]

Hi,

I have a multi project repo with in both projects this setting for alDoc:

"alDoc": {
    "continuousDeployment": true,
    "deployToGitHubPages": false,
    "groupByProject": false,
    "includeProjects": [],
    "excludeProjects": [],
    "maxReleases": 3
  }

With this setting, I would expect the artifact github-pages to be created but not deployed.

• continuousDeployment = Determines if reference documentation will be deployed continuously as part of CI/CD. You can run the Deploy Reference Documentation workflow to deploy manually or on a schedule. (Default false)
• deployToGitHubPages = Determines whether or not the reference documentation site should be deployed to GitHub Pages for the repository. In order to deploy to GitHub Pages, GitHub Pages must be enabled and set to GitHub Actuibs. (Default true)

The CICD workflow runs fine, but there is no artifact github-pagesthat are created.

When I trigger the workflow Deploy Reference Documentation manually, then the artifact is created and published. I also would expect the artifact to be created but not published as GitHub Pages:

Attached the log of the latest CICD

logs_50809296191.zip

[spetersenms]

Hi @louagej, great that the first issue is fixed. Regarding the artifact not being created, could you please double check your settings? The setup you included in this post looks correct, and with those settings it worked correctly for me when I tried, however inspecting your logs, I see the continousDeployment is true while deployToGitHubPages is false:

"alDoc":  {
  "continuousDeployment":  false,
  "deployToGitHubPages":  true,
  "maxReleases":  3,
  "groupByProject":  true,
  "includeProjects":  [],
  "excludeProjects":  [],
  "header":  "<...>",
  "footer":  "<...>"
}

[louagej]

@spetersenms ,

I searched trough my repository and for the 2 projects, there are similar setting:

So, I'm not sure where the CICD did find these setting, because they are just the opposite

[louagej]

@spetersenms I send you an invite from my repository. Hopefully, you can find more like this

[spetersenms]

Hi @louagej, thanks that helps. I think I found the issue. In multiproject repos, the Init job does not have access to project settings, only GitHub settings, and we determine if documentation should be built in the Init job. To fix this, please put your AlDoc settings in .github/AL-Go-Settings.json and try again.

[louagej]

@spetersenms ,

Changing this setting indeed solved the problem. Thank you for this analysis and tip!

[navdotnetreqs]

@spetersenms It works! Awesome!