# 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.