From db59fa1d1f2612621a107934280b01581d33e2a0 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Fri, 22 May 2026 07:57:12 +0200
Subject: [PATCH 01/26] api_refs.sh: Avoid hint about master VS main

```
+ git init
hint: Using 'master' as the name for the initial branch. This default branch name
hint: will change to "main" in Git 3.0. To configure the initial branch name
```
---
 tools/api_refs/api_refs.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/api_refs/api_refs.sh b/tools/api_refs/api_refs.sh
index 5f9f31167b..1e3c265727 100755
--- a/tools/api_refs/api_refs.sh
+++ b/tools/api_refs/api_refs.sh
@@ -216,7 +216,7 @@ fi;
 
 if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
   echo 'Set up DXP recipes…';
-  git init && git add . && git commit -m "Installed Ibexa Commerce" > /dev/null;
+  git init -b main && git add . && git commit -m "Installed Ibexa Commerce" > /dev/null;
   composer recipes:install ibexa/$DXP_EDITION --force --reset --no-interaction;
 fi;
 

From ef1d3d85c0332e5283acc64f9a36a393ffa3796c Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Fri, 22 May 2026 08:10:09 +0200
Subject: [PATCH 02/26] api_refs.sh: COMPOSER_BINARY var

---
 tools/api_refs/api_refs.sh | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/tools/api_refs/api_refs.sh b/tools/api_refs/api_refs.sh
index 1e3c265727..6701c466f0 100755
--- a/tools/api_refs/api_refs.sh
+++ b/tools/api_refs/api_refs.sh
@@ -24,6 +24,7 @@ REDOCLY_TEMPLATE="$(pwd)/tools/api_refs/redocly.hbs"; # Absolute path to Redocly
 OPENAPI_FIX="$(pwd)/tools/api_refs/openapi.php"; # A script editing and fixing few things on the dumped schema (should be temporary and fixes reported to source)
 
 PHP_BINARY="php -d error_reporting=`php -r 'echo E_ALL & ~E_DEPRECATED;'`"; # Avoid depreciation messages from phpDocumentor/Reflection/issues/529 when using PHP 8.2 or higher
+COMPOSER_BINARY='composer';
 TMP_DXP_DIR=/tmp/ibexa-dxp-phpdoc; # Absolute path of the temporary directory in which Ibexa DXP will be installed and the PHP API Reference built
 FORCE_DXP_INSTALL=1; # If 1, empty the temporary directory, install DXP from scratch, build, remove temporary directory; if 0, potentially reuse the DXP already installed in temporary directory, keep temporary directory for future uses.
 BASE_DXP_BRANCH="${BASE_DXP_BRANCH:-}"; # Branch from and for which the Reference is built when using a dev branch as version; can be overridden by the BASE_DXP_BRANCH env var
@@ -63,32 +64,32 @@ cd $TMP_DXP_DIR; # /!\ Change working directory (reason why all paths must be ab
 if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
   echo "Creating ibexa/$DXP_EDITION-skeleton:$DXP_VERSION project in ${TMP_DXP_DIR}…";
   if [[ "$DXP_VERSION" == *".x-dev" ]]; then
-    composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=dev;
+    $COMPOSER_BINARY create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=dev;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;
-    composer config repositories.ibexa composer https://updates.ibexa.co;
-    composer config extra.symfony.endpoint "https://api.github.com/repos/ibexa/recipes-dev/contents/index.json?ref=flex/main";
-    composer require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
+    $COMPOSER_BINARY config repositories.ibexa composer https://updates.ibexa.co;
+    $COMPOSER_BINARY config extra.symfony.endpoint "https://api.github.com/repos/ibexa/recipes-dev/contents/index.json?ref=flex/main";
+    $COMPOSER_BINARY require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
   elif [[ "$DXP_VERSION" == *"-rc"* ]]; then
-    composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=rc;
+    $COMPOSER_BINARY create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=rc;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;
-    composer config repositories.ibexa composer https://updates.ibexa.co;
-    composer require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
+    $COMPOSER_BINARY config repositories.ibexa composer https://updates.ibexa.co;
+    $COMPOSER_BINARY require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
   else
-    composer create-project ibexa/$DXP_EDITION-skeleton:$DXP_VERSION . --no-interaction --no-install --ignore-platform-reqs --no-scripts;
+    $COMPOSER_BINARY create-project ibexa/$DXP_EDITION-skeleton:$DXP_VERSION . --no-interaction --no-install --ignore-platform-reqs --no-scripts;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;
   fi;
-  composer install --no-interaction --ignore-platform-reqs --no-scripts;
+  $COMPOSER_BINARY install --no-interaction --ignore-platform-reqs --no-scripts;
 fi;
 
 if [[ "$DXP_VERSION" == *".*"* ]]; then
   export COMPOSER_ROOT_VERSION=0.0.0;
-  DXP_VERSION=$(composer -n show ibexa/$DXP_EDITION | grep -E "^version" | cut -d 'v' -f 3);
+  DXP_VERSION=$($COMPOSER_BINARY -n show ibexa/$DXP_EDITION | grep -E "^version" | cut -d 'v' -f 3);
   echo "Obtained version: $DXP_VERSION";
 fi;
 
@@ -96,7 +97,7 @@ export COMPOSER_ROOT_VERSION=$DXP_VERSION;
 
 if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
   for additional_package in "${DXP_ADD_ONS[@]}"; do
-    composer require --no-interaction --ignore-platform-reqs --no-scripts --with-all-dependencies ibexa/$additional_package:$DXP_VERSION;
+    $COMPOSER_BINARY require --no-interaction --ignore-platform-reqs --no-scripts --with-all-dependencies ibexa/$additional_package:$DXP_VERSION;
   done;
 fi;
 
@@ -118,7 +119,7 @@ if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
       package=$(echo $line | cut -d '"' -f 2);
       if [[ ! "${DXP_EDITIONS[*]}" =~ "${package/ibexa\//}" ]]; then
         PACKAGE_MAP="$PACKAGE_MAP\n'$package': '$edition',"
-        NAMESPACES=$(composer show "$package" --available --format=json | \
+        NAMESPACES=$($COMPOSER_BINARY show "$package" --available --format=json | \
           jq -r --arg PACKAGE "$package" '"'\''\(.autoload | ."psr-4" | try to_entries[] catch empty | .key[:-1] | sub("\\\\";"\\\\\\";"g"))'\'': '\''\($PACKAGE)'\'',"')
         NAMESPACE_MAP="$NAMESPACE_MAP\n$NAMESPACES"
       fi;
@@ -131,7 +132,7 @@ if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
 
   echo -n 'Building namespace→edition map… ';
   for package in "${DXP_ADD_ONS[@]}"; do
-    NAMESPACES=$(composer show "ibexa/$package" --available --format=json | \
+    NAMESPACES=$($COMPOSER_BINARY show "ibexa/$package" --available --format=json | \
       jq -r --arg PACKAGE "ibexa/$package" '"'\''\(.autoload | ."psr-4" | try to_entries[] catch empty | .key[:-1] | sub("\\\\";"\\\\\\";"g"))'\'': '\''\($PACKAGE)'\'',"')
     NAMESPACE_MAP="$NAMESPACE_MAP\n$NAMESPACES"
     PACKAGE_MAP="$PACKAGE_MAP\n'ibexa/$package': 'optional',"
@@ -217,7 +218,7 @@ fi;
 if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
   echo 'Set up DXP recipes…';
   git init -b main && git add . && git commit -m "Installed Ibexa Commerce" > /dev/null;
-  composer recipes:install ibexa/$DXP_EDITION --force --reset --no-interaction;
+  $COMPOSER_BINARY recipes:install ibexa/$DXP_EDITION --force --reset --no-interaction;
 fi;
 
 echo 'Dump REST OpenAPI schema… ';

From 7b1cffe66805ec11cd97f24c8aee6db0013db070 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 10:54:33 +0200
Subject: [PATCH 03/26] api_refs.sh: Fix Composer authentication

---
 tools/api_refs/api_refs.sh | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/tools/api_refs/api_refs.sh b/tools/api_refs/api_refs.sh
index f152149606..0d23504ee0 100755
--- a/tools/api_refs/api_refs.sh
+++ b/tools/api_refs/api_refs.sh
@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 
-set -x;
+set +x;
 
-AUTH_JSON=${1:-~/.composer/auth.json}; # Path to an auth.json file allowing to install the targeted edition and version
+AUTH_JSON=$(realpath "${1:-~/.composer/auth.json}"); # Path to an auth.json file allowing to install the targeted edition and version
 PHP_API_OUTPUT_DIR=${2:-./docs/api/php_api/php_api_reference}; # Path to the directory where the built PHP API Reference is hosted
 REST_API_OUTPUT_FILE=${3:-./docs/api/rest_api/rest_api_reference/rest_api_reference.html}; # Path to the REST API Reference file
 REST_API_OPENAPI_FILE_YAML=${4:-./docs/api/rest_api/rest_api_reference/openapi.yaml}; # Path to the REST API OpenAPI spec file
@@ -63,7 +63,7 @@ cd $TMP_DXP_DIR; # /!\ Change working directory (reason why all paths must be ab
 if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
   echo "Creating ibexa/$DXP_EDITION-skeleton:$DXP_VERSION project in ${TMP_DXP_DIR}…";
   if [[ "$DXP_VERSION" == *".x-dev" ]]; then
-    composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=dev;
+    COMPOSER_AUTH="$(cat $AUTH_JSON | tr -d '\n')" composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=dev;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;
@@ -71,14 +71,14 @@ if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
     composer config extra.symfony.endpoint "https://api.github.com/repos/ibexa/recipes-dev/contents/index.json?ref=flex/main";
     composer require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
   elif [[ "$DXP_VERSION" == *"-rc"* ]]; then
-    composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=rc;
+    COMPOSER_AUTH="$(cat $AUTH_JSON | tr -d '\n')" composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=rc;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;
     composer config repositories.ibexa composer https://updates.ibexa.co;
     composer require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
   else
-    composer create-project ibexa/$DXP_EDITION-skeleton:$DXP_VERSION . --no-interaction --no-install --ignore-platform-reqs --no-scripts;
+    COMPOSER_AUTH="$(cat $AUTH_JSON | tr -d '\n')" composer create-project ibexa/$DXP_EDITION-skeleton:$DXP_VERSION . --no-interaction --no-install --ignore-platform-reqs --no-scripts;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;

From 1b4ac2895648e689bbebded0c4adca3fea311b5f Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 10:55:15 +0200
Subject: [PATCH 04/26] README.md: Update

---
 tools/api_refs/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index 12c61dbdf9..721e804b92 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -58,8 +58,8 @@ Time is saved. The DXP's code could even be modified for test purpose.
 If you change some of those values, please do not commit those changes, and don't commit their output.
 To prevent that, you can make a local copy, and use this copy to generate in a temporary output directory:
 ```bash
-cp tools/api_refs/api_refs.sh tools/api_refs/phpdoc.dev.sh
-nano phpdoc.dev.sh # Edit and make your changes. For example, change PHPDOC_CONF to use phpdoc.dev.xml.
+cp tools/api_refs/api_refs.sh tools/api_refs/api_refs.dev.sh
+nano api_refs.dev.sh # Edit and make your changes. For example, change PHPDOC_CONF to use phpdoc.dev.xml.
 nano phpdoc.dev.xml # Edit and make your changes. For example, target only your package.
 tools/api_refs/api_refs.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
 ```

From aff679f34d072cfd1e24eb61b175def03f7f142b Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 11:38:22 +0200
Subject: [PATCH 05/26] README.md: Update

---
 tools/api_refs/README.md | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index 721e804b92..a13a1df9bb 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -6,16 +6,20 @@ Requires [`jq`](https://stedolan.github.io/jq/download/)
 
 ## Basic usage
 
-`tools/api_refs/api_refs.sh` is a script generating PHP API Reference, by default, under `docs/api/php_api/php_api_reference/`.
+`tools/api_refs/api_refs.sh` is a script generating PHP & REST API References, by default, under `docs/api/php_api/php_api_reference/` and `docs/api/rest_api/rest_api_reference/`.
 
-- For Composer, if you do not use a global authentication to retrieve _Commerce_ edition, a path to an auth.json file can be given as first argument. For example:
+- For Composer, if you do not use a global authentication to retrieve _Commerce_ edition, a path to an auth.json file can be given as first optional argument. For example:
   ```
   tools/api_refs/api_refs.sh ~/www/ibexa-dxp-commerce/auth.json
   ```
-- The second argument can be a path to an output directory to use instead of the default one. For example, using the Composer global authentication file as first argument and the path to directory (which is created if it doesn't exist yet):
+- The second optional argument can be a path to an output directory to use instead of the default one. For example, using the Composer global authentication file as first argument and the path to directory (which is created if it doesn't exist yet):
   ```
   tools/api_refs/api_refs.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
   ```
+- The next three optional arguments are the REST API files
+    - 3rd arg is the reference HTML file path
+    - 4th arg is the file path for the OpenAPI specification in YAML format
+    - 5th arg is the file path for the OpenAPI specification in JSON format
 
 ## Rebuild example
 
@@ -100,3 +104,17 @@ if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
   composer require --no-interaction --ignore-platform-reqs --no-scripts ibexa/$MY_PACKAGE "$MY_BRANCH as $DXP_VERSION";
 fi;
 ```
+
+### Run as GitHub Action
+
+#### Using `gh`
+
+With [GitHub CLI `gh`](https://cli.github.com/), you can trigger a GitHub Action workflow to build the API References
+
+```bash
+gh workflow run api_refs.yaml -f version=<tag> -f use_dev_version=<false|true> --ref <branch>
+```
+
+`-f version=<tag>` to pass the Ibexa DXP version tag for which the API References are built.
+`-f use_dev_version=<false|true>` to use the released version designed by the tag, or to use the development version (`v5.0.x-dev`) for an incoming tag.
+`--ref <branch>` to use a `api_refs.yaml` workflow from a given branch instead of the default branch (`5.0`).

From fa0d44cc2c204b34c300b874f253c0fe0f66ddf1 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 11:38:55 +0200
Subject: [PATCH 06/26] README.md: Update

---
 tools/api_refs/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index a13a1df9bb..de63e9cb0b 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -117,4 +117,4 @@ gh workflow run api_refs.yaml -f version=<tag> -f use_dev_version=<false|true> -
 
 `-f version=<tag>` to pass the Ibexa DXP version tag for which the API References are built.
 `-f use_dev_version=<false|true>` to use the released version designed by the tag, or to use the development version (`v5.0.x-dev`) for an incoming tag.
-`--ref <branch>` to use a `api_refs.yaml` workflow from a given branch instead of the default branch (`5.0`).
+`--ref <branch>` to use the `api_refs.yaml` workflow from a given branch instead of the default branch (`5.0`).

From e31c3218b125a44e45ac951f14655883842b6c98 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 11:43:45 +0200
Subject: [PATCH 07/26] api_refs.yaml: base_branch as an input

---
 .github/workflows/api_refs.yaml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml
index 6d216c7d10..aedb622d20 100644
--- a/.github/workflows/api_refs.yaml
+++ b/.github/workflows/api_refs.yaml
@@ -30,7 +30,10 @@ jobs:
                   # Strip leading 'v' to get a plain version number (e.g. 5.0.9)
                   version="${{ inputs.version }}"
                   version="${version#v}"
-                  base_branch="$(echo $version | sed 's/\(.*\..*\)\..*/\1/')"
+                  base_branch="${{ inputs.base_branch }}"
+                  if [ -z "$base_branch" ]; then
+                    base_branch="$(echo $version | sed 's/\(.*\..*\)\..*/\1/')"
+                  fi
                   work_branch="api_refs_v${version}"
 
                   if [[ "${{ inputs.use_dev_version }}" == "true" ]]; then

From 6673291b89e7429950c93e616d1b234a83ae8c2f Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 11:45:38 +0200
Subject: [PATCH 08/26] README.md: Update

---
 tools/api_refs/README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index de63e9cb0b..dd4edd576a 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -112,9 +112,10 @@ fi;
 With [GitHub CLI `gh`](https://cli.github.com/), you can trigger a GitHub Action workflow to build the API References
 
 ```bash
-gh workflow run api_refs.yaml -f version=<tag> -f use_dev_version=<false|true> --ref <branch>
+gh workflow run api_refs.yaml -f version=<tag> -f use_dev_version=<false|true> --ref <branch> - f base_branch=<branch>
 ```
 
 `-f version=<tag>` to pass the Ibexa DXP version tag for which the API References are built.
 `-f use_dev_version=<false|true>` to use the released version designed by the tag, or to use the development version (`v5.0.x-dev`) for an incoming tag.
 `--ref <branch>` to use the `api_refs.yaml` workflow from a given branch instead of the default branch (`5.0`).
+`-f base_branch=<branch>` to use the `api_refs.sh` from a given branch and make a PR to that branch.

From 8f370c4f8f0d897e0c9962479629769c675b84f2 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 11:47:52 +0200
Subject: [PATCH 09/26] api_refs.yaml: base_branch as an input

---
 .github/workflows/api_refs.yaml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml
index aedb622d20..915643824a 100644
--- a/.github/workflows/api_refs.yaml
+++ b/.github/workflows/api_refs.yaml
@@ -17,6 +17,10 @@ on:
                 required: false
                 type: boolean
                 default: false
+            base_branch:
+                description: 'Use this branch of the doc to build the refs'
+                required: false
+                type: string
 
 jobs:
     open_php_api_ref_pr:

From a9456d9fde8fa5436bbf62f8d9f0324aac58373e Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 13:10:24 +0200
Subject: [PATCH 10/26] api_refs.yaml: base_branch as an input

---
 .github/workflows/api_refs.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml
index 915643824a..25bdbcbf63 100644
--- a/.github/workflows/api_refs.yaml
+++ b/.github/workflows/api_refs.yaml
@@ -42,8 +42,8 @@ jobs:
 
                   if [[ "${{ inputs.use_dev_version }}" == "true" ]]; then
                     # Dev build: install from the x-dev branch and label output with the target version
-                    dxp_version="v${base_branch}.x-dev"
-                    base_dxp_branch="${base_branch}"
+                    base_dxp_branch="$(echo $version | sed 's/\(.*\..*\)\..*/\1/')"
+                    dxp_version="v${base_dxp_branch}.x-dev"
                     virtual_dxp_version="${version}"
                   else
                     # Stable build: install from the released tag

From d965cfac82d2ce02b675811e9a842346a1cbefe4 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 15:56:48 +0200
Subject: [PATCH 11/26] tools/api_refs/README.md: More examples

---
 tools/api_refs/README.md | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index dd4edd576a..2ae75da972 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -36,7 +36,7 @@ In `tools/api_refs/api_refs.sh`:
 
 `PHPDOC_VERSION` should always target the last version of phpDocumentor.
 
-`DXP_VERSION` should target the version of Ibexa DXP Commerce corresponding to the main doc's branch.
+`DXP_VERSION` should target the version of Ibexa DXP Commerce corresponding to the doc's branch.
 
 ### Templates
 
@@ -55,9 +55,27 @@ For example, when working on the design, the set of parsed files can be reduced
 
 `PHP_BINARY` can be edited, for example, to use a different PHP version than the default, to change verbosity, or to add `-d memory_limit=-1`.
 
+```bash
+PHP_BINARY="/opt/homebrew/opt/php@8.4/bin/php -d memory_limit=-1 -d error_reporting=`php -r 'echo E_ALL & ~E_DEPRECATED;'`";
+```
+
+`COMPOSER_BINARY` can be edited, for example, to add options to `composer`, or change the PHP used with it.
+
+```bash
+COMPOSER_BINARY="$PHP_BINARY $(which composer)";
+```
+
 `FORCE_DXP_INSTALL` can be changed to `0` (zero) to have a persistent `TMP_DXP_DIR`.
 After a first run to create it, the Ibexa DXP won't be rebuilt by Composer by next runs.
 Time is saved. The DXP's code could even be modified for test purpose.
+TMP_DXP_DIR can be set to the path of a running installation.
+
+```bash
+PHP_BINARY='ddev php';
+COMPOSER_BINARY='ddev composer';
+TMP_DXP_DIR=~/my-ddev-project/;
+FORCE_DXP_INSTALL=0;
+```
 
 If you change some of those values, please do not commit those changes, and don't commit their output.
 To prevent that, you can make a local copy, and use this copy to generate in a temporary output directory:

From 0888a42d10f8f0f39396029441a85e0a0b2de45b Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 15:58:48 +0200
Subject: [PATCH 12/26] tools/api_refs/README.md: <!-- vale off -->

---
 tools/api_refs/README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index 2ae75da972..70b1b10b40 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -1,3 +1,5 @@
+<!-- vale off -->
+
 # PHP API Ref
 
 ## Install/Dependencies

From 677c093dd68bfbbea882532ec53a62cbc946e2f3 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 22 Jul 2026 16:01:42 +0200
Subject: [PATCH 13/26] tools/api_refs/README.md: Format

---
 tools/api_refs/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index 70b1b10b40..6d9daa13bb 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -70,7 +70,7 @@ COMPOSER_BINARY="$PHP_BINARY $(which composer)";
 `FORCE_DXP_INSTALL` can be changed to `0` (zero) to have a persistent `TMP_DXP_DIR`.
 After a first run to create it, the Ibexa DXP won't be rebuilt by Composer by next runs.
 Time is saved. The DXP's code could even be modified for test purpose.
-TMP_DXP_DIR can be set to the path of a running installation.
+`TMP_DXP_DIR` can be set to the path of a running installation.
 
 ```bash
 PHP_BINARY='ddev php';

From 6b95db9fb27584688be06198b05ece5818aa5eb5 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 12:17:48 +0200
Subject: [PATCH 14/26] api_refs.yaml: Add `work_branch` `force`

---
 .github/workflows/api_refs.yaml | 24 ++++++++++++++++++++++--
 tools/api_refs/README.md        | 18 ++++++++++++++++--
 2 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml
index 25bdbcbf63..2ef50462af 100644
--- a/.github/workflows/api_refs.yaml
+++ b/.github/workflows/api_refs.yaml
@@ -18,9 +18,18 @@ on:
                 type: boolean
                 default: false
             base_branch:
-                description: 'Use this branch of the doc to build the refs'
+                description: 'Start from this branch of the doc to build the refs (default: Maj.min from version)'
                 required: false
                 type: string
+            work_branch:
+                description: 'Commit builds to this branch of the doc (default: api_refs_<version>})'
+                required: false
+                type: string
+            force:
+                description: 'Push to work_branch even if it exists (default: false)'
+                required: false
+                type: boolean
+                default: false
 
 jobs:
     open_php_api_ref_pr:
@@ -38,7 +47,10 @@ jobs:
                   if [ -z "$base_branch" ]; then
                     base_branch="$(echo $version | sed 's/\(.*\..*\)\..*/\1/')"
                   fi
-                  work_branch="api_refs_v${version}"
+                  work_branch="${{ inputs.work_branch }}"
+                  if [ -z "$work_branch" ]; then
+                    work_branch="api_refs_v${version}"
+                  fi
 
                   if [[ "${{ inputs.use_dev_version }}" == "true" ]]; then
                     # Dev build: install from the x-dev branch and label output with the target version
@@ -59,6 +71,14 @@ jobs:
                   echo "base_dxp_branch=${base_dxp_branch}" >> "$GITHUB_OUTPUT"
                   echo "virtual_dxp_version=${virtual_dxp_version}" >> "$GITHUB_OUTPUT"
 
+            - name: Check if work branch exists
+              id: check_work_branch
+              if: inputs.force == false
+              run: |
+                  if git ls-remote --exit-code --heads origin "${{ steps.version_and_branches.outputs.work_branch }}"; then
+                    exit 1
+                  fi
+
             - name: Checkout documentation
               uses: actions/checkout@v4
               with:
diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index dd4edd576a..2471f368e9 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -109,13 +109,27 @@ fi;
 
 #### Using `gh`
 
-With [GitHub CLI `gh`](https://cli.github.com/), you can trigger a GitHub Action workflow to build the API References
+With [GitHub CLI `gh`](https://cli.github.com/), you can trigger a GitHub Action workflow to build the API References.
 
 ```bash
-gh workflow run api_refs.yaml -f version=<tag> -f use_dev_version=<false|true> --ref <branch> - f base_branch=<branch>
+gh workflow run api_refs.yaml -f version=<tag> -f use_dev_version=<false|true> --ref <branch> -f base_branch=<branch>
 ```
 
 `-f version=<tag>` to pass the Ibexa DXP version tag for which the API References are built.
 `-f use_dev_version=<false|true>` to use the released version designed by the tag, or to use the development version (`v5.0.x-dev`) for an incoming tag.
 `--ref <branch>` to use the `api_refs.yaml` workflow from a given branch instead of the default branch (`5.0`).
 `-f base_branch=<branch>` to use the `api_refs.sh` from a given branch and make a PR to that branch.
+
+Examples:
+
+Build from the dev branch `5.0.x-dev` API references for `v5.0.999`:
+
+```bash
+gh workflow run api_refs.yaml -f version=v5.0.999 -f use_dev_version=true
+```
+
+Rebuild references for the released version `v5.0.10` from `my-tools`'s `api_refs.yaml` with `my-tools`'s tools and commit the result into `my-api-refs` even if it already exists:
+
+```bash
+gh workflow run api_refs.yaml -f version=v5.0.10 --ref my-tools -f base_branch==my-tools -f work_branch=my-api-refs -f force=true
+```

From ee028f7d793e0d204342c1819a6304ef54da0621 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 12:18:54 +0200
Subject: [PATCH 15/26] api_refs.yaml: Add `work_branch` `force`

---
 tools/api_refs/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index 2471f368e9..267b6ba520 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -131,5 +131,5 @@ gh workflow run api_refs.yaml -f version=v5.0.999 -f use_dev_version=true
 Rebuild references for the released version `v5.0.10` from `my-tools`'s `api_refs.yaml` with `my-tools`'s tools and commit the result into `my-api-refs` even if it already exists:
 
 ```bash
-gh workflow run api_refs.yaml -f version=v5.0.10 --ref my-tools -f base_branch==my-tools -f work_branch=my-api-refs -f force=true
+gh workflow run api_refs.yaml -f version=v5.0.10 --ref my-tools -f base_branch=my-tools -f work_branch=my-api-refs -f force=true
 ```

From 869e5448509e5765340751936b95a2349634598a Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 12:22:24 +0200
Subject: [PATCH 16/26] api_refs.yaml: Add `work_branch` `force`

---
 tools/api_refs/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index 267b6ba520..5b4a3adc0a 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -112,13 +112,15 @@ fi;
 With [GitHub CLI `gh`](https://cli.github.com/), you can trigger a GitHub Action workflow to build the API References.
 
 ```bash
-gh workflow run api_refs.yaml -f version=<tag> -f use_dev_version=<false|true> --ref <branch> -f base_branch=<branch>
+gh workflow run api_refs.yaml -f version=<tag> -f use_dev_version=<false|true> --ref <branch> -f base_branch=<branch> -f work_branch=<branch> -f force=<false|true>
 ```
 
 `-f version=<tag>` to pass the Ibexa DXP version tag for which the API References are built.
 `-f use_dev_version=<false|true>` to use the released version designed by the tag, or to use the development version (`v5.0.x-dev`) for an incoming tag.
 `--ref <branch>` to use the `api_refs.yaml` workflow from a given branch instead of the default branch (`5.0`).
 `-f base_branch=<branch>` to use the `api_refs.sh` from a given branch and make a PR to that branch.
+`-f work_branch=<branch>` to use a given target branch to commit the build and make a PR from that branch.
+`-f force=<false|true>` to force the commit on the target branch even if it already exists.
 
 Examples:
 

From 72edb9a8b465cc49e57fbc4b9b6e42ed066d9ebd Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 12:27:52 +0200
Subject: [PATCH 17/26] api_refs.yaml: Add `work_branch` `force`

---
 tools/api_refs/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index 5b4a3adc0a..86f008e822 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -133,5 +133,5 @@ gh workflow run api_refs.yaml -f version=v5.0.999 -f use_dev_version=true
 Rebuild references for the released version `v5.0.10` from `my-tools`'s `api_refs.yaml` with `my-tools`'s tools and commit the result into `my-api-refs` even if it already exists:
 
 ```bash
-gh workflow run api_refs.yaml -f version=v5.0.10 --ref my-tools -f base_branch=my-tools -f work_branch=my-api-refs -f force=true
+gh workflow run api_refs.yaml -f version=v5.0.10 --ref my-builder -f base_branch=my-builder -f work_branch=my-api-refs -f force=true
 ```

From 820de147585c753edcdf3f3c7a2f190305b36e64 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 14:21:04 +0200
Subject: [PATCH 18/26] api_refs.yaml: Fix `force`

fatal: 'origin' does not appear to be a git repository
---
 .github/workflows/api_refs.yaml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml
index 2ef50462af..9ef0e5c646 100644
--- a/.github/workflows/api_refs.yaml
+++ b/.github/workflows/api_refs.yaml
@@ -71,6 +71,11 @@ jobs:
                   echo "base_dxp_branch=${base_dxp_branch}" >> "$GITHUB_OUTPUT"
                   echo "virtual_dxp_version=${virtual_dxp_version}" >> "$GITHUB_OUTPUT"
 
+            - name: Checkout documentation
+              uses: actions/checkout@v4
+              with:
+                  ref: ${{ steps.version_and_branches.outputs.base_branch }}
+
             - name: Check if work branch exists
               id: check_work_branch
               if: inputs.force == false
@@ -79,11 +84,6 @@ jobs:
                     exit 1
                   fi
 
-            - name: Checkout documentation
-              uses: actions/checkout@v4
-              with:
-                  ref: ${{ steps.version_and_branches.outputs.base_branch }}
-
             - name: Disable PHP coverage
               uses: shivammathur/setup-php@v2
               with:

From 5b7a3b3fe4a2f53a2a34a34503cc97f47875640f Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 14:35:55 +0200
Subject: [PATCH 19/26] api_refs.yaml: Fix `force`

fatal: 'origin' does not appear to be a git repository
---
 .github/workflows/api_refs.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml
index 9ef0e5c646..9f30acffe8 100644
--- a/.github/workflows/api_refs.yaml
+++ b/.github/workflows/api_refs.yaml
@@ -81,6 +81,7 @@ jobs:
               if: inputs.force == false
               run: |
                   if git ls-remote --exit-code --heads origin "${{ steps.version_and_branches.outputs.work_branch }}"; then
+                    echo "::error title=Branch exists::The branch ${{ steps.version_and_branches.outputs.work_branch }} already exists. You can use the 'force' option to overwrite it."
                     exit 1
                   fi
 

From d3a8b2d418da34d87bd6450cf2678aa58db571c2 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 15:54:46 +0200
Subject: [PATCH 20/26] api_refs.yaml: Fix vulnerability w/ Copilot

Hey, Do you know how to execute the following security suggestion in github action @api_refs.yaml?:

inputs.base_branch is vulnerable to script injection: values of inputs are provided by whoever triggers the workflow. Change this workflow to not use user-controlled data directly in a run block, for example by assigning this expression to an environment variable.
---
 .github/workflows/api_refs.yaml | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml
index 9f30acffe8..10274317c8 100644
--- a/.github/workflows/api_refs.yaml
+++ b/.github/workflows/api_refs.yaml
@@ -39,22 +39,27 @@ jobs:
         steps:
             - name: Set version and branches
               id: version_and_branches
+              env:
+                  INPUT_VERSION: ${{ inputs.version }}
+                  INPUT_BASE_BRANCH: ${{ inputs.base_branch }}
+                  INPUT_WORK_BRANCH: ${{ inputs.work_branch }}
+                  INPUT_USE_DEV_VERSION: ${{ inputs.use_dev_version }}
               run: |
                   # Strip leading 'v' to get a plain version number (e.g. 5.0.9)
-                  version="${{ inputs.version }}"
+                  version="$INPUT_VERSION"
                   version="${version#v}"
-                  base_branch="${{ inputs.base_branch }}"
+                  base_branch="$INPUT_BASE_BRANCH"
                   if [ -z "$base_branch" ]; then
-                    base_branch="$(echo $version | sed 's/\(.*\..*\)\..*/\1/')"
+                    base_branch="$(echo "$version" | sed 's/\(.*\..*\)\..*/\1/')"
                   fi
-                  work_branch="${{ inputs.work_branch }}"
+                  work_branch="$INPUT_WORK_BRANCH"
                   if [ -z "$work_branch" ]; then
                     work_branch="api_refs_v${version}"
                   fi
 
-                  if [[ "${{ inputs.use_dev_version }}" == "true" ]]; then
+                  if [[ "$INPUT_USE_DEV_VERSION" == "true" ]]; then
                     # Dev build: install from the x-dev branch and label output with the target version
-                    base_dxp_branch="$(echo $version | sed 's/\(.*\..*\)\..*/\1/')"
+                    base_dxp_branch="$(echo "$version" | sed 's/\(.*\..*\)\..*/\1/')"
                     dxp_version="v${base_dxp_branch}.x-dev"
                     virtual_dxp_version="${version}"
                   else

From a399a1955e63a72ff1fff0c1c9738ffbd5514b29 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 16:07:16 +0200
Subject: [PATCH 21/26] Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
---
 .github/workflows/api_refs.yaml |  2 +-
 tools/api_refs/README.md        | 12 ++++++------
 tools/api_refs/api_refs.sh      |  4 ++--
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml
index 10274317c8..cc51f8b54a 100644
--- a/.github/workflows/api_refs.yaml
+++ b/.github/workflows/api_refs.yaml
@@ -22,7 +22,7 @@ on:
                 required: false
                 type: string
             work_branch:
-                description: 'Commit builds to this branch of the doc (default: api_refs_<version>})'
+                description: 'Commit builds to this branch of the doc (default: api_refs_<version>)'
                 required: false
                 type: string
             force:
diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index 86f008e822..ae89730eb7 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -17,9 +17,9 @@ Requires [`jq`](https://stedolan.github.io/jq/download/)
   tools/api_refs/api_refs.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
   ```
 - The next three optional arguments are the REST API files
-    - 3rd arg is the reference HTML file path
-    - 4th arg is the file path for the OpenAPI specification in YAML format
-    - 5th arg is the file path for the OpenAPI specification in JSON format
+    - 3rd argument is the reference HTML file path
+    - 4th argument is the file path for the OpenAPI specification in YAML format
+    - 5th argument is the file path for the OpenAPI specification in JSON format
 
 ## Rebuild example
 
@@ -63,9 +63,9 @@ If you change some of those values, please do not commit those changes, and don'
 To prevent that, you can make a local copy, and use this copy to generate in a temporary output directory:
 ```bash
 cp tools/api_refs/api_refs.sh tools/api_refs/api_refs.dev.sh
-nano api_refs.dev.sh # Edit and make your changes. For example, change PHPDOC_CONF to use phpdoc.dev.xml.
-nano phpdoc.dev.xml # Edit and make your changes. For example, target only your package.
-tools/api_refs/api_refs.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
+nano tools/api_refs/api_refs.dev.sh # Edit and make your changes. For example, change PHPDOC_CONF to use phpdoc.dev.xml.
+nano tools/api_refs/phpdoc.dev.xml # Edit and make your changes. For example, target only your package.
+tools/api_refs/api_refs.dev.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
 ```
 
 ### Creating a build of dev version
diff --git a/tools/api_refs/api_refs.sh b/tools/api_refs/api_refs.sh
index 0d23504ee0..559c9375e7 100755
--- a/tools/api_refs/api_refs.sh
+++ b/tools/api_refs/api_refs.sh
@@ -2,7 +2,7 @@
 
 set +x;
 
-AUTH_JSON=$(realpath "${1:-~/.composer/auth.json}"); # Path to an auth.json file allowing to install the targeted edition and version
+AUTH_JSON=$(realpath ${1:-~/.composer/auth.json}); # Path to an auth.json file allowing to install the targeted edition and version
 PHP_API_OUTPUT_DIR=${2:-./docs/api/php_api/php_api_reference}; # Path to the directory where the built PHP API Reference is hosted
 REST_API_OUTPUT_FILE=${3:-./docs/api/rest_api/rest_api_reference/rest_api_reference.html}; # Path to the REST API Reference file
 REST_API_OPENAPI_FILE_YAML=${4:-./docs/api/rest_api/rest_api_reference/openapi.yaml}; # Path to the REST API OpenAPI spec file
@@ -63,7 +63,7 @@ cd $TMP_DXP_DIR; # /!\ Change working directory (reason why all paths must be ab
 if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
   echo "Creating ibexa/$DXP_EDITION-skeleton:$DXP_VERSION project in ${TMP_DXP_DIR}…";
   if [[ "$DXP_VERSION" == *".x-dev" ]]; then
-    COMPOSER_AUTH="$(cat $AUTH_JSON | tr -d '\n')" composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=dev;
+    COMPOSER_AUTH="$(tr -d '\n' < $AUTH_JSON)" composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=dev;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;

From 14f74d51e014befcb39c3a52efbfcadf10a7f7de Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 16:17:07 +0200
Subject: [PATCH 22/26] Test $AUTH_JSON file existence

---
 tools/api_refs/api_refs.sh | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/tools/api_refs/api_refs.sh b/tools/api_refs/api_refs.sh
index 559c9375e7..1c5331febf 100755
--- a/tools/api_refs/api_refs.sh
+++ b/tools/api_refs/api_refs.sh
@@ -2,7 +2,7 @@
 
 set +x;
 
-AUTH_JSON=$(realpath ${1:-~/.composer/auth.json}); # Path to an auth.json file allowing to install the targeted edition and version
+AUTH_JSON=$(realpath ${1:-~/.composer/auth.json}); # Path to an auth.json file allowing to install the targeted edition and version
 PHP_API_OUTPUT_DIR=${2:-./docs/api/php_api/php_api_reference}; # Path to the directory where the built PHP API Reference is hosted
 REST_API_OUTPUT_FILE=${3:-./docs/api/rest_api/rest_api_reference/rest_api_reference.html}; # Path to the REST API Reference file
 REST_API_OPENAPI_FILE_YAML=${4:-./docs/api/rest_api/rest_api_reference/openapi.yaml}; # Path to the REST API OpenAPI spec file
@@ -61,6 +61,11 @@ fi;
 cd $TMP_DXP_DIR; # /!\ Change working directory (reason why all paths must be absolute)
 
 if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
+  if [ ! -f $AUTH_JSON ]; then
+    echo "Credentials file ${AUTH_JSON} doesn't exist.";
+    exit 3;
+  fi;
+
   echo "Creating ibexa/$DXP_EDITION-skeleton:$DXP_VERSION project in ${TMP_DXP_DIR}…";
   if [[ "$DXP_VERSION" == *".x-dev" ]]; then
     COMPOSER_AUTH="$(tr -d '\n' < $AUTH_JSON)" composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=dev;

From 2ac2957940ec0a535fcfb3c2bbdaa45f8556c71c Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 23 Jul 2026 16:57:52 +0200
Subject: [PATCH 23/26] Apply suggestions from code review

Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
---
 tools/api_refs/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index ae89730eb7..af7a4143a6 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -107,7 +107,7 @@ fi;
 
 ### Run as GitHub Action
 
-#### Using `gh`
+#### By using `gh`
 
 With [GitHub CLI `gh`](https://cli.github.com/), you can trigger a GitHub Action workflow to build the API References.
 

From 4d11558cb3c9ec2b1998d729f66f1c4f1d271d70 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Fri, 24 Jul 2026 09:23:36 +0200
Subject: [PATCH 24/26] Test $AUTH_JSON file existence

---
 tools/api_refs/api_refs.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/api_refs/api_refs.sh b/tools/api_refs/api_refs.sh
index f5ef0a724b..26efb47fe2 100755
--- a/tools/api_refs/api_refs.sh
+++ b/tools/api_refs/api_refs.sh
@@ -77,14 +77,14 @@ if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
     $COMPOSER_BINARY config extra.symfony.endpoint "https://api.github.com/repos/ibexa/recipes-dev/contents/index.json?ref=flex/main";
     $COMPOSER_BINARY require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
   elif [[ "$DXP_VERSION" == *"-rc"* ]]; then
-    COMPOSER_AUTH="$(cat $AUTH_JSON | tr -d '\n')" $COMPOSER_BINARY create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=rc;
+    COMPOSER_AUTH="$(tr -d '\n' < $AUTH_JSON)" $COMPOSER_BINARY create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=rc;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;
     $COMPOSER_BINARY config repositories.ibexa composer https://updates.ibexa.co;
     $COMPOSER_BINARY require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
   else
-    COMPOSER_AUTH="$(cat $AUTH_JSON | tr -d '\n')" $COMPOSER_BINARY create-project ibexa/$DXP_EDITION-skeleton:$DXP_VERSION . --no-interaction --no-install --ignore-platform-reqs --no-scripts;
+    COMPOSER_AUTH="$(tr -d '\n' < $AUTH_JSON)" $COMPOSER_BINARY create-project ibexa/$DXP_EDITION-skeleton:$DXP_VERSION . --no-interaction --no-install --ignore-platform-reqs --no-scripts;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;

From f2c809dc423f17c188327b44a471b3527fdf27ad Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Fri, 24 Jul 2026 09:23:36 +0200
Subject: [PATCH 25/26] Test $AUTH_JSON file existence

---
 tools/api_refs/api_refs.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/api_refs/api_refs.sh b/tools/api_refs/api_refs.sh
index 1c5331febf..d4989cb162 100755
--- a/tools/api_refs/api_refs.sh
+++ b/tools/api_refs/api_refs.sh
@@ -76,14 +76,14 @@ if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
     composer config extra.symfony.endpoint "https://api.github.com/repos/ibexa/recipes-dev/contents/index.json?ref=flex/main";
     composer require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
   elif [[ "$DXP_VERSION" == *"-rc"* ]]; then
-    COMPOSER_AUTH="$(cat $AUTH_JSON | tr -d '\n')" composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=rc;
+    COMPOSER_AUTH="$(tr -d '\n' < $AUTH_JSON)" composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=rc;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;
     composer config repositories.ibexa composer https://updates.ibexa.co;
     composer require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
   else
-    COMPOSER_AUTH="$(cat $AUTH_JSON | tr -d '\n')" composer create-project ibexa/$DXP_EDITION-skeleton:$DXP_VERSION . --no-interaction --no-install --ignore-platform-reqs --no-scripts;
+    COMPOSER_AUTH="$(tr -d '\n' < $AUTH_JSON)" composer create-project ibexa/$DXP_EDITION-skeleton:$DXP_VERSION . --no-interaction --no-install --ignore-platform-reqs --no-scripts;
     if [ -n "$AUTH_JSON" ]; then
       cp $AUTH_JSON ./;
     fi;

From 7e8504bd62b6daf426ae7f45ffb001c18a04bcf9 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Tue, 28 Jul 2026 11:26:57 +0200
Subject: [PATCH 26/26] README.md: "By using web UI" section

---
 tools/api_refs/README.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md
index a04d5142cb..2600077666 100644
--- a/tools/api_refs/README.md
+++ b/tools/api_refs/README.md
@@ -155,3 +155,8 @@ Rebuild references for the released version `v5.0.10` from `my-tools`'s `api_ref
 ```bash
 gh workflow run api_refs.yaml -f version=v5.0.10 --ref my-builder -f base_branch=my-builder -f work_branch=my-api-refs -f force=true
 ```
+
+#### By using web UI
+
+On the GitHub repository page, go to the "Actions" tab and, in the workflow list, select ["Build API Refs"](https://github.com/ibexa/documentation-developer/actions/workflows/api_refs.yaml).
+On top right of the past workflow table, unfold "Run workflow" menu, set the fields, then click "Run workflow" button.