ci: better support PR from fork for preview build and ref validation (#…

…698)

Let pass the git repo url to the preview script:
  - Only valid for a branch preview for a component.
- This allows you to use an alternative URL to the one configured for
the component, in particular to use a fork.

The "build-and-publish-pr-preview" and the "build-pr-site" (used for
references validation) actions set this new argument to use the git URL
of the branch of the PR
This ensures that the git URL of the repository whose the PR is
originated from is used (fork or upstream repository).

Covers #402

.github/actions/build-and-publish-pr-preview/README.md

@@ -1,6 +1,8 @@
 # build and publish pr preview
 
-**WARN**: Only work on Ubuntu runners
+**WARN**: Only work
+- with Pull Requests
+- on Ubuntu runners
 
 Manage the surge preview deployment. In particular, teardown the surge deployment when closing the Pull Request.
 

.github/actions/build-and-publish-pr-preview/action.yml

@@ -48,7 +48,7 @@ runs:
     - name: Build Setup
       uses: ./.github/actions/build-setup
       if: github.event.action != 'closed'
-    - name: Build Site without error check
+    - name: Build Site for a single component
       if: github.event.action != 'closed' && inputs.component-name != ''
       shell: bash
       # '>' Replace newlines with spaces (folded)
@@ -57,12 +57,13 @@ runs:
         ./build-preview.bash
         --branch "${{ github.head_ref }}"
         --component "${{inputs.component-name}}"
+        --component-repo-url "${{github.event.pull_request.head.repo.clone_url}}"
         --fail-on-warning "${{inputs.fail-on-warning}}"
         --fetch-sources true
         --ignore-errors "${{inputs.ignore-errors}}"
         --pr "${{ github.event.pull_request.number }}"
         --site-url "${{ steps.surge-preview-tools.outputs.preview-url }}"
-    - name: Build Site
+    - name: Build Site with custom build-preview command
       if: github.event.action != 'closed' && inputs.component-name == ''
       shell: bash
       # '>' Replace newlines with spaces (folded)

.github/actions/build-pr-site/action.yml

@@ -3,8 +3,12 @@ description: 'Build site from a PR to check if all xref references are valid'
 
 inputs:
   build-preview-command:
-    description: 'The documentation `build-preview` command to build the preview'
-    required: true
+    description: 'The documentation `build-preview` command to build the preview and validate references. Mandatory when `component-name` is not set. Otherwise, ignored.'
+    required: false
+  component-name:
+    description: 'The name of the component to build. If set, the build-preview-command input is ignored'
+    required: false
+    default: ''
   # needed by content repository (default master) and here (computed automagically)
   doc-site-branch:
     description: 'The branch of the `bonita-documentation-site` used to build the site preview'
@@ -30,7 +34,21 @@ runs:
     - name: Install antora dependencies for xref validation
       shell: bash
       run: npm install --save-dev antora@3.2.0-alpha.4
-    - name: Build Site
+    - name: Build Site for a single component
+      if: inputs.component-name != ''
+      shell: bash
+      # '>' Replace newlines with spaces (folded)
+      # '-' No newline at end (strip)
+      run: >-
+        ./build-preview.bash
+        --branch "${{ github.head_ref }}"
+        --component "${{inputs.component-name}}"
+        --component-repo-url "${{github.event.pull_request.head.repo.clone_url}}"
+        --fail-on-warning "${{inputs.fail-on-warning}}"
+        --fetch-sources true
+        --pr "${{ github.event.pull_request.number }}"
+    - name: Build Site with custom build-preview command
+      if: inputs.component-name == ''
       shell: bash
       # '>' Replace newlines with spaces (folded)
       # '-' No newline at end (strip)

build-preview.bash

@@ -26,6 +26,7 @@ function usage() {
   echo "Antora configuration"
   echo "      --branch <branch-name>                  Name of the branch when keeping a single branch per component"
   echo "      --component <component-name>            Name of the component when keeping a single branch per component"
+  echo "      --component-repo-url <url>              Only relevant when keeping a single branch per component. Override the configured git repository URL for the provided component"
   echo "      --component-with-branches <form>        Components and branches when using 'Multiple Repositories'."
   echo "                                              Pass one argument per component. For instance, --component-with-branches bcd:3.4 --component-with-branches bonita:7.11,2021.1"
   echo "      --default-ui-bundle <parameter>         If set, use the Antora Default UI. If set to 'snapshot', fetch the bundle instead of retrieving it from the cache. Defaults to 'false'"

lib/antora/log-aggregated-component-versions-extension.js

@@ -9,13 +9,14 @@ module.exports.register = function () {
   const logger = this.getLogger('bonita-log-aggregated-component');
 
   this.once('contentAggregated', ({ contentAggregate }) => {
-    logger.info('Discovered the following component versions')
+    logger.info('Start discovering component versions')
     contentAggregate.forEach((bucket) => {
       logger.info(`name: ${bucket.name}, version: ${bucket.version}, files: ${bucket.files.length}`)
       if (logger.isLevelEnabled('debug')) {
         const sources = bucket.origins.map(({url, refname}) => ({url, refname}));
         logger.debug('sources: %o', sources);
       }
     })
+    logger.info('Done discovery of component versions')
   })
 }

scripts/generate-content-for-preview-antora-playbook.js

@@ -138,7 +138,15 @@ else {
 
     // override the sources: only the single branch of the single component
     const repoUrl = getRepoUrl(componentName);
-    doc.content.sources = [{ url: repoUrl, branches: [branchName] }];
+    console.info(`Configured repo URL for the component: ${repoUrl}`);
+    // if provided a specific repository, use it. Calling getRepoUrl validates that the component is known
+    const repoUrlArg = getArgument(argv, 'component-repo-url', false);
+    if (repoUrlArg) {
+        console.info(`--> Overriding repo URL with the provided argument: ${repoUrlArg}`);
+        doc.content.sources = [{ url: repoUrlArg, branches: [branchName] }];
+    } else {
+        doc.content.sources = [{ url: repoUrl, branches: [branchName] }];
+    }
 
     const titlePreviewPart = prNumber ? `PR #${prNumber}` : `branch '${branchName}'`;
     doc.site.title = siteTitle || `Preview ${componentName} ${titlePreviewPart}`;