295 lines
7.3 KiB
Markdown
295 lines
7.3 KiB
Markdown
# 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. |