From 01b3c77fd9e1bc89a091872c1d4456c9eb851f3c Mon Sep 17 00:00:00 2001 From: Mike Kell Date: Sun, 29 Mar 2026 20:42:57 -0400 Subject: [PATCH] Add CI/CD workflow documentation --- docs/operations/cicd-workflow.md | 295 +++++++++++++++++++++++++++++++ mkdocs.yml | 3 +- 2 files changed, 297 insertions(+), 1 deletion(-) create mode 100644 docs/operations/cicd-workflow.md diff --git a/docs/operations/cicd-workflow.md b/docs/operations/cicd-workflow.md new file mode 100644 index 0000000..a9c92db --- /dev/null +++ b/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. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index c67ea53..e3dacd4 100644 --- a/mkdocs.yml +++ b/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: