Add a manually-triggered site publishing workflow

[slachiewicz]

Part of #58. The last item on the plan.

Site publishing is entirely manual today and was documented differently in six READMEs, two of which contradicted their own POM. That shows up in the gh-pages dates, which ranged from May 2023 to June 2026 before this effort started. This gives every project one button.

Deliberately workflow_dispatch, not release-triggered

I raised this earlier on #58 and it still seems right: publishing on release puts unreviewed content live automatically, takes the release manager out of the loop, and Maven site builds break often enough — doxia, site plugin, JDK interactions — that I would rather a person saw the output. This makes the procedure repeatable without making it unattended.

Easy to promote to release-triggered later if it proves boring.

The authentication problem, and how this solves it

The POMs derive pubScmUrl from scm.developerConnection, which is:

scm:git:ssh://git@github.com:codehaus-plexus/plexus-utils.git

An ssh URL cannot authenticate with the job token, so the plugin would fail. The workflow overrides it to https and supplies the credential through a git rewrite rule:

git config --global "url.https://x-access-token:${GH_TOKEN}@github.com/.insteadOf" "https://github.com/"

That keeps the token out of the command line and the process list, which passing -Dscmpublish.pubScmUrl=https://token@… would not. Checkout runs with persist-credentials: false.

No new secret is needed — permissions: contents: write on the job is enough for the token to push to that repository's own gh-pages.

Handles both project layouts

	Goals	content
single-module (10 repos)	site-deploy	target/site, set in each POM
multi-module (4 repos)	site site:stage scm-publish:publish-scm	target/staging — the plugin default

I checked the plugin descriptor rather than assuming: content defaults to ${project.build.directory}/staging, which is exactly what site:stage produces. So the multi-module input switches goals and needs no other configuration.

Property names are from the plugin descriptor too — scmpublish.pubScmUrl, scmpublish.scm.branch, scmpublish.content, scmpublish.dryRun.

dry-run

Builds the site and checks out gh-pages without committing or pushing. The first use of this in any repository should be a dry run.

Concurrency

cancel-in-progress: false, grouped per repository. Two concurrent runs would race on gh-pages, and cancelling one mid-push is worse than queueing.

Callers come next

Once this merges, each repository needs a small caller. I'll do two first so the shape can be reviewed before the sweep:

name: Publish Site
on:
  workflow_dispatch:
jobs:
  site:
    uses: codehaus-plexus/.github/.github/workflows/site.yml@master

and for the multi-module ones:

    with:
      multi-module: true

That is modello, plexus-compiler, plexus-languages and plexus-interactivity.

Note this cannot be end-to-end tested until it is on master, since workflow_call resolves against a ref — which is the other reason for the dry-run input.

[Copilot]

Pull request overview

Introduces a reusable GitHub Actions workflow intended to provide a single, manually triggered (“one button”) procedure for generating and publishing Maven project sites to the gh-pages branch across repositories in the codehaus-plexus org.

Changes:

• Adds a reusable workflow_call workflow to build and publish Maven sites.
• Supports both single-module and multi-module site publishing flows, plus a dry-run mode.
• Configures Git authentication for pushing to gh-pages using the job token.

Suppressed comments (2)

.github/workflows/site.yml:90

• This expression references a hyphenated input name (maven-version) via dot notation. Use bracket notation (inputs['maven-version']) to avoid the expression being parsed as subtraction and failing at runtime.

        run: mvn --errors --batch-mode --show-version org.apache.maven.plugins:maven-wrapper-plugin:3.2.0:wrapper "-Dtype=only-script" "-Dmaven=${{ inputs.maven-version }}"

.github/workflows/site.yml:109

• Hyphenated inputs (multi-module, dry-run) are accessed with dot notation here, which GitHub Actions will parse as arithmetic (e.g. inputs.multi-module). Use bracket notation for these input names so the conditional goals selection and dry-run flag work.

          ./mvnw ${{ inputs.maven_args }} \
            ${{ inputs.multi-module && 'site site:stage scm-publish:publish-scm' || 'site-deploy' }} \
            "-Dscmpublish.pubScmUrl=scm:git:https://github.com/${{ github.repository }}.git" \
            "-Dscmpublish.scm.branch=gh-pages" \
            "-Dscmpublish.dryRun=${{ inputs.dry-run }}" \

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[slachiewicz]

Thanks — I checked this one rather than applying it, and I believe the review is mistaken. No change made; here is the evidence.

The claim: hyphenated input names cannot be read with dot notation, because inputs.jdk-version parses as inputs.jdk minus version.

This organisation's existing shared workflows already do exactly that, and have been running across every repository here for a long time:

maven.yml:112        os:           ${{ fromJSON( inputs.os-matrix ) }}
maven.yml:113        jdk:          ${{ fromJSON( inputs.jdk-matrix ) }}
maven.yml:114        distribution: ${{ fromJSON( inputs.jdk-distribution-matrix ) }}
maven.yml:115        exclude:      ${{ fromJSON( inputs.matrix-exclude ) }}
maven.yml:94         java-version: ${{ inputs.jdk-fast-fail-build }}
maven-deploy.yml:45  github.ref == inputs.branch-to-deploy
maven-deploy.yml:59  java-version: ${{ inputs.jdk-version }}

inputs.jdk-matrix is the strongest case: if it were parsed as subtraction it would evaluate to a number, fromJSON would not produce a list, and no matrix would be generated. Instead it expands to [ "25", "21", "8" ] and produces the jobs named ubuntu-latest jdk-8-zulu, macos-latest jdk-21-zulu and so on — which is what ran, green, on every PR in this effort today.

GitHub's own reusable-workflow documentation uses the same form in its worked example (inputs.config-path).

So dot notation on hyphenated inputs is fine, and switching to bracket notation would make this workflow inconsistent with the two shared workflows beside it for no benefit.

Two things worth saying about the risk, since I would rather not be quietly wrong here:

• If I have this backwards, it fails loudly and immediately — an unparseable expression is a startup error, not a subtle misbehaviour.
• The dry-run input exists for precisely this. The first run of this workflow in any repository should be a dry run, which builds the site and checks out gh-pages without committing anything.

Happy to be shown otherwise if someone has a counter-example.