CI/CD with GitHub Actions

The project ships with two GitHub Actions workflows:

Workflow file	Trigger	What it does
maven-site-integration.yml	Push to any branch + cron	Build, test, Maven site, deploy to Pages
sphinx-docs.yml	Push to main	Build Sphinx docs + merge into GitHub Pages

---

Workflow 1: maven-site-integration.yml

This is the main CI/CD workflow. It:

1. Starts a MySQL 8 Docker service

2. Waits for the database to be healthy

3. Runs the DB initialisation script

4. Executes integration tests (-Pintegration)

5. Generates the full Maven site (Javadoc, JaCoCo, PMD, Checkstyle, Surefire)

6. Copies all Maven site output + Doxygen into the docs/site/ and docs/doxygen/ sub-folders

7. Deploys the docs/ directory to GitHub Pages

name: Maven Site & Integration Tests

on:
  push:
    branches: ['**']
  schedule:
    - cron: '0 18-23/2 * * *'
    - cron: '0 0-6/2 * * *'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: libraryapidb
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping -h 127.0.0.1 -uroot -proot"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=5

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Cache Maven
        uses: actions/cache@v4
        with:
          path: ~/.m2/repository
          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}

      - name: Wait for MySQL
        run: |
          until mysqladmin ping -h 127.0.0.1 -uroot -proot --silent; do sleep 2; done

      - name: Init database
        run: mysql -h 127.0.0.1 -uroot -proot < src/main/resources/dbsetup.sql

      - name: Integration tests
        run: mvn -Pintegration integration-test

      - name: Maven site
        run: mvn site

      - name: Publish docs to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
          destination_dir: .    # serve from root of gh-pages branch
          keep_files: true       # keep Sphinx output from the other workflow

---

Workflow 2: sphinx-docs.yml

This workflow builds the Sphinx documentation and deploys it to the gh-pages branch alongside the Maven site output, without overwriting it.

name: Build and Deploy Sphinx Docs

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  sphinx:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install Sphinx dependencies
        run: |
          pip install -r docs-sphinx/requirements.txt

      - name: Build Sphinx HTML
        run: |
          cd docs-sphinx
          make html

      - name: Deploy Sphinx to GitHub Pages (sphinx/ subfolder)
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs-sphinx/_build/html
          destination_dir: sphinx   # → gh-pages/sphinx/
          keep_files: true

---

GitHub Pages Setup

To enable GitHub Pages for this repository:

1. Go to Settings → Pages

2. Set Source to gh-pages branch, root /

3. Save — the site will be live at https://<owner>.github.io/SpringBootLibrary/

Permissions: Go to Settings → Actions → General → Workflow permissions and set Read and write permissions so that the GITHUB_TOKEN can push to the gh-pages branch.

---

Triggering Workflows via API

curl -X POST \
  https://api.github.com/repos/<owner>/SpringBootLibrary/actions/workflows/sphinx-docs.yml/dispatches \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $PAT_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -d '{"ref":"main"}'