MokoCLI/docs/workflows/shared-workflows.md

<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>

This file is part of a Moko Consulting project.

SPDX-License-Identifier: GPL-3.0-or-later

# FILE INFORMATION
DEFGROUP: MokoStandards.Documentation
INGROUP: MokoStandards
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API
PATH: /docs/workflows/shared-workflows.md
VERSION: 04.06.00
BRIEF: Reference for shared workflow templates synced to all governed repos
-->

[![MokoStandards](https://img.shields.io/badge/MokoStandards-04.06.00-orange)](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 `<version>`)
4. Updates `[VERSION: XX.YY.ZZ]` badges in markdown files
5. Writes update files (Dolibarr `update.txt`, Joomla `updates.xml` with `<tag>stable</tag>`)
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 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](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` 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](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 (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.