moko-platform/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:

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