[Enhancement] Optimize CI workflows to skip Java tests on docs-only changes

[ongdisheng]

Search before asking

• I searched in the issues and found nothing similar.

Motivation

Currently all Java CI workflows run on every PR even when only documentation files are changed. This wastes CI resources and slows down PR checks. For example, PR #702 only changed website/community/contribution.md but still triggered all Java CI tests including license check, spotless, tests across 5 JDK versions, CodeQL scan, etc.

Solution

Propose to add paths filtering to ci.yml and codeql-scan.yml so they only run when Java source code or Maven configs change:

paths:
  - '.github/workflows/ci.yml'
  - '**/pom.xml'
  - 'fesod/**'
  - 'fesod-*/**'
  - '!**.md'

Alternatives

No response

Anything else?

Are you willing to submit a PR?

• I'm willing to submit a PR!

[delei]

Hi, @ongdisheng
Good idea.

IMO, We could start by making the “Check Licence Header” a standalone workflow. Any PR must require a license header check.

[ongdisheng]

IMO, We could start by making the “Check Licence Header” a standalone workflow. Any PR must require a license header check.

@delei Sure, Iet me work on this.

[delei]

Hi, @ongdisheng
How about providing a separate GitHub workflow for Doc CI? It would only be effective when there are changes to the files in the website directory.

FYI, due to the fact that the CI for the preview document still has some issues at present, I suggest that it might be more appropriate to use a single CI for now.

[ongdisheng]

Hi @delei, Thank you for the suggestion! Just to clarify and make sure if I understand correctly: are you suggesting we combine deploy-docs.yml and the PR preview workflows into fewer files since they share similar build steps? I'm thinking of creating two consolidated workflows:

1. ci-docs.yml: Combined build and production deployment

Click to expand

name: Documentation CI

on:
  push:
    branches: [main]
    paths: ['website/**']
  pull_request:
    paths: ['website/**']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 8
          run_install: false
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Corepack
        working-directory: website
        run: npm i -g --force corepack && corepack enable
      - name: Install Dependencies
        working-directory: website
        run: pnpm install
      - name: Build
        working-directory: website
        run: pnpm build
      
      # For PRs: upload artifact
      - name: Upload artifact
        if: github.event_name == 'pull_request'
        uses: actions/upload-artifact@v4
        with:
          name: website
          path: website/build
          retention-days: 7
      
      # For main branch: deploy to GitHub Pages
      - name: Copy asf file
        if: github.event_name == 'push' && github.repository == 'apache/fesod'
        run: cp .asf.yaml ./website/build/.asf.yaml
      
      - name: Deploy to GitHub Pages
        if: github.event_name == 'push' && github.repository == 'apache/fesod'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: website/build
          publish_branch: gh-pages
          force_orphan: true

2. ci-docs-netlify.yml: Secure Netlify preview deployment

Click to expand

name: Deploy Netlify Preview

on:
  workflow_run:
    workflows: ["Documentation CI"]
    types: [completed]

jobs:
  preview:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Download artifact
        uses: actions/github-script@v7
        with:
          script: |
            const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
               owner: context.repo.owner,
               repo: context.repo.repo,
               run_id: ${{ github.event.workflow_run.id }},
            });
            const websiteArtifact = artifacts.data.artifacts.filter((artifact) => {
              return artifact.name == 'website'
            })[0];
            var download = await github.rest.actions.downloadArtifact({
               owner: context.repo.owner,
               repo: context.repo.repo,
               artifact_id: websiteArtifact.id,
               archive_format: 'zip',
            });
            const fs = require('fs');
            fs.writeFileSync('${{github.workspace}}/website.zip', Buffer.from(download.data));

      - name: Unzip artifact
        run: unzip -q website.zip -d website/build

      - name: Deploy preview to Netlify
        id: netlify
        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654
        with:
          publish-dir: './website/build'
          production-deploy: false
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-message: "Deploy preview for PR #${{ github.event.workflow_run.pull_requests[0].number }}"
          enable-pull-request-comment: false
          enable-commit-comment: false
          enable-commit-status: false
          enable-github-deployment: false
          alias: deploy-preview-${{ github.event.workflow_run.pull_requests[0].number }}
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
        timeout-minutes: 10

      - name: Comment on PR
        uses: actions-cool/maintain-one-comment@4b2dbf086015f892dcb5e8c1106f5fccd6c1476b
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          number: ${{ github.event.workflow_run.pull_requests[0].number }}
          body: |
            🚀 Preview is ready at: ${{ steps.netlify.outputs.deploy-url }}
            <!-- Netlify Preview Comment -->
          body-include: '<!-- Netlify Preview Comment -->'

Logic flow:

• For PRs: ci-docs.yml builds and uploads artifact -> ci-docs-netlify.yml downloads and deploys to Netlify for secure fork PRs
• For main branch push: ci-docs.yml builds and deploys directly to GitHub Pages

Just wondering if is this what you had in mind? 😊

[delei]

Please allow me to explain. I hope this new ci-docs.yml can merge and override the current markdownlint.yml CI and achieve the following goals:

• Introduce markdownlint-cli2 to inspect Markdown files ( Please refer to and merge markdownlint.yml).
• Ensure successful install and build.
• If preview-docs.yml functions correctly, the final preview will be generated in Netlify.

BTW, deploy-docs.yml should remain unchanged. This is the CI process for the separate ASF website.

[ongdisheng]

Hi @delei, Thank you for the clarification! Now, I got a better understanding. Probably we can try with these:

1. ci-docs.yml: Combined markdown linting and build for PRs

on:
  pull_request:
    paths: ['website/**']

jobs:
  lint-and-build:
    - Check which files changed in the PR
    - Lint Markdown (only if .md files changed)
      - Run markdownlint-cli2 
      - Fail if lint errors found
    - Setup pnpm and Node.js
    - Enable corepack
    - Install dependencies (pnpm install)
    - Build website (pnpm build)
    - Upload artifact (website/build) 

2. ci-docs-preview.yml or preview-docs.yml: Netlify preview deployment

on:
  workflow_run:
    workflows: ["Documentation CI"]
    types: [completed]

jobs:
  preview:
    - Download artifact
    - Unzip artifact
    - Deploy to Netlify
    - Comment on PR with preview link

3. deploy-docs.yml: Keep unchanged

Does this match what you're looking for? 😊

[delei]

No need to upload artifacts (website/build) in ci-docs.yml.

Regarding preview-docs.yml, it appears there are still unresolved issues. Please leave it as is until it functions correctly and meets the requirements.

[ongdisheng]

Hi @delei, understood! I'll work on ci-docs.yml first without the artifact uploading part.

[ongdisheng]

Hi @delei, I noticed the markdownlint step in ci-docs which was taken from the previous markdownlint.yml workflow seems to have an issue as it appears to be failing to detect changed files as shown in 1 and 2:

fatal: ambiguous argument 'origin/main...feature/test_preview_20251123': unknown revision or path not in the working tree.
No markdown files changed, skipping lint.

It looks like the bash script might not be able to find the git reference in some cases, causing the linting to be skipped even when there are markdown changes. I was wondering if we could consider using GitHub Actions instead:

• ana06/get-changed-files: Gets changed markdown files
• DavidAnson/markdownlint-cli2-action: Lints those files

This might be simpler and could work more consistently. I've tested it in my repo link and it seems to work well. Just wondering what's your take on this approach?

[delei]

I have reviewed the historical action logs you marked. It seems there is indeed a problem. Please feel free to submit the PR.