From 0fb79d44a79e52fd6bb4fa5431165b31ef356621 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Tue, 18 Aug 2026 14:08:43 +0200 Subject: [PATCH] Drop the shared site-publishing workflow It was reusable-only and had exactly one caller, plexus-utils, so RELEASING.md's claim that "every project has a Publish Site workflow" was true of one repo out of nineteen. Finishing the rollout would mean a caller workflow in each repo; we would rather publish sites from a local checkout, which is what the section above already documents and what has happened in practice. The reasoning for not publishing on release moves up into that section, since it is the reason there is no workflow at all now, not a footnote to one. --- .github/workflows/site.yml | 163 ------------------------------------- RELEASING.md | 15 +--- 2 files changed, 3 insertions(+), 175 deletions(-) delete mode 100644 .github/workflows/site.yml diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml deleted file mode 100644 index c1ec213..0000000 --- a/.github/workflows/site.yml +++ /dev/null @@ -1,163 +0,0 @@ -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - -name: Publish Site - -on: - workflow_call: - inputs: - multi-module: - description: 'Stage the site before publishing. Required for reactors with modules.' - required: false - default: false - type: boolean - - dry-run: - description: 'Build and check out gh-pages, but do not commit or push.' - required: false - default: false - type: boolean - - publish-branch: - description: 'Branch the built site is committed to. gh-pages for project sites; master for the organisation page.' - required: false - default: 'gh-pages' - type: string - - maven_args: - description: 'Goals and arguments used to build the site' - required: false - default: '--batch-mode --errors --show-version -Preporting clean verify' - type: string - - maven-version: - description: 'The Maven version used to build the site' - required: false - default: '3.9.11' - type: string - - jdk-version: - description: 'JDK used to build the site' - required: false - default: '21' - type: string - - jdk-distribution: - description: 'JDK distribution used to build the site' - required: false - default: 'temurin' - type: string - -# one publish at a time: two concurrent runs would race on gh-pages -concurrency: - group: publish-site-${{ github.repository }} - cancel-in-progress: false - -jobs: - publish-site: - name: Publish Site - - if: github.repository_owner == 'codehaus-plexus' - - runs-on: ubuntu-latest - - permissions: - # maven-scm-publish-plugin commits the generated site to the gh-pages branch - contents: write - - steps: - - name: Checkout - uses: actions/checkout@v7 - with: - persist-credentials: false - - - name: Set up JDK - uses: actions/setup-java@v5 - with: - java-version: ${{ inputs.jdk-version }} - distribution: ${{ inputs.jdk-distribution }} - cache: 'maven' - - - name: Set up Maven - 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 }}" - - - name: Build site - run: ./mvnw ${{ inputs.maven_args }} ${{ inputs.multi-module && 'site site:stage' || 'site' }} - - - name: Publish site - # maven-scm-publish-plugin is not used to do the push here. The POMs configure - # its pubScmUrl explicitly, which means an explicitly configured value always - # wins over the -Dscmpublish.pubScmUrl user property, so the ssh URL from - # scm.developerConnection cannot be overridden from the command line - and ssh - # cannot authenticate with the job token. Pushing with git directly keeps the - # whole step under the workflow's control. - env: - GH_TOKEN: ${{ github.token }} - BRANCH: ${{ inputs.publish-branch }} - DRY_RUN: ${{ inputs.dry-run }} - CONTENT: ${{ inputs.multi-module && 'target/staging' || 'target/site' }} - run: | - set -euo pipefail - - if [ ! -d "$CONTENT" ]; then - echo "::error::the site build produced no $CONTENT directory" - exit 1 - fi - - remote="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - - if git ls-remote --exit-code --heads "$remote" "$BRANCH" >/dev/null 2>&1; then - git clone --branch "$BRANCH" --depth 1 --quiet "$remote" .site-publish - else - echo "branch $BRANCH does not exist yet; creating it" - git clone --depth 1 --quiet "$remote" .site-publish - git -C .site-publish checkout --orphan "$BRANCH" - git -C .site-publish rm -rq --cached . || true - find .site-publish -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} + - fi - - # mirror the built site over the branch content, so pages deleted upstream - # also disappear from the published site - rsync -a --delete --exclude '.git' "$CONTENT"/ .site-publish/ - - cd .site-publish - git config user.name "github-actions[bot]" - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git add -A - - if git diff --cached --quiet; then - echo "site is unchanged; nothing to publish" - exit 0 - fi - - # sed rather than head: head exits after 50 lines, which SIGPIPEs git status, - # and under `set -o pipefail` that aborts the whole step with exit 141 - changed=$(git diff --cached --name-only | wc -l) - git status --short | sed -n '1,50p' - if [ "$changed" -gt 50 ]; then - echo "... and $((changed - 50)) more" - fi - echo "$changed file(s) changed" - - if [ "$DRY_RUN" = "true" ]; then - echo "::notice::dry run - not committing or pushing" - exit 0 - fi - - git commit -qm "Site checkin for ${GITHUB_REPOSITORY}@${GITHUB_SHA}" - git push --quiet origin "$BRANCH" - echo "::notice::published to $BRANCH" diff --git a/RELEASING.md b/RELEASING.md index dd81903..5c9fc87 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -66,18 +66,9 @@ That covers modello, plexus-compiler, plexus-languages and plexus-interactivity. The `-Preporting` profile is what adds the Javadoc, JXR and surefire reports. Without it you publish a site with no API documentation, which is worse than not republishing at all. -## Publishing from GitHub Actions - -Every project has a **Publish Site** workflow, run from the Actions tab. It does the same thing as the commands above, so you do not need a local checkout or credentials: - -- **multi-module** — set by the caller workflow, not by you -- **dry-run** — builds the site and checks out `gh-pages` without committing. Worth using the first time you publish a given project. - -The job token pushes to that repository's own `gh-pages`; there is no secret to configure. - -### Why it isn't automatic - -The workflow is triggered by hand rather than on release. Publishing puts content live with no review step, and Maven site builds break often enough — doxia, site plugin and JDK interactions — that we would rather a person saw the output before it goes up. +Sites are published from a local checkout. There is no workflow for it: publishing puts content live with +no review step, and Maven site builds break often enough — doxia, site plugin and JDK interactions — that +the person doing it should see the output first. ## Snapshot deployment