⬅️ Back to Deployment Index

CI/CD & Documentation Pipeline

Overview

Smart Supply Pro uses GitHub Actions for fully automated continuous integration and continuous deployment. Three coordinated workflows ensure code is tested, documented, and deployed:

1. 1️⃣ Backend CI – Build & Test (1-ci-test.yml) – Compile, test, build Docker image, scan for CVEs
2. 2️⃣ Documentation Pipeline (docs-pipeline.yml + 2-deploy-ghpages.yml) – Generate API/architecture docs, publish to GitHub Pages
3. 3️⃣ Deployment to Fly.io (3-deploy-fly.yml) – Deploy to production (automatic after CI passes)

This document explains the workflow coordination, key steps, and how documentation is generated and published.

Workflow Architecture

Workflow 1️⃣: CI Build & Test (1-ci-test.yml)

Trigger

• Push to main or develop branch
• Changes in: backend source, pom.xml, Dockerfile, CI workflow itself
• Manual trigger: workflow_dispatch

Pipeline Steps

Example: Build & Test Step

mvn -U clean verify \
  -Dspring.profiles.active=test \
  -Dtestcontainers.enabled=false

Flags: - -U – Update snapshots (fresh dependencies) - clean verify – Full lifecycle (compile → test → package → verify) - -Dspring.profiles.active=test – Use H2 database, test config - -Dtestcontainers.enabled=false – Skip Docker-based integration tests in CI

Security Gate: Trivy Vulnerability Scan

After image is built and pushed:

trivy image ckbuzin/inventory-service:${IMAGE_TAG_SHA} \
  --severity CRITICAL,HIGH \
  --exit-code 1

Behavior: - Scans image for known CVEs in OS packages and libraries - Reports only CRITICAL and HIGH severity - Blocks deployment if vulnerabilities found (exit-code: 1) - Allows deployment if no HIGH/CRITICAL (LOW/MEDIUM/unknown are logged)

Example failure:

CRITICAL   3 vulnerabilities found in base image
  - openssl 3.0.0 → Use 3.0.5 or later
  - glibc 2.31 → Use 2.34 or later
Exit code: 1 → Deployment blocked

Resolution: 1. Update base image in Dockerfile (e.g., newer eclipse-temurin:17-jre) 2. Or update vulnerable library in pom.xml 3. Push new commit → Re-run CI → Retry scan

Artifacts Produced

Workflow 2️⃣: Documentation Pipeline (docs-pipeline.yml + 2-deploy-ghpages.yml)

Trigger

• Automatic: After 1-ci-test.yml succeeds (via workflow_run)
• Manual: Direct push to main if docs/ or scripts/ changed

Key Insight: Dual-Trigger Design

Why two triggers?

1. After CI (workflow_run): Rebuild docs whenever code changes
   • Ensures OpenAPI, coverage, architecture stay fresh
   • Consumes JaCoCo artifact from CI
2. Direct push (direct trigger): Rapid docs-only updates
   • Allows emergency doc fixes without rebuilding code
   • Skips JaCoCo (optional, not always available)

Step 1: Build Documentation (docs-pipeline.yml)

Tools Used

Documentation Structure

docs-site/
├── index.html                    # Portal entry point
├── api/
│   ├── openapi.html             # Swagger/ReDoc interactive
│   └── index.html               # API overview
├── architecture/
│   ├── overview.html
│   ├── layers/
│   ├── resources/
│   ├── deployment/
│   └── ...                       # All architecture guides as HTML
├── backend/
│   ├── coverage/                # JaCoCo HTML report (from CI)
│   │   ├── index.html
│   │   ├── inventory-service/
│   │   └── ... (line-by-line coverage)
│   └── api/
└── ...

Build Scripts

scripts/build-openapi-docs.sh

#!/bin/bash
PROJECT_DIR=$1

# Install Redocly CLI (or use pre-installed)
npm install -g @redocly/cli

# Convert OpenAPI YAML → ReDoc HTML
redocly build-docs \
  $PROJECT_DIR/docs/api/openapi/openapi.yaml \
  -o $PROJECT_DIR/target/docs/api/openapi.html

scripts/build-architecture-docs.sh

#!/bin/bash
PROJECT_DIR=$1

# Install Pandoc
apt-get install pandoc

# Convert each markdown file to HTML with Lua filter for mermaid
for file in $PROJECT_DIR/docs/architecture/**/*.md; do
  output_file="${file%.md}.html"
  pandoc "$file" \
    --filter /path/to/mermaid-filter.lua \
    --template template.html \
    -o "$output_file"
done

Lua Filter for Mermaid (mermaid-filter.lua)

function CodeBlock(el)
  if el.classes:includes("mermaid") then
    -- Wrap in <div class="mermaid"> for mermaid.js to render
    return pandoc.RawBlock(
      'html',
      '<div class="mermaid">' .. el.text .. '</div>'
    )
  end
end

When HTML is served, mermaid.js renders the diagrams client-side.

Step 2: Publish to GitHub Pages (2-deploy-ghpages.yml)

Why Separate Workflow?

• Separation of concerns: Build docs ≠ publish docs
• Artifact staging: docs-site is intermediate artifact
• Coverage preservation: If current build skips coverage, old coverage is retained
• Deployment safety: Can republish without rebuilding

Steps

- name: Checkout gh-pages branch
  uses: actions/checkout@v4
  with:
    ref: gh-pages
    fetch-depth: 0

- name: Download docs-site artifact
  uses: actions/download-artifact@v4
  with:
    name: docs-site

- name: Preserve JaCoCo coverage if missing
  run: |
    if [ ! -d "docs-site/backend/coverage" ] && [ -d "backend/coverage" ]; then
      # Current build doesn't have coverage, but old one does
      mkdir -p /tmp/coverage-backup
      cp -R backend/coverage /tmp/coverage-backup/
      # ... (later restore)
    fi

- name: Sync docs-site to gh-pages root
  run: |
    # Remove everything except .git and docs-site
    find . -mindepth 1 -maxdepth 1 ! -name '.git' ! -name 'docs-site' -exec rm -rf {} +
    # Copy docs-site contents to root
    cp -R docs-site/* .
    # Restore coverage if preserved
    # ...

- name: Commit and push to gh-pages
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    
    if git status --porcelain | grep .; then
      git add .
      git commit -m "docs: publish docs-site"
      git push origin gh-pages
    else
      echo "No changes to publish"
    fi

Output: Live Documentation

After push to gh-pages, documentation is live at:

https://keglev.github.io/inventory-service/

Site structure: - / → index.html (portal) - /api/ → OpenAPI/ReDoc documentation - /architecture/ → Architecture guides (deployment, resources, etc.) - /backend/coverage/ → JaCoCo test coverage report

Workflow 3️⃣: Deploy to Fly.io (3-deploy-fly.yml)

See Fly.io Infrastructure for detailed deployment steps.

Quick Summary

• Trigger: Automatic after CI success, OR manual via workflow_dispatch
• Steps:
  1. Validate Docker image exists in registry
  2. Verify Fly.io app exists
  3. Deploy: flyctl deploy --image {SHA} --strategy immediate
  4. Health check: Poll /health until HEALTHY (5-min timeout)
  5. Smoke tests: Validate API endpoints
  6. Report status

Artifact Flow Diagram

Scripts Organization

/scripts/ Directory

scripts/
├── build-openapi-docs.sh      # Redocly: OpenAPI YAML → HTML
├── build-architecture-docs.sh # Pandoc: Markdown → HTML
├── mermaid-filter.lua         # Pandoc filter for mermaid diagrams
├── deploy-docs-scripts/       # (Optional) local deployment helpers
└── ...

These scripts are invoked by docs-pipeline.yml in CI environment.

Troubleshooting

Docs Build Fails: “Redocly CLI not found”

• Ensure npm install -g @redocly/cli in workflow step
• Check npm version compatibility (Node.js 20+)
• Review Redocly syntax: redocly lint docs/api/openapi.yaml

Pandoc Conversion Fails: “Command not found”

• Install Pandoc: apt-get install pandoc
• Verify Lua filter path is correct
• Check Markdown syntax (review .md file)

Mermaid Diagrams Not Rendering

• Verify Lua filter is wrapping code block in <div class="mermaid">
• Ensure HTML includes: <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
• Check diagram syntax: mmdc -i diagram.md -o diagram.html

JaCoCo Coverage Missing from Docs

• Normal for docs-only pushes (JaCoCo only generated by CI)
• 2-deploy-ghpages.yml preserves old coverage if current build skips it
• To refresh coverage: Re-run 1-ci-test.yml

gh-pages Push Fails: “Permission denied”

• Verify GitHub token has contents: write permission
• Check branch is gh-pages (case-sensitive)
• Ensure git user is configured: git config user.name/email

Docs Artifacts Too Large

• Review what’s in docs-site/ artifact
• Remove unnecessary images, large generated files
• Compress coverage HTML if needed
• Consider cleanup: find . -name "*.tmp" -delete

Related Documentation

• Deployment Index – Overview of entire pipeline
• Build & Docker Image – Maven and Docker build details
• Fly.io Infrastructure – Production deployment
• Architecture Overview – System design

Last Updated: November 2025
Audience: DevOps engineers, documentation maintainers, CI/CD administrators