MokoCLI/docs/WORKFLOW_STANDARDS.md

# Workflow Standards

> Canonical reference for Gitea Actions CI/CD workflows across all Moko Consulting repositories.

## Architecture

```
Template Repos (canonical source)     →  Production Repos (synced copies)
─────────────────────────────────────    ──────────────────────────────────
MokoStandards-Template-Joomla         →  MokoOnyx, MokoCassiopeia, MokoJGDPC, etc.
MokoStandards-Template-Dolibarr       →  MokoCRM, MokoDoliForm, MokoDoliAuth, etc.
MokoStandards-Template-Generic        →  MokoISOUpdatePortable, etc.
MokoStandards-Template-Client         →  client-clarksvillefurs, client-kiddieland
```

**MokoOnyx** is the living reference implementation for Joomla workflows. Template repos are the **single source of truth** for workflow content. The MokoStandards-API repo does NOT store workflow templates — its sync engine (`RepositorySynchronizer.php`) clones template repos at runtime to get the latest workflows.

### How Sync Works

```
bulk-repo-sync.yml (API repo)
  → RepositorySynchronizer.php detects platform type
  → Clones the matching template repo to /tmp/
  → Copies .gitea/workflows/*.yml from template → target repo
```

No workflow files are stored in the API repo. This prevents drift.

## Template Repos

| Repo | Purpose | Types |
|------|---------|-------|
| `MokoStandards-Template-Joomla` | All Joomla extension types in one repo | plugin, template, module, component, package, library |
| `MokoStandards-Template-Dolibarr` | Dolibarr module scaffold | — |
| `MokoStandards-Template-Generic` | Non-platform projects | — |
| `MokoStandards-Template-Client` | Client Joomla sites with media sync | — |

## Standard Workflow Suite

### Joomla Repositories (10 workflows)

| Workflow | Trigger | Purpose |
|----------|---------|---------|
| `auto-release.yml` | PR merge to main (src/ changes) | Stable release: zip, Gitea release, version bump, updates.xml |
| `pre-release.yml` | Manual dispatch | Dev/alpha/beta/rc: patch bump, zip, pre-release |
| `ci-joomla.yml` | PRs to main | PHP lint, PHPStan, coding standards |
| `pr-check.yml` | PRs to main | Gate: manifest XML validation, build test |
| `deploy-manual.yml` | Manual dispatch | SFTP deploy to selected environment |
| `repo-health.yml` | Weekly schedule / manual | Structure compliance, required files |
| `update-server.yml` | Weekly schedule / manual | Validate updates.xml format + download URLs |
| `security-audit.yml` | Weekly + PR (lock file changes) | Dependency vulnerability scanning |
| `notify.yml` | Workflow completion | ntfy push on release success or failure |
| `cleanup.yml` | Weekly (Sunday 03:00 UTC) | Delete merged branches + old workflow runs |

### Dolibarr Repositories (11 workflows)

Same as Joomla except:
- `ci-dolibarr.yml` replaces `ci-joomla.yml` (Dolibarr-specific validation)
- `publish-to-mokodolimods.yml` added (copies src/ to mokodolimods on release)

### Generic Repositories (9 workflows)

Same as Joomla minus `ci-joomla.yml` (no platform-specific CI).

### Client Repositories (11 workflows)

Same as Joomla (clients are Joomla-based) plus:
- `sync-media.yml` — Bidirectional SFTP sync for `images/`, `files/`, `media/` between dev and production (every 6 hours + manual dispatch)

**Per-client repo variables required for sync:**
| Variable | Purpose |
|----------|---------|
| `DEV_SYNC_HOST` | Dev server hostname |
| `DEV_SYNC_PORT` | Dev SSH port (default 22) |
| `DEV_SYNC_USERNAME` | Dev server user |
| `DEV_SYNC_PATH` | Base path on dev |
| `PROD_SYNC_HOST` | Production server hostname |
| `PROD_SYNC_PORT` | Production SSH port (default 22) |
| `PROD_SYNC_USERNAME` | Production server user |
| `PROD_SYNC_PATH` | Base path on production |

**Per-client repo secrets:** `DEV_SYNC_KEY`, `PROD_SYNC_KEY`

## Release Model

```
Feature branch → PR → merge to main → auto-release.yml (STABLE)
                                     ↓
                         pre-release.yml (manual dispatch for dev/alpha/beta/rc)
```

- **Stable releases** trigger automatically on PR merge to main (with `src/` changes)
- **Pre-releases** (dev, alpha, beta, rc) are manual via workflow_dispatch
- Both bump the patch version automatically
- All releases overwrite the previous release for that channel (no history accumulation)

## Org-Level Configuration

These secrets and variables are set at the MokoConsulting org level and available to all repos:

### Secrets
| Name | Purpose |
|------|---------|
| `GA_TOKEN` | Gitea API token for releases, branch operations |
| `GH_TOKEN` | GitHub token for mirrors |
| `DEPLOY_SSH_KEY` | Universal SSH key for SFTP deploys |
| `DEV_SSH_KEY` | Dev server SSH key |
| `DEMO_FTP_KEY` | Demo server SFTP key |

### Variables
| Name | Value | Purpose |
|------|-------|---------|
| `NTFY_URL` | `https://ntfy.mokoconsulting.tech` | Notification server |
| `NTFY_TOPIC` | `gitea-releases` | Default notification topic |
| `DEV_SSH_HOST` | `dev.mokoconsulting.tech` | Dev server hostname |
| `DEV_SSH_PORT` | `22` | Dev server SSH port |
| `DEV_SSH_USERNAME` | `mokoconsulting_dev` | Dev server username |
| `DEMO_FTP_HOST` | `demo.mokoconsulting.tech` | Demo server hostname |
| `DEMO_FTP_PORT` | `22` | Demo server port |
| `DEMO_FTP_USERNAME` | `mokoconsulting_demo` | Demo server username |

## Syncing Workflows

To update workflows across all repos from the canonical template:

```bash
# Joomla repos — sync from unified template
for REPO in MokoOnyx MokoCassiopeia MokoJGDPC MokoJoomHero MokoJoomTOS MokoWaaS MokoWaaSAnnounce MokoDPCalendarAPI; do
  cd /a/$REPO
  rm -f .gitea/workflows/*.yml
  cp /a/MokoStandards-Template-Joomla/.gitea/workflows/*.yml .gitea/workflows/
  git add .gitea/workflows/ && git commit -m "chore: sync workflows" && git push
done

# Dolibarr repos — sync from Dolibarr template
for REPO in MokoCRM MokoDoliForm MokoDoliAuth MokoDolibarr ...; do
  cd /a/$REPO
  rm -f .gitea/workflows/*.yml
  cp /a/MokoStandards-Template-Dolibarr/.gitea/workflows/*.yml .gitea/workflows/
  git add .gitea/workflows/ && git commit -m "chore: sync workflows" && git push
done

# Client repos — sync from Client template
for REPO in client-clarksvillefurs client-kiddieland; do
  cd /a/$REPO
  rm -f .gitea/workflows/*.yml
  cp /a/MokoStandards-Template-Client/.gitea/workflows/*.yml .gitea/workflows/
  git add .gitea/workflows/ && git commit -m "chore: sync workflows" && git push
done
```

## Changelog

| Date | Change |
|------|--------|
| 2026-05-02 | Initial standardization: 10-workflow Joomla suite from MokoOnyx |
| 2026-05-02 | Added pre-release.yml for manual dev/alpha/beta/rc builds |
| 2026-05-02 | Removed auto-deploy (deploy is manual only) |
| 2026-05-02 | Modernized Dolibarr/Generic/Client templates to match |
| 2026-05-02 | Added workflows to all 22 Dolibarr production repos |
| 2026-05-02 | Moved canonical source from API repo to template repos |
| 2026-05-02 | Added sync-media.yml to Client template (bidirectional SFTP) |
| 2026-05-02 | Deployed workflows to client repos (clarksvillefurs, kiddieland) |
| 2026-05-02 | Consolidated 6 Joomla template repos → `MokoStandards-Template-Joomla` |
| 2026-05-02 | Deleted individual template repos (Plugin, Template, Module, Component, Package, Library) |