Add CI/CD workflow documentation

docs/operations/cicd-workflow.md

@@ -0,0 +1,295 @@
+# 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:
+
+```bash
+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
+```bash
+systemctl status forgejo-runner-docker.service
+systemctl status forgejo-runner-host.service
+```
+
+### Check runner service enablement
+```bash
+systemctl is-enabled forgejo-runner-docker.service
+systemctl is-enabled forgejo-runner-host.service
+```
+
+### Check runner logs
+```bash
+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.

mkdocs.yml

@@ -50,7 +50,8 @@ nav:
   - Policies:
       - Policy Repository: "policies/index.md"
   - Operations:
-      - Operations Overview: "operations/index.md"
+      - Operations Overview: operations/index.md
+      - CI/CD Workflow: operations/cicd-workflow.md
   - Standards:
       - Standards Overview: "standards/index.md"
   - Integrations: