CI/CD and Generated Docs | Identity Service User Guide

Workflow triggers

The Identity Service CI/CD workflow runs for:

pull requests targeting master;
pushes to master.

Both event types execute project verification and Docker validation. Only a successful push to master assembles and deploys GitHub Pages; pull requests never deploy.

Verification job

Check out the repository and configure Temurin Java 21 with Maven dependency caching.
Run mvn -B -ntp clean verify, including unit and Testcontainers integration tests.
Validate that JaCoCo and generated OpenAPI reports exist.
Validate the source User Guide pages required by the Pages artifact.
Run docker compose config.
Run docker compose build app.

Any compilation, test, report-generation, documentation-source, Compose, or image-build failure stops the workflow.

Pages assembly and deployment

After verification succeeds on master, Maven generates the technical site and CI assembles an ignored pages/ staging directory:

pages/
  index.html
  styles.css
  script.js
  user-guide/
  openapi/
  coverage/
  maven-site/

The workflow validates the expected index files before uploading the artifact. It then uses the official configure-pages, upload-pages-artifact, and deploy-pages actions with deployment permissions isolated to the deploy job.

Repository Settings must configure Pages with Source: GitHub Actions. A local commit does not update the public site until it is pushed to master and the workflow completes successfully.

Generated documentation

Documentation	Local output	Published path
OpenAPI HTML	`target/openapi-docs`	`/openapi/`
JaCoCo HTML	`target/site/jacoco`	`/coverage/`
Maven site	`target/site`	`/maven-site/`
JavaDoc	`target/site/apidocs`	`/maven-site/apidocs/`

Generate the Maven site locally after verification:

mvn site

Source and generated ownership

Edit: docs/, src/site/, OpenAPI YAML, mapper interfaces, and handwritten Java.
Do not edit: generated OpenAPI code, MapStruct implementations, target/openapi-docs, target/site, or assembled pages/.
Do not commit: target/, pages/, local environment files, logs, or IDE metadata.

The HTML User Guide is direct source under docs/user-guide/; it is intentionally not generated from Markdown and is reviewed like the dashboard.