kell_creations/docs/operations/cicd-workflow.md

CI/CD Workflow

This document defines the standard continuous integration and continuous delivery workflow for the Kell Creations Platform documentation environment.

Purpose

The purpose of this workflow is to ensure that:

• documentation changes are validated automatically
• production documentation is published only from the main branch
• validation and publishing are separated by branch behavior
• Forgejo, runners, and the Ubuntu documentation host remain synchronized
• the documentation pipeline is auditable, repeatable, and maintainable

Scope

This workflow applies to:

• MkDocs documentation
• PlantUML and C4-based architecture documentation
• workflow files under .forgejo/workflows/
• the Forgejo runners used for validation and publishing
• the published site at docs.kellsupport.com

Platforms and Services

Source control and automation

• Forgejo repository: git.kellsupport.com
• Forgejo Actions workflows: .forgejo/workflows/

Authoring environment

• Windows 11 workstation
• VS Code
• local Git working copy

Build and publish environment

• Ubuntu 24.04.4 LTS on kellsupport.com
• Docker / Docker Compose
• MkDocs Material container
• published site path:
  • /opt/kellcreations/docs-platform/published/site/

Rendering and published services

• PlantUML server: plantuml.kellsupport.com
• documentation site: docs.kellsupport.com

Workflow Model

The CI/CD design separates validation from publishing.

Validation workflow

Validation runs on non-main branches.

Its purpose is to:

• check that MkDocs builds successfully
• verify expected site output is created
• catch documentation errors before changes reach main

Publish workflow

Publishing runs only on the main branch.

Its purpose is to:

• build the MkDocs site
• synchronize generated output to the published site directory
• update the live documentation site automatically

Branch Behavior

Main branch

• triggers: Publish Docs
• result: build and publish to live documentation site

Non-main branches

• triggers: Validate Docs
• result: build only, no publish

Workflow Files

Publish workflow

File:

/.forgejo/workflows/publish-docs.yml

Purpose:

• build MkDocs
• sync generated site to:
  • /opt/kellcreations/docs-platform/published/site/

Validation workflow

File:

/.forgejo/workflows/validate-docs.yml

Purpose:

• build MkDocs
• verify expected output exists
• do not publish

Runner Architecture

Two Forgejo runners are used.

Docker runner

Purpose:

• supports container-oriented CI tasks
• available for future isolated workloads

Runner label:

• docker

Systemd service:

• forgejo-runner-docker.service

Host publish runner

Purpose:

• runs workflows directly on the Ubuntu host
• required for workflows that need direct host access to:
  • Docker
  • rsync
  • published site path

Runner label:

• docs-host

Systemd service:

• forgejo-runner-host.service

Why the host runner is required

The documentation publishing workflow must:

• run Docker commands on the host
• access the local published site directory
• synchronize files directly to the live docs path

Because of that, the publish workflow uses the host runner instead of the Docker-labeled runner.

Published Site Permissions Model

The published docs directory uses a shared group model.

Shared group

• group name: kellcreations-docs

Group members

• mtkell
• runner

Permission design

• owner remains administrative
• shared group allows both manual administration and automated publishing
• setgid is applied to directories so new files inherit the shared group

This prevents ownership conflicts between manual updates and automated workflow execution.

Standard CI/CD Process

1. Author changes on Windows

The author updates documentation, diagrams, or workflow files in the local Git repository using VS Code.

2. Commit and push changes

The author commits changes and pushes them to Forgejo.

3. Forgejo triggers the correct workflow

• non-main branch pushes trigger validation
• main branch pushes trigger publishing

4. Runner executes workflow

The assigned runner processes the job based on the workflow label.

5. MkDocs site is built

The workflow runs the MkDocs Material container to build the site.

6. Publish step runs only on main

For the publish workflow, generated output is synchronized to the live documentation path.

7. Live site is updated

The published content is immediately served by docs.kellsupport.com.

Publish Command

The publish workflow uses:

rsync -rlDz --delete site/ /opt/kellcreations/docs-platform/published/site/

This avoids unnecessary permission and metadata preservation issues while still ensuring the site is synchronized correctly.

Validation Checks

The validation workflow currently confirms:

• MkDocs builds successfully
• site/index.html exists
• site/architecture exists

These checks can be expanded later to include:

• broken-link validation
• Markdown linting
• PlantUML validation
• required document metadata checks

Operational Verification

Check runner service status

systemctl status forgejo-runner-docker.service
systemctl status forgejo-runner-host.service

Check runner service enablement

systemctl is-enabled forgejo-runner-docker.service
systemctl is-enabled forgejo-runner-host.service

Check runner logs

journalctl -u forgejo-runner-docker.service -f
journalctl -u forgejo-runner-host.service -f

Troubleshooting

Validation workflow fails with docker: command not found

Cause:

• workflow is running in the wrong execution environment

Correction:

• use the docs-host runner for workflows that need host Docker access

Publish workflow fails with Permission denied

Cause:

• publish target directory permissions or group membership are incorrect

Correction:

• verify shared group membership
• verify setgid permissions on published directories
• confirm the runner session has been restarted after group changes

Workflow does not start

Cause:

• no matching runner label
• runner offline
• workflow file path or syntax issue

Correction:

• confirm runner is online in Forgejo
• confirm workflow runs-on label matches an available runner label
• review workflow YAML syntax

Published site does not update

Cause:

• build succeeded but publish step failed
• rsync target path incorrect
• permissions on published directory incorrect

Correction:

• inspect workflow logs
• confirm target path exists
• verify group permissions and runner access

Security and Administrative Notes

• runner registration tokens must not be stored in the repository
• exposed runner tokens must be rotated immediately
• host runners should be limited to narrowly defined workflows
• workflow changes should be reviewed before merging to main

Future Enhancements

Potential next improvements include:

• pull-request validation if enabled in Forgejo
• documentation linting
• PlantUML diagram validation
• automated link checking
• notification hooks for failed publishes
• environment promotion model for staging and production docs

Summary

This CI/CD workflow ensures that Kell Creations documentation is validated before publication, published automatically from main, and maintained through a controlled, auditable pipeline using Forgejo Actions, dedicated runners, MkDocs, and the Ubuntu documentation host.