TechDocs URL Reader Zip Archive Not In Expected State using Azure DevOps Server 2020

Expected Behavior

TechDocs should still generate using the URL Reader method with Azure DevOps Server 2020

Current Behavior

Once Issue #4357 has been fixed you’ll now get the following error(s) when opening a Docs site using the URL Reader method:

In the UI:

Error: Failed to generate docs from C:\Users\UserName\AppData\Local\Temp\backstage-OCDxtp into C:\Users\UserName\AppData\Local\Temp\techdocs-tmp-6bZilb with error Docker container returned a non-zero exit code (1) at TechdocsGenerator.run (webpack-internal:///…/techdocs-common/src/stages/generate/techdocs.ts:120:13) at runMicrotasks () at processTicksAndRejections (internal/process/task_queues.js:93:5) at async DocsBuilder.build (webpack-internal:///…/…/plugins/techdocs-backend/src/DocsBuilder/builder.ts:94:5) at async eval (webpack-internal:///…/…/plugins/techdocs-backend/src/service/router.ts:151:13)

Then in the backend logs there is also the following messages:

techdocs debug Failed to generate docs from C:\Users\UserName\AppData\Local\Temp\backstage-OCDxtp into C:\Users\UserName\AppData\Local\Temp\techdocs-tmp-6bZilb type=plugin techdocs debug Build failed with error: {“status”:“Pulling from spotify/techdocs”,“id”:“latest”},{“status”:“Digest: sha256:915bbe59e2602882674d8308ff1211c0c7ab8bdb1a48121df22c9c1abc6a55b1”} {“status”:“Status: Image is up to date for spotify/techdocs:latest”},ERROR - Config value: ‘docs_dir’. Error: The path /content/docs isn’t an existing directory.

Possible Solution

Upon walking through the code it looks like the Zip Archive downloaded for the Azure DevOps Server 2020 REST API isn’t in the expected format. Removing the stripTopDirectory function and just using the entry.path as the arg for 'getInnerPath` from this line fixes the issue:

https://github.com/backstage/backstage/blob/d941f6187b6490878cfea67a46ce573130659765/packages/backend-common/src/reading/tree/ZipArchiveResponse.ts#L156

Here is a sample archive of a repo downloaded using the Azure DevOps Server 2020 REST API: SampleRepo.zip

Steps to Reproduce

These steps assume that you are using Azure DevOps Server 2020 and that Issue #4357 has been fixed.

1. Create a valid catalog-info.yaml file and add it to your repo
2. In your catalog-info file add a backstage.io/techdocs-ref annotation using the URL Reader format for it’s value: url:https://ados-servername/organization/project/_git/repository
3. Make sure you have a \docs folder with at least an index.md
4. Add a mkdocs.yml file in the root of you repo with this as the body of the file:

site_name: 'example-docs'
nav:
  - Home: index.md
plugins:
  - techdocs-core

1. Start up Backstage
2. Register your catalog-info
3. Navigate to the Docs area
4. Then click on the Read Docs button for the repo you setup in the previous steps

Notice that after some time you’ll get the following error in the UI:

Error: Failed to generate docs from C:\Users\UserName\AppData\Local\Temp\backstage-OCDxtp into C:\Users\UserName\AppData\Local\Temp\techdocs-tmp-6bZilb with error Docker container returned a non-zero exit code (1) at TechdocsGenerator.run (webpack-internal:///…/techdocs-common/src/stages/generate/techdocs.ts:120:13) at runMicrotasks () at processTicksAndRejections (internal/process/task_queues.js:93:5) at async DocsBuilder.build (webpack-internal:///…/…/plugins/techdocs-backend/src/DocsBuilder/builder.ts:94:5) at async eval (webpack-internal:///…/…/plugins/techdocs-backend/src/service/router.ts:151:13)

Then in the backend logs there is also the following messages:

techdocs debug Failed to generate docs from C:\Users\UserName\AppData\Local\Temp\backstage-OCDxtp into C:\Users\UserName\AppData\Local\Temp\techdocs-tmp-6bZilb type=plugin techdocs debug Build failed with error: {“status”:“Pulling from spotify/techdocs”,“id”:“latest”},{“status”:“Digest: sha256:915bbe59e2602882674d8308ff1211c0c7ab8bdb1a48121df22c9c1abc6a55b1”} {“status”:“Status: Image is up to date for spotify/techdocs:latest”},ERROR - Config value: ‘docs_dir’. Error: The path /content/docs isn’t an existing directory.

Context

We are currently running Backstage using a fork, we’d really like to move away from that as it is a large amount of overhead to manage the merges. Getting this working would get us to that point.

Your Environment

The key element to this is using Azure DevOps Server 2020

[nadworny]

Hi @freben , I’ve just created a PR for it - my first ever for OS project. Do you need to approve it first so that it goes through the ci/cd pipeline?

[freben]

This is a pretty high value contribution. If you have the time to work on it @nadworny it’d be great!