Allowed building dev version of the API references from Github Actions (#3173)

* Allowed building dev version of the API references from Github Actions

* Added GitHub token to the workflow

* Added Readme

* Update .github/workflows/api_refs.yaml

Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>

* Apply suggestion from @adriendupuis

---------

Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>

Author: mnocon

.github/workflows/api_refs.yaml

@@ -4,9 +4,19 @@ on:
     workflow_dispatch:
         inputs:
             version:
-                description: 'Released version tag (for example: v4.6.21 or v5.0.0)'
+                # The version to build the API Reference for.
+                # Use a released tag (e.g. v5.0.9) or a plain number (e.g. 5.0.9).
+                description: 'Version (e.g. v5.0.9 or 5.0.9)'
                 required: true
                 type: string
+            use_dev_version:
+                # When checked, Composer installs from the x-dev branch instead of a released tag.
+                # Useful for building a reference before the final release is tagged.
+                # Example: version=5.0.9 + use_dev_version=true → DXP_VERSION=v5.0.x-dev, BASE_DXP_BRANCH=5.0, VIRTUAL_DXP_VERSION=5.0.9
+                description: 'Use x-dev branch (default: false)'
+                required: false
+                type: boolean
+                default: false
 
 jobs:
     open_php_api_ref_pr:
@@ -17,12 +27,30 @@ jobs:
             - name: Set version and branches
               id: version_and_branches
               run: |
+                  # Strip leading 'v' to get a plain version number (e.g. 5.0.9)
                   version="${{ inputs.version }}"
-                  base_branch="$(echo $version | sed 's/v\(.*\..*\)\..*/\1/')"
-                  work_branch="api_refs_$version"
-                  echo "version=$version" >> "$GITHUB_OUTPUT"
-                  echo "base_branch=$base_branch" >> "$GITHUB_OUTPUT"
-                  echo "work_branch=$work_branch" >> "$GITHUB_OUTPUT"
+                  version="${version#v}"
+                  base_branch="$(echo $version | sed 's/\(.*\..*\)\..*/\1/')"
+                  work_branch="api_refs_v${version}"
+
+                  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}"
+                    virtual_dxp_version="${version}"
+                  else
+                    # Stable build: install from the released tag
+                    dxp_version="v${version}"
+                    base_dxp_branch=""
+                    virtual_dxp_version=""
+                  fi
+
+                  echo "version=v${version}" >> "$GITHUB_OUTPUT"
+                  echo "base_branch=${base_branch}" >> "$GITHUB_OUTPUT"
+                  echo "work_branch=${work_branch}" >> "$GITHUB_OUTPUT"
+                  echo "dxp_version=${dxp_version}" >> "$GITHUB_OUTPUT"
+                  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
@@ -39,13 +67,30 @@ jobs:
             - name: Install Redocly CLI
               run: npm install -g @redocly/cli@latest
 
+            - name: Generate token
+              id: generate_token
+              if: inputs.use_dev_version == true
+              uses: actions/create-github-app-token@v2
+              with:
+                  app-id: ${{ secrets.AUTOMATION_CLIENT_ID }}
+                  private-key: ${{ secrets.AUTOMATION_CLIENT_SECRET }}
+                  owner: ibexa
+
             - name: Build API Refs
               env:
                   SATIS_NETWORK_KEY: ${{ secrets.SATIS_NETWORK_KEY }}
                   SATIS_NETWORK_TOKEN: ${{ secrets.SATIS_NETWORK_TOKEN }}
+                  GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
                   BASE_BRANCH: ${{ steps.version_and_branches.outputs.base_branch }}
+                  DXP_VERSION: ${{ steps.version_and_branches.outputs.dxp_version }}
+                  BASE_DXP_BRANCH: ${{ steps.version_and_branches.outputs.base_dxp_branch }}
+                  VIRTUAL_DXP_VERSION: ${{ steps.version_and_branches.outputs.virtual_dxp_version }}
               run: |
+                  if [ -n "$GITHUB_TOKEN" ]; then
+                    composer config --global github-oauth.github.com "$GITHUB_TOKEN"
+                  fi
                   composer config --global http-basic.updates.ibexa.co $SATIS_NETWORK_KEY $SATIS_NETWORK_TOKEN
+
                   if [[ '4.6' != $BASE_BRANCH ]]; then
                     tools/api_refs/api_refs.sh
                     # Fix escape character:

tools/api_refs/README.md

@@ -64,6 +64,20 @@ nano phpdoc.dev.xml # Edit and make your changes. For example, target only your
 tools/api_refs/api_refs.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
 ```
 
+### Creating a build of dev version
+
+To build the reference for an unreleased version, set the following variables:
+
+- `DXP_VERSION`
+- `BASE_DXP_BRANCH`
+- `VIRTUAL_DXP_VERSION`
+
+For example, to build the API Reference based on the development version of the DXP before the 5.0.10 release, run:
+
+``` bash
+DXP_VERSION=v5.0.x-dev BASE_DXP_BRANCH=5.0 VIRTUAL_DXP_VERSION=5.0.10 tools/api_refs/api_refs.sh ~/my/path/to/auth.json
+```
+
 ### Test a branch
 
 To load a package on a development branch instead of a released version,

tools/api_refs/api_refs.sh

@@ -9,7 +9,7 @@ REST_API_OPENAPI_FILE_YAML=${4:-./docs/api/rest_api/rest_api_reference/openapi.y
 REST_API_OPENAPI_FILE_JSON=${5:-./docs/api/rest_api/rest_api_reference/openapi.json}; # Path to the REST API OpenAPI spec file
 
 DXP_EDITION='commerce'; # Edition from and for which the Reference is built
-DXP_VERSION='5.0.*'; # Version from and for which the Reference is built
+DXP_VERSION="${DXP_VERSION:-5.0.*}"; # Version from and for which the Reference is built; can be overridden by the DXP_VERSION env var (e.g. v5.0.x-dev for a dev build)
 DXP_ADD_ONS=(automated-translation rector integrated-help fieldtype-richtext-rte connector-anthropic connector-gemini shopping-list cdp connector-raptor connector-quable mcp); # Packages not included in $DXP_EDITION but added to the Reference, listed without their vendor "ibexa"
 DXP_EDITIONS=(oss headless experience commerce); # Available editions ordered by ascending capabilities
 SF_VERSION='7.4'; # Symfony version used by Ibexa DXP
@@ -26,8 +26,8 @@ OPENAPI_FIX="$(pwd)/tools/api_refs/openapi.php"; # A script editing and fixing f
 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
 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=''; # Branch from and for which the Reference is built when using a dev branch as version
-VIRTUAL_DXP_VERSION=''; # Version for which the reference is supposedly built when using dev branch as version
+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
+VIRTUAL_DXP_VERSION="${VIRTUAL_DXP_VERSION:-}"; # Version for which the reference is supposedly built when using dev branch as version; can be overridden by the VIRTUAL_DXP_VERSION env var
 
 if [ ! -d $PHP_API_OUTPUT_DIR ]; then
   echo -n "Creating ${PHP_API_OUTPUT_DIR}… ";