Migrated documentation build script to GitHub actions #6

tholzheim · 2025-12-03T10:16:13Z

Summary

Added documentation build script and updated dtcw script to latest version

What’s Changed

migrated GitLab documentation build script to Github actions workflow
updated dtcw script to version v3.4.2

How to Test

Check workflow artifact it generates a zip file containing the Architecture Gaia-X Federated Catalogue as PDF and HTML version.

sonarqubecloud · 2025-12-03T10:16:48Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Copilot

Pull request overview

This PR migrates the documentation build process from GitLab to GitHub Actions and updates the docToolchain wrapper script (dtcw) from v2.0.5 to v3.4.1.

Key Changes:

Added a new GitHub Actions workflow to automate documentation generation on push to main branch
Updated dtcw script with improved error handling, multi-environment support (local/sdk/docker), and better user guidance
Configured artifact upload for generated PDF and HTML documentation

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.

File	Description
`.github/workflows/buildDocs.yml`	New workflow that checks out code, generates HTML and PDF documentation using dtcw, and uploads artifacts
`federated-catalogue/dtcw`	Complete replacement updating from v2.0.5 to v3.4.1 with enhanced features including improved environment detection, Java installation support, and better error messages

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-03T10:24:14Z

federated-catalogue/dtcw

+assert_java_version_supported() {
+    # Defines the order in which Java is searched.
+    if [ -d "${DTC_JAVA_HOME}" ]; then
+            echo "Caution: Your JAVA_HOME setting is overriden by DTCs own JDK install (for this execution)"


Typo: 'overriden' should be 'overridden'

Suggested change

echo "Caution: Your JAVA_HOME setting is overriden by DTCs own JDK install (for this execution)"

echo "Caution: Your JAVA_HOME setting is overridden by DTCs own JDK install (for this execution)"

Copilot · 2025-12-03T10:24:15Z

federated-catalogue/dtcw

+    local adoptium_java_url="https://api.adoptium.net/v3/binary/latest/${version}/${releasetype}/${os}/${arch}/${imagetype}/${implementation}/${heapsize}/eclipse?project=jdk"
+    download_file "${adoptium_java_url}" "${DTC_JAVA_HOME}/jdk.tar.gz"
+    echo "Extracting JDK from archive file."
+    # TODO: should we not delete a previsouly installed on?


Typo: 'previsouly' should be 'previously'

Suggested change

# TODO: should we not delete a previsouly installed on?

# TODO: should we not delete a previously installed one?

Copilot · 2025-12-03T10:24:15Z

federated-catalogue/dtcw

+    if ! is_doctoolchain_installed "${env}"; then
+        # We reach this point if the user executes a command in an
+        # environment where docToolchain is not installed.
+        # Note that 'docker' always has a command (no instalation required)


Typo: 'instalation' should be 'installation'

Suggested change

# Note that 'docker' always has a command (no instalation required)

# Note that 'docker' always has a command (no installation required)

Copilot · 2025-12-03T10:24:15Z

federated-catalogue/dtcw

+
+# See https://github.com/docToolchain/docToolchain/releases for available versions.
+# Set DTC_VERSION to "latest" to get the latest, yet unreleased version.
+: "${DTC_VERSION:=3.4.1}"


The PR description states that dtcw was updated to version v3.4.2, but the script contains version 3.4.1. Please verify which version is correct and update either the PR description or the script accordingly.

Suggested change

: "${DTC_VERSION:=3.4.1}"

: "${DTC_VERSION:=3.4.2}"

Copilot · 2025-12-03T10:24:16Z

.github/workflows/buildDocs.yml

+          ./dtcw generateHTML
+      
+      - name: Generate PDF Documentation
+        run: |
+          cd ./federated-catalogue
+          ./dtcw generatePDF


[nitpick] The workflow runs dtcw script without explicitly setting up Java or specifying the execution environment. The dtcw script will default to 'local' environment which requires Java 11-17. Consider either:

Adding a Java setup step before generating documentation (e.g., actions/setup-java@v4), or

Explicitly using the docker environment by changing the commands to ./dtcw docker generateHTML and ./dtcw docker generatePDF

Option 2 is recommended as it ensures a consistent build environment without requiring Java installation.

Suggested change

./dtcw generateHTML

- name: Generate PDF Documentation

run: |

cd ./federated-catalogue

./dtcw generatePDF

./dtcw docker generateHTML

- name: Generate PDF Documentation

run: |

cd ./federated-catalogue

./dtcw docker generatePDF

Copilot · 2025-12-03T10:24:16Z

federated-catalogue/dtcw

+}
+
+get_available_environments() {
+    # The local environment is alway available - even if docToolchain is not installed


Typo: 'alway' should be 'always'

Suggested change

# The local environment is alway available - even if docToolchain is not installed

# The local environment is always available - even if docToolchain is not installed

Copilot · 2025-12-03T10:24:16Z

federated-catalogue/dtcw

+    # The local environment is alway available - even if docToolchain is not installed
+    local envs=" local"
+
+    # 'sdk' is provided a bash founction - thus command doesn't work


Typo: 'founction' should be 'function'

Suggested change

# 'sdk' is provided a bash founction - thus command doesn't work

# 'sdk' is provided a bash function - thus command doesn't work

Copilot · 2025-12-03T10:24:17Z

federated-catalogue/dtcw

+                echo "Could not find doctoolchain executable, neither in '${DTC_HOME}' nor on PATH ('${PATH}')" >&2
+                exit 1
+            fi
+            cmd="${cmd} . ${*} ${DTC_OPTS}"


User-controlled CLI arguments are concatenated into a shell command string via ${*} and later executed with bash -c, enabling shell injection. An attacker can pass arguments containing shell metacharacters (e.g., ;, &&) to execute arbitrary commands with the user’s privileges. Fix by avoiding bash -c and not building command strings; instead, execute the target directly using an argument array and pass arguments safely, e.g.,

# Build an array and exec without a shell args=("." ) args+=("$@") exec "${cmd}" "${args[@]}" ${DTC_OPTS:+"${DTC_OPTS}"}

Or use "$@" expansions when invoking without going through a shell.

Copilot · 2025-12-03T10:24:17Z

federated-catalogue/dtcw

+        docker_args="run --rm -i --platform linux/amd64 -u $(id -u):$(id -g) --name ${container_name} \
+            -e DTC_HEADLESS=true -e DTC_SITETHEME -e DTC_PROJECT_BRANCH=${DTC_PROJECT_BRANCH} \
+            ${docker_extra_arguments} ${env_file_option} \
+            --entrypoint /bin/bash -v '${pwd}:/project' ${DTC_DOCKER_PREFIX}${docker_image}:v${version}"
+
+        cmd="docker ${docker_args} -c \"doctoolchain . ${*} ${DTC_OPTS} && exit\""


Docker execution path constructs a command string that embeds ${*} (user-provided args) and ${docker_extra_arguments} directly, then runs it via bash -c, allowing shell injection. Supplying malicious args (e.g., "; uname -a; #") can break out of the intended invocation and run arbitrary host commands. Fix by avoiding bash -c and passing arguments to docker and to the container entrypoint as separate argv elements, e.g.,

# Example: do not use -c; set entrypoint and pass args safely exec docker run --rm -i --platform linux/amd64 -u "$(id -u):$(id -g)" \ --name "$container_name" -e DTC_HEADLESS=true -e "DTC_PROJECT_BRANCH=$DTC_PROJECT_BRANCH" \ ${docker_extra_args_array[@]} ${env_file_option_args[@]} \ -v "$pwd:/project" --entrypoint doctoolchain "${DTC_DOCKER_PREFIX}${docker_image}:v${version}" \ . "$@" ${DTC_OPTS:+"${DTC_OPTS}"}

Suggested change

docker_args="run --rm -i --platform linux/amd64 -u $(id -u):$(id -g) --name ${container_name} \

-e DTC_HEADLESS=true -e DTC_SITETHEME -e DTC_PROJECT_BRANCH=${DTC_PROJECT_BRANCH} \

${docker_extra_arguments} ${env_file_option} \

--entrypoint /bin/bash -v '${pwd}:/project' ${DTC_DOCKER_PREFIX}${docker_image}:v${version}"

cmd="docker ${docker_args} -c \"doctoolchain . ${*} ${DTC_OPTS} && exit\""

# Convert docker_extra_arguments and env_file_option to arrays for safe expansion

local docker_extra_args_array=()

if [ -n "${docker_extra_arguments}" ]; then

# shellcheck disable=SC2206

docker_extra_args_array=(${docker_extra_arguments})

fi

local env_file_option_args=()

if [ -n "${env_file_option}" ]; then

# shellcheck disable=SC2206

env_file_option_args=(${env_file_option})

fi

docker_args=(run --rm -i --platform linux/amd64 -u "$(id -u):$(id -g)" --name "${container_name}" \

-e DTC_HEADLESS=true -e DTC_SITETHEME -e "DTC_PROJECT_BRANCH=${DTC_PROJECT_BRANCH}" \

"${docker_extra_args_array[@]}" "${env_file_option_args[@]}" \

-v "${pwd}:/project" --entrypoint doctoolchain "${DTC_DOCKER_PREFIX}${docker_image}:v${version}")

# Build argument list for doctoolchain: . "$@" ${DTC_OPTS}

local doctoolchain_args=(. "$@")

if [ -n "${DTC_OPTS}" ]; then

# shellcheck disable=SC2206

doctoolchain_args+=(${DTC_OPTS})

fi

cmd="docker ${docker_args[@]} ${doctoolchain_args[@]}"

Copilot · 2025-12-03T10:24:17Z

federated-catalogue/dtcw

+            fi
+            cmd="${cmd} . ${*} ${DTC_OPTS}"
+        else
+            cmd="$(sdk_home_doctoolchain "${version}")/bin/doctoolchain . ${*} ${DTC_OPTS}"


User-supplied CLI arguments are interpolated into a command string via ${*} that is later executed with bash -c, enabling shell metacharacter injection. A crafted argument (e.g., --help; rm -rf "$HOME" #) would be executed by the shell rather than passed to doctoolchain. Fix by avoiding command-string construction and bash -c; invoke the target binary directly with an argument array and forward "$@" safely.

tholzheim and others added 3 commits December 3, 2025 10:55

updates dtcw script to version v3.4.2

ff04dd4

adds buildDocs workflow

dce92c4

changed permission of dtcw script to executable

178b9a5

Copilot AI review requested due to automatic review settings December 3, 2025 10:16

Copilot started reviewing on behalf of tholzheim December 3, 2025 10:16 View session

Copilot finished reviewing on behalf of tholzheim December 3, 2025 10:19

Copilot AI reviewed Dec 3, 2025

View reviewed changes

	echo "Caution: Your JAVA_HOME setting is overriden by DTCs own JDK install (for this execution)"
	echo "Caution: Your JAVA_HOME setting is overridden by DTCs own JDK install (for this execution)"

	# TODO: should we not delete a previsouly installed on?
	# TODO: should we not delete a previously installed one?

	# Note that 'docker' always has a command (no instalation required)
	# Note that 'docker' always has a command (no installation required)

	# The local environment is alway available - even if docToolchain is not installed
	# The local environment is always available - even if docToolchain is not installed

	# 'sdk' is provided a bash founction - thus command doesn't work
	# 'sdk' is provided a bash function - thus command doesn't work

-        docker_args="run --rm -i --platform linux/amd64 -u $(id -u):$(id -g) --name ${container_name} \
-            -e DTC_HEADLESS=true -e DTC_SITETHEME -e DTC_PROJECT_BRANCH=${DTC_PROJECT_BRANCH} \
-            ${docker_extra_arguments} ${env_file_option} \
-            --entrypoint /bin/bash -v '${pwd}:/project' ${DTC_DOCKER_PREFIX}${docker_image}:v${version}"
-        cmd="docker ${docker_args} -c \"doctoolchain . ${*} ${DTC_OPTS} && exit\""
+        # Convert docker_extra_arguments and env_file_option to arrays for safe expansion
+        local docker_extra_args_array=()
+        if [ -n "${docker_extra_arguments}" ]; then
+            # shellcheck disable=SC2206
+            docker_extra_args_array=(${docker_extra_arguments})
+        fi
+        local env_file_option_args=()
+        if [ -n "${env_file_option}" ]; then
+            # shellcheck disable=SC2206
+            env_file_option_args=(${env_file_option})
+        fi
+        docker_args=(run --rm -i --platform linux/amd64 -u "$(id -u):$(id -g)" --name "${container_name}" \
+            -e DTC_HEADLESS=true -e DTC_SITETHEME -e "DTC_PROJECT_BRANCH=${DTC_PROJECT_BRANCH}" \
+            "${docker_extra_args_array[@]}" "${env_file_option_args[@]}" \
+            -v "${pwd}:/project" --entrypoint doctoolchain "${DTC_DOCKER_PREFIX}${docker_image}:v${version}")
+        # Build argument list for doctoolchain: . "$@" ${DTC_OPTS}
+        local doctoolchain_args=(. "$@")
+        if [ -n "${DTC_OPTS}" ]; then
+            # shellcheck disable=SC2206
+            doctoolchain_args+=(${DTC_OPTS})
+        fi
+        cmd="docker ${docker_args[@]} ${doctoolchain_args[@]}"

Migrated documentation build script to GitHub actions #6

Are you sure you want to change the base?

Migrated documentation build script to GitHub actions #6

Uh oh!

Conversation

tholzheim commented Dec 3, 2025

Summary

What’s Changed

How to Test

Uh oh!

sonarqubecloud bot commented Dec 3, 2025

Quality Gate passed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant