This directory contains consolidated GitHub Actions workflow templates for use across MokoStandards-governed repositories. These templates provide standardized CI/CD configurations for different project types.

All workflow templates are documented in the unified repository schema at schemas/unified-repository-schema.json. The schema defines:

Platform compatibility (generic, joomla, dolibarr, shared)
Category (ci, build, test, release, deploy, quality, security, etc.)
Required secrets and variables
Permissions needed
Requirement level (required, recommended, optional)

Live Workflows vs Templates

Live Workflows (.github/workflows/) - Always active for MokoStandards repo:

standards-compliance.yml - Repository standards validation
confidentiality-scan.yml - Security and confidentiality checks
changelog_update.yml - CHANGELOG management
bulk-repo-sync.yml - Bulk repository synchronization
auto-create-org-projects.yml - Organization project automation

Templates (templates/workflows/) - For use in governed repositories:

All workflow templates organized by platform and purpose
43 workflow templates available

Structure

The workflows are organized by platform and purpose:

Platform-Specific Templates

generic/ - Universal workflows for all project types

ci.yml - Generic continuous integration
code-quality.yml - Code quality checks
codeql-analysis.yml - Security analysis
dependency-review.yml.template - Dependency review
repo-health.yml - Repository health checks
test.yml.template - Generic testing workflow

infrastructure/terraform/ - Terraform infrastructure-as-code workflows

ci.yml - Terraform validation, formatting, and planning
deploy.yml.template - Infrastructure deployment workflow
drift-detection.yml.template - Automated drift detection

joomla/ - Joomla extension workflows

ci-joomla.yml.template - Joomla-specific CI
test.yml.template - Joomla extension testing
release.yml.template - Joomla package creation
repo_health.yml.template - Joomla repo health
version_branch.yml.template - Version management

dolibarr/ - Dolibarr module workflows

ci-dolibarr.yml.template - Dolibarr CI
test.yml.template - Dolibarr module testing
release.yml.template - Dolibarr package creation
sync-changelogs.yml.template - Changelog synchronization

Release & Build Templates

release-cycle.yml.template - Full release cycle (main → dev → rc → version → main)
release-pipeline.yml.template - Automated release pipeline
build.yml.template - Universal build workflow
version_branch.yml - Version branch management
branch-cleanup.yml.template - Branch cleanup automation

Reusable Workflows

reusable-build.yml.template - Reusable build job
reusable-ci-validation.yml - Reusable CI validation
reusable-deploy.yml - Reusable deployment
reusable-joomla-testing.yml - Reusable Joomla tests
reusable-php-quality.yml - Reusable PHP quality checks
reusable-platform-testing.yml - Reusable platform testing
reusable-project-detector.yml - Project type detection
reusable-release.yml.template - Reusable release job
reusable-script-executor.yml - Reusable script execution

Shared Utilities

shared/ - Organization-wide utility workflows

enterprise-firewall-setup.yml.template - Firewall configuration
rebuild-docs-indexes.yml.template - Documentation indexing
setup-project-v2.yml.template - Project setup automation
sync-docs-to-project.yml.template - Documentation sync

Root Templates

ci-joomla.yml.template - Legacy Joomla CI template
repo_health.yml.template - Legacy repo health template
repo_health_xml.yml.template - XML-based repo health ├── dolibarr/ # Dolibarr-specific workflow templates │ ├── ci-dolibarr.yml.template # Continuous integration for Dolibarr modules │ ├── test.yml.template # Testing workflow for Dolibarr modules │ └── release.yml.template # Automated release and deployment └── generic/ # Generic/platform-agnostic workflow templates ├── ci.yml.template # Multi-language CI (Node.js, Python, PHP, Go, Ruby, Rust) ├── test.yml.template # Comprehensive testing (unit, integration, e2e) ├── deploy.yml.template # Deployment workflow for multiple environments ├── code-quality.yml.template # Code quality, linting, and static analysis ├── codeql-analysis.yml.template # CodeQL security analysis └── repo_health.yml.template # Repository health checks for generic projects


**Note**: All template workflow files use the `.yml.template` extension to clearly distinguish them from actual workflow files. When copying to your repository, rename them to `.yml` (e.g., `cp ci.yml.template .github/workflows/ci.yml`).

## Template Categories

### Joomla Templates (`joomla/`)

Workflow templates specifically designed for Joomla extensions (components, modules, plugins, libraries, packages, templates):

- **auto-release.yml.template** - Build & release pipeline for stable releases (triggers on merge to main). Runs on the dedicated `release` runner. Reads version from README.md, installs PHP+Composer if missing, builds ZIP+tar.gz packages, bundles payload (e.g. MokoOnyx template), creates/updates Gitea releases on the `stable` tag, cascading updates to all channels in updates.xml, syncs to main via PR, and mirrors to GitHub. All patches release (including patch 00).
- **update-server.yml.template** - Multi-channel Joomla update server (triggers on dev/alpha/beta/rc branch merges). Runs on the dedicated `release` runner. Builds packages, uploads to per-channel Gitea releases, cascading updates to lower stability channels in updates.xml. Supports SFTP deploy to dev server.
- **ci-joomla.yml.template** - Continuous integration workflow with PHP validation, XML checking, and manifest verification
- **deploy-manual.yml.template** - Manual deployment workflow for Joomla extensions with release triggering
- **repo_health.yml.template** - Repository health monitoring including documentation checks and standards validation

### Dolibarr Templates (`dolibarr/`)

Workflow templates specifically designed for Dolibarr ERP/CRM modules:

- **ci-dolibarr.yml.template** - Continuous integration for Dolibarr modules with structure validation, PHP syntax checking, and security checks
- **test.yml.template** - Automated testing workflow with PHPUnit tests and Dolibarr environment integration
- **release.yml.template** - Automated release workflow for Dolibarr module packaging and deployment

### Generic Templates (`generic/`)

Platform-agnostic workflow templates for multi-language software development:

- **ci.yml.template** - Multi-language continuous integration with automatic language detection (supports Node.js, Python, PHP, Go, Ruby, Rust)
- **test.yml.template** - Comprehensive testing workflow supporting unit tests, integration tests, and end-to-end tests
- **deploy.yml.template** - Deployment workflow for staging and production environments with rollback capabilities
- **code-quality.yml.template** - Code quality analysis with linting, formatting, static analysis, dependency checks, and security scanning
- **codeql-analysis.yml.template** - CodeQL security analysis for vulnerability detection
- **repo_health.yml.template** - Repository health monitoring for generic projects

## Available Templates

### ci-joomla.yml / joomla/ci.yml
Continuous Integration workflow for Joomla component repositories.

**Features:**
- Validates Joomla manifests
- Checks XML well-formedness
- Runs PHP syntax validation
- Validates CHANGELOG structure
- Checks license headers
- Validates version alignment
- Tab and path separator checks
- Secret scanning

**Usage:**
Copy to your repository as `.github/workflows/ci.yml` and customize as needed.

### repo_health.yml / generic/repo_health.yml / joomla/repo_health.yml
Repository health and governance validation workflow.

**Features:**
- Admin-only execution gate
- Scripts governance (directory structure validation)
- Repository artifact validation (required files and directories)
- Content heuristics (CHANGELOG, LICENSE, README validation)
- Extended checks:
  - CODEOWNERS presence
  - Workflow pinning advisory
  - Documentation link integrity
  - ShellCheck validation
  - SPDX header compliance
  - Git hygiene (stale branches)

**Profiles:**
- `all` - Run all checks
- `scripts` - Scripts governance only
- `repo` - Repository health only

**Usage:**
Copy to your repository as `.github/workflows/repo_health.yml`. Requires admin permissions to run.

### version_branch.yml / joomla/version_branch.yml
Automated version branching and version bumping workflow.

**Features:**
- Creates `dev/<version>` branches from base branch
- Updates version numbers across all governed files
- Updates manifest dates
- Updates CHANGELOG with version entry
- Enterprise policy gates:
  - Required governance artifacts check
  - Branch namespace collision defense
  - Control character guard
  - Update feed enforcement

**Inputs:**
- `new_version` (required) - Version in format NN.NN.NN (e.g., 03.01.00)
- `version_text` (optional) - Version label (e.g., LTS, RC1, hotfix)
- `report_only` (optional) - Dry run mode without branch creation
- `commit_changes` (optional) - Whether to commit and push changes

**Usage:**
Copy to your repository as `.github/workflows/version_branch.yml`. Run manually via workflow_dispatch.

### joomla/test.yml
Comprehensive testing workflow for Joomla extensions.

**Features:**
- PHPUnit tests across multiple PHP and Joomla versions
- Code quality checks (PHPCS, PHPStan, Psalm)
- Integration tests with MySQL database
- Code coverage reporting with Codecov integration

**Matrix Testing:**
- PHP versions: 7.4, 8.0, 8.1, 8.2
- Joomla versions: 4.4, 5.0

**Usage:**
Copy to your repository as `.github/workflows/test.yml`.

### joomla/release.yml
Automated release and package creation workflow for Joomla extensions.

**Features:**
- Builds release packages from tags or manual triggers
- Updates version numbers in manifest files
- Creates ZIP packages with proper structure
- Generates checksums (SHA256 and MD5)
- Creates GitHub releases with changelog extraction
- Uploads release artifacts

**Triggers:**
- Push to tags matching `v*.*.*`
- Manual workflow dispatch with version input

**Usage:**
Copy to your repository as `.github/workflows/release.yml`.

### dolibarr/ci.yml
Continuous integration workflow for Dolibarr modules.

**Features:**
- Module structure validation
- PHP syntax checking across PHP 7.4-8.2 and Dolibarr 16.0-18.0
- Dolibarr API usage validation
- Database schema validation
- License header compliance
- Code quality checks (PHPCS, PHPStan)
- Security scanning (hardcoded credentials, SQL injection, XSS)

**Usage:**
Copy to your repository as `.github/workflows/ci.yml`.

### dolibarr/test.yml
Testing workflow for Dolibarr modules with full environment setup.

**Features:**
- PHPUnit tests with Dolibarr environment
- Automatic Dolibarr installation and configuration
- MySQL database integration
- Module linking and installation
- Integration tests support
- Code coverage reporting

**Usage:**
Copy to your repository as `.github/workflows/test.yml`.

### generic/ci.yml
Multi-language continuous integration workflow with automatic language detection.

**Features:**
- Automatic project language detection (Node.js, Python, PHP, Go, Ruby, Rust)
- Parallel testing across language matrices
- Language-specific linting and code quality checks
- Security scanning with Trivy
- Comprehensive test execution

**Supported Languages:**
- Node.js (16.x, 18.x, 20.x)
- Python (3.8, 3.9, 3.10, 3.11)
- PHP (7.4, 8.0, 8.1, 8.2)
- Go (1.20, 1.21, 1.22)
- Ruby (2.7, 3.0, 3.1, 3.2)
- Rust (stable, beta)

**Usage:**
Copy to your repository as `.github/workflows/ci.yml`.

### generic/test.yml
Comprehensive testing workflow supporting unit, integration, and end-to-end tests.

**Features:**
- Automatic project type detection
- Unit tests with coverage reporting
- Integration tests with PostgreSQL and Redis
- End-to-end tests with Playwright
- Codecov integration
- Test result summaries

**Usage:**
Copy to your repository as `.github/workflows/test.yml`.

### generic/deploy.yml
Deployment workflow for multiple environments with rollback capabilities.

**Features:**
- Automatic environment detection (staging, production, development)
- Multi-language build support
- Separate staging and production deployment jobs
- Smoke tests after deployment
- Automatic rollback on failure
- Deployment notifications

**Triggers:**
- Push to main or staging branches
- Release publication
- Manual workflow dispatch

**Usage:**
Copy to your repository as `.github/workflows/deploy.yml`. Configure deployment commands for your infrastructure.

### generic/code-quality.yml
Comprehensive code quality analysis workflow.

**Features:**
- Multi-language linting and formatting
  - JavaScript/TypeScript: ESLint, Prettier
  - Python: Flake8, Black, isort, Pylint, Bandit
  - PHP: PHPCS, PHP-CS-Fixer, PHPStan, Psalm
  - Go: golangci-lint, go fmt
  - Rust: cargo fmt, cargo clippy
- Static analysis with CodeQL
- Dependency security checks (Snyk, npm audit, pip safety)
- Code complexity analysis with radon
- Code coverage analysis

**Usage:**
Copy to your repository as `.github/workflows/code-quality.yml`.

### Plugin Validation Workflows

Project-specific validation workflows using the MokoStandards plugin system. Each workflow validates projects using the appropriate plugin for automated quality assurance.

#### validate-joomla-project.yml
**Features:**
- Validates Joomla CMS projects and extensions
- Runs health checks specific to Joomla standards
- Collects Joomla-specific metrics
- Checks release readiness for Joomla extensions
- Comments validation results on pull requests

**Usage:** Copy to `.github/workflows/validate.yml` in Joomla projects.

#### validate-nodejs-project.yml
**Features:**
- Validates Node.js applications and packages
- Checks package.json structure and scripts
- Runs npm audit for security vulnerabilities
- Collects Node.js project metrics
- Creates validation summary in workflow run

**Usage:** Copy to `.github/workflows/validate.yml` in Node.js projects.

#### validate-python-project.yml
**Features:**
- Validates Python applications and packages
- Checks pyproject.toml, setup.py, requirements.txt
- Runs safety checks for Python dependencies
- Collects Python-specific metrics
- Validates project structure and best practices

**Usage:** Copy to `.github/workflows/validate.yml` in Python projects.

#### validate-terraform-project.yml
**Features:**
- Validates Terraform Infrastructure as Code projects
- Checks Terraform file formatting
- Runs terraform validate
- Validates module structure
- Collects infrastructure metrics

**Usage:** Copy to `.github/workflows/validate.yml` in Terraform projects.

#### validate-wordpress-project.yml
**Features:**
- Validates WordPress themes and plugins
- Checks WordPress coding standards
- Validates plugin/theme structure
- Collects WordPress-specific metrics
- Checks for common WordPress security issues

**Usage:** Copy to `.github/workflows/validate.yml` in WordPress projects.

#### validate-mobile-project.yml
**Features:**
- Validates mobile applications (iOS/Android)
- Checks mobile app structure
- Validates configuration files
- Collects mobile app metrics

**Usage:** Copy to `.github/workflows/validate.yml` in mobile projects.

#### validate-api-project.yml
**Features:**
- Validates REST API and GraphQL services
- Checks OpenAPI/Swagger specifications
- Validates API structure and documentation
- Collects API-specific metrics
- Checks API security best practices

**Usage:** Copy to `.github/workflows/validate.yml` in API projects.

#### validate-dolibarr-project.yml
**Features:**
- Validates Dolibarr ERP/CRM modules
- Checks Dolibarr module structure
- Validates module descriptors
- Collects Dolibarr-specific metrics

**Usage:** Copy to `.github/workflows/validate.yml` in Dolibarr projects.

#### validate-generic-project.yml
**Features:**
- Validates generic project types
- Checks common best practices
- Validates basic project structure
- Collects general metrics

**Usage:** Copy to `.github/workflows/validate.yml` in projects that don't fit other categories.

#### validate-documentation-project.yml
**Features:**
- Validates documentation projects
- Checks for broken links with markdown-link-check
- Lints Markdown files with markdownlint
- Validates documentation structure
- Collects documentation metrics

**Usage:** Copy to `.github/workflows/validate.yml` in documentation projects.

**All Plugin Validation Workflows Include:**
- Automated project type detection (or explicit type specification)
- Validation checks with JSON output
- Health checks with scoring
- Metrics collection
- Release readiness checks (on main branch)
- Artifact upload for validation results
- Proper exit codes (0=success, 1=failure, 2=error)

## Multi-Channel updates.xml Architecture (Joomla)

Joomla extensions use `updates.xml` as their update server manifest. MokoStandards implements a **multi-channel** architecture where each stability level has its own `<update>` block:

```xml
<updates>
  <!-- 1. DEVELOPMENT -->  <update>...<tag>development</tag>...</update>
  <!-- 2. ALPHA -->         <update>...<tag>alpha</tag>...</update>
  <!-- 3. BETA -->          <update>...<tag>beta</tag>...</update>
  <!-- 4. RC -->            <update>...<tag>rc</tag>...</update>
  <!-- 5. STABLE -->        <update>...<tag>stable</tag>...</update>
</updates>

Key Principles

Cascading channel updates — Each release updates its own channel and all lower stability channels. This ensures every site sees the update regardless of their minimum stability setting:
- stable → updates development, alpha, beta, rc, stable
- rc → updates development, alpha, beta, rc
- beta → updates development, alpha, beta
- alpha → updates development, alpha
- development → updates development only
Joomla filters by user setting — Site administrators choose "Minimum Stability" in Joomla's update settings; Joomla shows updates matching that level or higher
SHA-256 must be raw hex — No sha256: prefix. Joomla expects the raw hash value
Version format is zero-padded semver — XX.YY.ZZ (e.g., 01.00.00), not tag names like v01
All patches release — Including patch 00. Release workflows auto-bump the patch version before building (increments XX.YY.ZZ → XX.YY.(ZZ+1) in README.md, manifest, and the matching updates.xml channel)
Auto-bump on all branches — release.yml (manual dispatch) and update-server.yml (branch merges) both auto-bump patch before building. No manual version bump required

Channel-to-Workflow Mapping

Channel	Workflow	Trigger	Release Tag
`stable`	`auto-release.yml`	Merge PR to `main`	`stable`
`development`	`update-server.yml`	Merge PR to `dev/**`	`development`
`alpha`	`update-server.yml`	Merge PR to `alpha/**`	`alpha`
`beta`	`update-server.yml`	Merge PR to `beta/**`	`beta`
`rc`	`update-server.yml`	Merge PR to `rc/**`	`release-candidate`

Usage

For New Projects

Choose the appropriate template directory for your project type:
- Joomla extensions → joomla/
- Dolibarr modules → dolibarr/
- Other projects → generic/
Copy the relevant workflow files to your project's .github/workflows/ directory
Customize the workflow parameters as needed for your specific project:
- Update FILE INFORMATION headers with correct paths
- Adjust branch patterns to match your branching strategy
- Configure environment-specific settings (deployment URLs, secrets, etc.)
Commit and push to enable the workflows

For Existing Projects

Review your current workflows against the templates
Identify gaps or improvements from the standard templates
Update your workflows to align with current standards
Test changes on a feature branch before merging to main

Integration with MokoStandards

These workflows are designed to work with:

Script templates in templates/scripts/
Documentation standards in docs/policy/
Repository layout standards defined in README.md

Customization Guidelines

When adapting these templates:

Preserve core validation steps - Don't remove required compliance checks
Add project-specific steps - Extend templates with additional validation as needed
Maintain naming conventions - Keep workflow names consistent for cross-repo visibility
Document deviations - If you must deviate from templates, document why in the workflow file

When copying templates to your repository:

Update FILE INFORMATION headers with correct paths
Adjust branch patterns to match your branching strategy
Modify validation scripts based on available scripts in your repository
Customize required artifacts in repo_health.yml
Update allowed script directories to match your structure

Workflow Dependencies

Joomla Workflows

ci.yml requires:

scripts/validate/manifest.sh
scripts/validate/xml_wellformed.sh
Optional validation scripts in scripts/validate/

test.yml requires:

PHPUnit configuration (phpunit.xml or phpunit.xml.dist)
Composer for dependency management
Optional: PHPCS, PHPStan, Psalm configurations

release.yml requires:

Git tags following semver pattern (v*.*.*)
XML manifest files for version updates
Optional: CHANGELOG.md for release notes

Dolibarr Workflows

ci.yml requires:

Module descriptor in core/modules/modMyModule.class.php
Proper Dolibarr module directory structure
Optional: scripts/validate/ directory for custom validation

test.yml requires:

PHPUnit configuration
MySQL database (provided by GitHub Actions services)
Dolibarr installation (automated in workflow)

Generic Workflows

ci.yml requires:

Language-specific package managers (npm, pip, composer, go, bundler, cargo)
Test configurations for your language

test.yml requires:

Test framework configuration (Jest, pytest, PHPUnit, etc.)
Optional: PostgreSQL and Redis (provided by services)
Optional: Playwright for E2E tests

deploy.yml requires:

Environment secrets configured in GitHub repository settings
Deployment target configuration (servers, cloud platforms, etc.)

code-quality.yml requires:

Optional: Snyk token for security scanning
Language-specific linter configurations

repo_health.yml requires:

Python 3.x (for JSON processing)
ShellCheck (installed automatically if needed)

version_branch.yml requires:

Python 3.x (for version bumping logic)
Governance artifacts: LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, etc.

Required Workflows

All MokoStandards-governed repositories MUST implement:

CI workflow - For build validation and testing
- Use joomla/ci.yml for Joomla extensions
- Use dolibarr/ci.yml for Dolibarr modules
- Use generic/ci.yml for other projects
Repository health workflow - For ongoing compliance monitoring

Optional but recommended:

Test workflow - For comprehensive automated testing
Release workflow - For automated release management (Joomla projects)
Deploy workflow - For automated deployments (web applications)
Code quality workflow - For advanced code analysis
Version branch workflow - For repositories using version-based branching
Security scanning - CodeQL or equivalent (now in main .github/workflows/)
Dependency updates - Dependabot (configured in .github/dependabot.yml)

Standards Compliance

All workflows follow MokoStandards requirements:

SPDX license headers
GPL-3.0-or-later license
Proper error handling and reporting
Step summaries for GitHub Actions UI
Audit trail generation

Trigger Patterns

CI Workflows

Push to main, dev/, rc/, version/** branches
Pull requests to same branches

Repo Health

Manual workflow_dispatch with profile selection
Push to main (workflows, scripts, docs paths)
Pull requests (workflows, scripts, docs paths)

Version Branch

Manual workflow_dispatch only (admin-level operation)

Template Maintenance

These templates are maintained as part of MokoStandards and updated periodically:

Breaking changes - Will be announced via changelog and require downstream updates
Non-breaking improvements - Can be adopted at downstream projects' convenience
Security updates - Must be adopted immediately per security policy

Integration with Repository Scaffolds

These workflow templates are designed to work with project-specific repository scaffolds maintained in individual repositories. The separation allows:

Workflow templates to be version-controlled and updated independently
Easy discovery and comparison of workflow configurations
Central management of CI/CD patterns across the organization

Consult the organization's scaffold repositories for complete repository layouts that integrate these workflows.

Best Practices

Pin action versions - Use specific versions (@v4) not @main/@master
Test workflows in development branches before merging to main
Review step summaries in GitHub Actions UI after runs
Use workflow concurrency to prevent simultaneous runs
Set appropriate timeouts for long-running operations
Configure secrets properly - Use GitHub repository secrets for sensitive data
Start with basic workflows - Begin with CI and testing, then add advanced workflows
Monitor workflow costs - Be aware of GitHub Actions minutes usage
Use matrix strategies - Test across multiple versions when appropriate
Document customizations - Add comments explaining any deviations from templates

Support and Feedback

For issues or questions about these workflows:

Review the workflow logs in GitHub Actions UI
Check the step summaries for detailed error reports
Validate your scripts locally before CI runs
Refer to MokoStandards documentation in docs/

For questions, issues, or suggestions regarding these workflow templates:

Open an issue in the MokoStandards repository
Reference specific template files in your report
Tag with workflow-template label

Compliance

Use of these templates helps ensure:

Consistent CI/CD patterns across projects
Automated enforcement of coding standards
Security scanning and vulnerability detection
Documentation and governance compliance

Metadata

Field	Value
Document	GitHub Workflow Templates README
Path	/templates/workflows/README.md
Repository	https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
Owner	Moko Consulting
Scope	Workflow template documentation
Status	Active
Effective	2026-01-04

Version History

Version	Date	Changes
01.01.00	2026-01-04	Added comprehensive development workflow templates
01.00.01	2026-01-04	Consolidated templates to /templates/workflows/
01.00.00	2026-01-04	Initial workflow templates for MokoStandards

Revision History

Date	Change Description	Author
2026-01-04	Added Joomla test.yml, release.yml; Dolibarr ci.yml, test.yml; Generic ci.yml, test.yml, deploy.yml, code-quality.yml	Moko Consulting
2026-01-04	Moved to /templates/workflows/ directory	Moko Consulting
2026-01-04	Initial creation with consolidated workflow templates	Moko Consulting