[](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards) # 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) | ### MokoStandards-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:** 1. If README.md was NOT part of the push, auto-increments the patch version (e.g., `04.00.72` → `04.00.73`) 2. Reads the VERSION from README.md FILE INFORMATION block 3. Runs `update_version_from_readme.php` to propagate to all file headers and badges 4. 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:** 1. Reads version from README.md 2. Creates or updates `version/XX` branch (patches force-update existing branch) 3. Sets platform version (Dolibarr `$this->version`, Joomla ``) 4. Updates `[VERSION: XX.YY.ZZ]` badges in markdown files 5. Writes update files (Dolibarr `update.txt`, Joomla `updates.xml` with `stable`) 6. 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-moko review) and a file path restriction ruleset. Only bypass actors can modify `.github/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](dev-deployment.md) — development server - [Demo Deployment](demo-deployment.md) — 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)](rs-deployment.md). ### Common Features (both deploy workflows) - **Permission check:** `jmiller-moko` 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 `` 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 ` | |-------------|----------------------|--------------------------| | 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](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-moko`. | 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 `.github/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 `.github/workflows/custom/` directory that is **never touched by sync or cleanup**. Place repo-specific workflows here: ``` .github/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 `` tag exists - ``, ``, ``, `` 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 (MokoStandards only) **Trigger:** Every push and PR **What it does:** Validates the `composer.json` integrity for the MokoStandards 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.