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 ./mvnw -B -ntp clean verify with the committed Maven version, 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.

OpenAPI compatibility policy

Contract-changing pull requests run oasdiff 1.35.0, verified by SHA-256, against the contract at the exact PR base commit. Unchanged contracts skip the tool; pushes retain the normal verification and publication flow.

The gate fails on oasdiff error-level incompatibilities: removed operations or response properties, new required request fields, tighter accepted request constraints, removed accepted enum values, and incompatible types. The policy in .github/oasdiff-levels.txt also protects optional response properties from removal. Warnings remain visible without failing the build. Additive operations and optional request fields are allowed when existing clients remain compatible.

Preserve existing v1/v2 operations when introducing another API version. A version-label change alone does not authorize breaking existing paths. The CLI processes repository files locally without uploading contracts or requiring an account.

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/
  badges/
    coverage.json
  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:

./mvnw 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.