MokoConsulting/moko-platform

Fork 0

Table of Contents

Shared Workflow Templates

Workflow Summary

moko-platform-only workflows (not synced)

sync-version-on-merge.yml
auto-release.yml
enterprise-firewall-setup.yml
Deploy Workflows

Common Features (both deploy workflows)
Version Handling by Environment
Update Server Files by Environment

auto-dev-issue.yml
repository-cleanup.yml
Custom Workflows
repo_health.yml (platform-specific)

Dolibarr (crm-module) checks
Joomla (waas-component) checks

composer-validate.yml (moko-platform only)
Composer Enterprise Dependency
Governed repos can manually override to dev-main for bleeding-edge testing, but this will be corrected on the next sync.

← Home

Shared Workflow Templates

These workflows are synced to every governed repository via bulk_sync.php. They live in templates/workflows/shared/ and are registered in all platform definitions.

Workflow Summary

Workflow	Triggers	Purpose
`deploy-dev.yml`	`dev/`, `alpha/`, `beta/`, `rc/`, `develop` (src/** only)	SFTP deploy to dev server (dev=development, alpha/beta auto-bump patch, rc=rc tag)
`deploy-demo.yml`	`main`, `master` (src/** only)	SFTP deploy to demo server (stable tag) + update files
`sync-version-on-merge.yml`	push to `main`	Auto-bump patch version, propagate to all headers
`auto-release.yml`	push to `main`	Build & Release: every push tags + updates platform version/badges; minor (XX.YY.00) creates version branch + new Release; patch updates existing Release
`auto-dev-issue.yml`	branch creation (`dev/`, `rc/`)	Auto-create tracking issue (dev=feature, rc=release)
`repository-cleanup.yml`	schedule (1st + 15th) + dispatch	Recurring maintenance: labels, branches, logs, workflows, doc indexes
`enterprise-firewall-setup.yml`	push to `main`	Configure trusted domain access for enterprise environments
`repo_health.yml`	every push + PR	Platform-specific health checks (Dolibarr: module descriptor; Joomla: XML manifest)

moko-platform-only workflows (not synced)

Workflow	Triggers	Purpose
`composer-validate.yml`	every push + PR	Validate composer.json schema, version consistency, autoload paths, bin scripts, enterprise dep pattern
`standards-compliance.yml`	push + PR	28-job, 4-tier compliance check
`bulk-repo-sync.yml`	dispatch	Sync standards to all governed repos

sync-version-on-merge.yml

Trigger: Every push to main/master

What it does:

If README.md was NOT part of the push, auto-increments the patch version (e.g., 04.00.72 → 04.00.73)
Reads the VERSION from README.md FILE INFORMATION block
Runs update_version_from_readme.php to propagate to all file headers and badges
Commits updated files with [skip ci]

Requirements: secrets.GH_TOKEN with write access

Skips: Commits by gitea-actions[bot], commits with [skip ci]

auto-release.yml

Trigger: Every push to main/master (skips bot commits and [skip ci])

What it does on every push:

Reads version from README.md
Creates or updates version/XX branch (patches force-update existing branch)
Sets platform version (Dolibarr $this->version, Joomla <version>)
Updates [VERSION: XX.YY.ZZ] badges in markdown files
Writes update files (Dolibarr update.txt, Joomla updates.xml with <tag>stable</tag>)
Creates git tag vXX.YY.ZZ

Additional steps on minor releases (patch == 00): 7. Creates new GitHub Release with changelog notes

On patch releases (patch != 00): 7. Updates the existing minor release (appends patch notes, updates title)

Protection: Workflow files are protected by CODEOWNERS (requires @jmiller review) and a file path restriction ruleset. Only bypass actors can modify .gitea/workflows/.

Version	What happens
`01.02.00`	Full release: version branch + tag + new GitHub Release
`01.02.01`	Patch: tag + update existing `v01.02.00` Release with patch notes
`01.02.02`	Patch: tag + update existing Release again
`01.03.00`	Full release: new version branch + tag + new GitHub Release

Requirements: secrets.GH_TOKEN with write access

enterprise-firewall-setup.yml

Trigger: Push to main

What it does: Configures trusted domain access rules for enterprise network environments. Ensures governed repositories can access required external services through corporate firewalls.

Deploy Workflows

See dedicated docs:

Dev Deployment — development server
Demo Deployment — demo server

Note: deploy-rs.yml has been retired (v04.06.00). RS deployment is now via the release pipeline only. See RS Deployment (deprecated).

Common Features (both deploy workflows)

Permission check: jmiller and gitea-actions[bot] hardcoded as authorized; others need admin/maintain role
Chore skip: PRs from chore/ branches do not deploy
Suffix required: {ENV}_FTP_SUFFIX must be set or deployment is skipped
Clear before upload: Remote folder is always cleared before uploading
.ftpignore support: Gitignore-style file exclusion
Failure tracking: Creates/updates a deploy-failure issue on error

Version Handling by Environment

Environment	Module Version
Dev (`dev/**`)	`"development"` — Dolibarr `$this->version` and Joomla `<version>` set to literal "development"
Alpha (`alpha/**`)	`XX.YY.ZZ-alpha` — version with `-alpha` suffix (auto-bumps patch)
Beta (`beta/**`)	`XX.YY.ZZ-beta` — version with `-beta` suffix (auto-bumps patch)
RC (`rc/**`)	`XX.YY.ZZ-rc` — version with `-rc` suffix
Demo (`main`)	Real version from README.md

Update Server Files by Environment

Environment	Dolibarr `update.txt`	Joomla `updates.xml <tag>`
Dev (`dev/**`)	`development`	`development`
Alpha (`alpha/**`)	`XX.YY.ZZ-alpha`	`alpha`
Beta (`beta/**`)	`XX.YY.ZZ-beta`	`beta`
RC (`rc/**`)	`XX.YY.ZZ-rc`	`release-candidate`
Release (`main` via auto-release)	`XX.YY.ZZ`	`vXX`

See update-server.md for the full update server specification.

auto-dev-issue.yml

Trigger: Branch creation matching dev/** or rc/**

What it does: Auto-creates a tracking issue when a new dev/** or rc/** branch is pushed. Assigns jmiller.

Branch type	Title prefix	Label
`dev/**`	`feat(XX.YY.ZZ)`	`type: feature`
`rc/**`	`rc(XX.YY.ZZ)`	`type: release`

Skips if an issue for that version already exists.

repository-cleanup.yml

Trigger: Schedule (1st + 15th of each month at 6:00 AM UTC) + manual dispatch

What it does (always):

Deletes 25 retired workflow files
Checks for version drift across all files
Creates .gitea/workflows/custom/ directory if missing

What it does (toggleable):

Reset labels to 58-label standard set (manual only, off by default)
Delete old sync branches
Clean cancelled/stale workflow runs
Delete workflow logs older than 30 days
Strip copyright blocks from issue templates
Rebuild docs/ index files

Custom Workflows

Every governed repo has a .gitea/workflows/custom/ directory that is never touched by sync or cleanup. Place repo-specific workflows here:

.gitea/workflows/
├── deploy-dev.yml              ← Synced (overwritten on sync)
├── auto-release.yml            ← Synced (overwritten on sync)
├── repository-cleanup.yml      ← Synced (overwritten on sync)
└── custom/                     ← SAFE — never touched
    ├── README.md
    └── my-custom-workflow.yml

repo_health.yml (platform-specific)

Trigger: Every push and PR (no path filter)

What it does: Platform-specific health checks in addition to shared guardrails (release vars, scripts governance, repo artifacts, extended checks).

Dolibarr (`crm-module`) checks

Module descriptor (src/core/modules/mod*.class.php) exists
$this->numero is set and non-zero
$this->version is not hardcoded
url_last_version points to update.txt (not update.json)
url_last_version references /main/ on main branch
src/README.md exists (module store requirement)
update.txt exists in root

Joomla (`waas-component`) checks

XML manifest with <extension> tag exists
<version>, <name>, <author>, <namespace> tags present
Extension type attribute is valid
Language .ini files exist
updates.xml exists in root
index.html directory listing protection in src/, src/admin/, src/site/

composer-validate.yml (moko-platform only)

Trigger: Every push and PR

What it does: Validates the composer.json integrity for the moko-platform enterprise library:

Schema validation (composer validate --strict)
Lock file freshness
Dependency resolution (dry run)
Security advisories (composer audit)
Version consistency: composer.json version = README.md VERSION = STANDARDS_VERSION in RepositorySynchronizer.php
All autoload paths (PSR-4, classmap, files) exist on disk
All bin scripts exist
Enterprise dep constraint uses dev-version/XX pattern (not dev-main)

Note: Governed repos can manually set dev-main for bleeding-edge installs, but the sync system always corrects this to dev-version/XX on the next sync run.

Composer Enterprise Dependency

On every sync, the RepositorySynchronizer checks if the remote composer.json requires mokoconsulting-tech/enterprise. If missing or stale (dev-main), it adds/updates it to "dev-version/XX" — always pinned to the current version branch, never bleeding-edge main.

Governed repos can manually override to `dev-main` for bleeding-edge testing, but this will be corrected on the next sync.

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	All repositories

Revision	Date	Author	Description
1.0	2026-05-08	Moko Consulting	Initial version