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-*, etc.

MokoOnyx is the living reference implementation for Joomla workflows. Template repos are the canonical source for distribution. The MokoStandards-API repo does NOT store workflow templates — it only has bulk-repo-sync.yml for its own CI.

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 (10 workflows)

Same as Joomla (clients are Joomla-based).

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 MokoOnyx
for REPO in MokoOnyx MokoCassiopeia MokoJGDPC MokoJoomHero ...; do
  cd /a/$REPO
  rm -f .gitea/workflows/*.yml
  cp /a/MokoStandards-Template-Joomla-Plugin/.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 ...; 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

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