From 89eec33c7bcc6905933e40b9669cb8659a778ef8 Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Tue, 5 May 2026 15:02:27 -0500 Subject: [PATCH] docs: fix stale workflow and client repo references Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/client-repos.md | 52 +--- docs/workflows/README.md | 604 +++------------------------------------ 2 files changed, 48 insertions(+), 608 deletions(-) diff --git a/docs/client-repos.md b/docs/client-repos.md index 9e5b415..ec75406 100644 --- a/docs/client-repos.md +++ b/docs/client-repos.md @@ -19,6 +19,8 @@ BRIEF: Standards and conventions for client-facing Joomla site repositories Client repos (`client-*`) contain Joomla site customizations for individual clients — templates, overrides, custom CSS, module configurations, and deployment scripts. They follow the **Joomla** workflow profile but have additional rules around privacy, branding, and deployment. +> **Note**: Client repos are **sites**, not distributable Joomla extensions. They do not have `updates.xml` or an update-server workflow. + ## Naming Convention ``` @@ -43,10 +45,8 @@ client-{name}/ │ ├── plugins/ # Custom plugins │ └── media/ # CSS, JS, images ├── docs/ # Client-specific documentation -│ ├── INSTALLATION.md # Deployment instructions -│ └── update-server.md # Update server configuration +│ └── INSTALLATION.md # Deployment instructions ├── scripts/ # Build and deployment scripts -├── updates.xml # Joomla update server manifest ├── composer.json # Dependencies ├── CHANGELOG.md # Version history ├── README.md # Client overview (no sensitive details) @@ -66,24 +66,18 @@ Client repos are **private** by default. These rules are non-negotiable: ## Workflows -Client repos use the **Joomla workflow profile** from `MokoStandards-Template-Client`: +Client repos use the **Joomla workflow profile** from `MokoStandards-Template-Client` (10 workflows): -- `auto-assign.yml` — Auto-assign issues/PRs to jmiller -- `auto-dev-issue.yml` — Create tracking issue on dev branch push - `auto-release.yml` — Create GitHub Release on main merge -- `changelog-validation.yml` — Validate CHANGELOG.md format +- `pre-release.yml` — Pre-release builds for dev/rc branches - `ci-joomla.yml` — Joomla manifest validation, XML lint -- `codeql-analysis.yml` — Security scanning -- `copilot-agent.yml` — Copilot agent configuration +- `pr-check.yml` — Pull request validation - `deploy-manual.yml` — Manual FTP deploy for testing -- `enterprise-firewall-setup.yml` — Copilot firewall rules -- `project-setup.yml` — Initialize project structure -- `repo_health.yml` — Repository health checks -- `repository-cleanup.yml` — Clean up stale branches/artifacts -- `standards-compliance.yml` — MokoStandards validation -- `sync-version-on-merge.yml` — Version tracking -- `update-docs.yml` — Auto-update documentation indexes -- `update-server.yml` — Update `updates.xml` on release +- `repo-health.yml` — Repository health checks +- `security-audit.yml` — Security scanning +- `notify.yml` — Notifications for workflow events +- `cleanup.yml` — Clean up stale branches/artifacts +- `sync-media.yml` — Synchronize media assets ## Release Tags @@ -95,28 +89,12 @@ Standard 5-tag system applies: - `release-candidate` — Final QA before production - `stable` — Production release -## Update Server - -Client repos use the standard dual update server with **Gitea as priority 1**: - -```xml - - - https://git.mokoconsulting.tech/MokoConsulting/client-{name}/raw/branch/main/updates.xml - - - https://raw.githubusercontent.com/mokoconsulting-tech/client-{name}/main/updates.xml - - -``` - ## Deployment Client sites are deployed via: -1. **Joomla updater** — site pulls from `updates.xml` (preferred for production) -2. **Manual FTP** — via `deploy-manual.yml` workflow dispatch (for dev/staging) -3. **Direct install** — download ZIP from GitHub Release and install via Joomla admin +1. **Manual FTP** — via `deploy-manual.yml` workflow dispatch (for dev/staging) +2. **Direct install** — download ZIP from GitHub Release and install via Joomla admin ## Creating a New Client Repo @@ -133,7 +111,7 @@ Client sites are deployed via: - **Visibility**: Always private (standard Joomla repos can be public) - **Template**: `MokoStandards-Template-Client` (not `Template-Joomla-*`) -- **Extra workflows**: `project-setup.yml`, `update-docs.yml`, `copilot-agent.yml` +- **No updates.xml**: Client repos are sites, not distributable extensions - **SFTP config**: `sftp-config.json.template` with credential placeholders - **Branding**: Client-specific (not Moko Consulting) -- **Deployment**: Joomla updater + manual FTP (standard repos use updater only) +- **Deployment**: Manual FTP + direct install (standard repos use Joomla updater) diff --git a/docs/workflows/README.md b/docs/workflows/README.md index 0c8e86a..acdf125 100644 --- a/docs/workflows/README.md +++ b/docs/workflows/README.md @@ -1,599 +1,61 @@ [![MokoStandards](https://img.shields.io/badge/MokoStandards-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards) -# GitHub Workflow Templates Documentation +# Workflow Templates — Secondary Reference -**Status**: Active | **Version**: 04.00.04 | **Effective**: 2026-01-07 +**Status**: Active | **Version**: 04.06.00 | **Effective**: 2026-05-05 -## Overview -> **Important (v2):** All workflows MUST be in `.gitea/workflows/` only. Gitea Actions does not run workflows from `.github/workflows/`. Having files in `.github/workflows/` creates ghost queued runs that block the runner. Releases use stream-based git tags (`stable`, `release-candidate`, `beta`, `alpha`, `development`). See [Release System](./release-system.md) for cascade logic, SHA-256 rules, and auto-detection. +> **Canonical documentation**: [WORKFLOW_STANDARDS.md](../WORKFLOW_STANDARDS.md) is the primary reference for workflow standards, inventory, and architecture. This file provides supplementary context only. -This document provides comprehensive documentation for MokoStandards workflow templates. These templates provide standardized CI/CD configurations that ensure consistency, security, and compliance across all Moko Consulting repositories. +## Architecture -### Workflow Documentation +Workflow templates live in their respective **template repositories**, not in MokoStandards-API: -- [Workflow Architecture](./workflow-architecture.md) - Workflow hierarchy and design patterns -- [Workflow Inventory](./workflow-inventory.md) - Complete inventory of workflows -- [Reusable Workflows](./reusable-workflows.md) - Documentation for reusable GitHub Actions workflows -- [Standards Compliance](./standards-compliance.md) - **NEW**: Comprehensive standards validation workflow -- [Bulk Repository Sync](./bulk-repo-sync.md) - Automated standards deployment across organization repositories -- [Release System](./release-system.md) - Unified release system documentation -- [Changelog Management](./changelog-management.md) - Changelog management workflows and scripts -- [Dev Branch Tracking and Issue Coordination](./dev-branch-tracking.md) - Automated dev branch and PR tracking system -- [Dev Deployment](./dev-deployment.md) - Development deployment workflows -- [Reserve Dolibarr Module ID](./reserve-dolibarr-module-id.md) - Automated Dolibarr module ID reservation workflow +- **MokoStandards-Template-Joomla** — Joomla extension workflows +- **MokoStandards-Template-Dolibarr** — Dolibarr module workflows +- **MokoStandards-Template-Generic** — Generic project workflows +- **MokoStandards-Template-Client** — Client site workflows -### Workflow Template Locations +The **sync engine** clones the appropriate template repo at runtime and applies workflows to target repositories. There is no local `templates/workflows/` directory to copy from. -MokoStandards provides workflow templates in two locations: +## How Workflows Reach Repos -1. **`templates/workflows/`** - **Public workflow templates** for community adoption - - `build.yml.template` - Universal build workflow with automatic project detection - - `release-cycle.yml.template` - Automated release management workflow (v2.0 with auto-detect & manual modes) - - `generic/codeql-analysis.yml` - Security scanning with CodeQL - - `generic/dependency-review.yml.template` - Dependency vulnerability scanning - - `standards-compliance.yml.template` - MokoStandards compliance validation - - `flush-actions-cache.yml.template` - GitHub Actions cache management workflow +1. New repos are created from a template repo (e.g., `MokoStandards-Template-Joomla`), which includes `.gitea/workflows/` pre-populated. +2. Existing repos receive workflow updates via the bulk-sync engine, which clones the template repo, compares, and pushes changes. +3. All workflows run from `.gitea/workflows/` only — Gitea Actions does not execute workflows from `.github/workflows/`. -2. **`templates/workflows/`** - Platform-specific workflow examples - - `joomla/` - Joomla extension workflows - - `dolibarr/` - Dolibarr module workflows - - `generic/` - Generic project workflows +## Important Notes -### Quick Start +- Releases use the 5-stream tag system (`stable`, `release-candidate`, `beta`, `alpha`, `development`). See [Release System](./release-system.md). +- All workflows require SPDX license headers (GPL-3.0-or-later). +- Pin action versions (use `@v4`, not `@main`). -To adopt MokoStandards workflows in your repository: +## Related Documentation -```bash -# Copy universal build workflow -cp templates/workflows/build.yml.template .gitea/workflows/build.yml - -# Copy release management workflow -cp templates/workflows/release-cycle.yml.template .gitea/workflows/release.yml - -# Copy security scanning workflows -cp templates/workflows/generic/codeql-analysis.yml .gitea/workflows/ -cp templates/workflows/generic/dependency-review.yml.template .gitea/workflows/dependency-review.yml - -# Copy standards compliance workflow -cp templates/workflows/standards-compliance.yml.template .gitea/workflows/standards-compliance.yml - -# Optional: Copy cache management workflow -cp templates/workflows/flush-actions-cache.yml.template .gitea/workflows/flush-actions-cache.yml -``` - -Then customize the workflows for your project as needed. - -## Public Workflow Templates (`templates/workflows/`) - -### 1. Build Universal (`build.yml.template`) - -**Location**: `templates/workflows/build.yml.template` - -Universal build workflow with automatic project type detection and Makefile precedence system. - -**Features**: -- **Automatic project detection** - Detects Joomla, Dolibarr, or Generic projects -- **Makefile precedence system** - Repository Makefile → MokoStandards Makefile → Default builds -- **Multi-language support** - PHP, Node.js, and mixed projects -- **Build artifacts** - Automatic artifact upload -- **Customizable** - Extensive inline documentation for customization - -**Trigger Patterns**: -```yaml -on: - push: - branches: [main, dev/**, rc/**, version/**] - pull_request: - branches: [main, dev/**, rc/**] - workflow_dispatch: -``` - -**Usage**: Copy to `.gitea/workflows/build.yml` and customize as needed. - -See [Build System Documentation](../build-system/README.md) for details on the Makefile precedence system. - -### 2. Release Cycle (`release-cycle.yml.template`) - -**Location**: `templates/workflows/release-cycle.yml.template` - -**Version 02.00.00** - Merged unified-release and release-cycle workflows with auto-detection and manual dispatch modes - -Automated release management workflow implementing the MokoStandards release cycle: main → dev → rc → version → main. - -**Features**: -- **Auto-detection** - Detects version changes from CITATION.cff, pyproject.toml, package.json, CHANGELOG.md -- **Manual dispatch** - Full control over release actions -- **Semantic versioning** - Automatic validation of version format -- **Branch management** - Automated branch creation and merging -- **Release actions** - start-release, create-rc, finalize-release, hotfix, simple-release -- **Release notes** - Automated generation from commits -- **GitHub releases** - Automatic creation with artifacts - -**Actions**: -- `start-release` - Create development branch and update version -- `create-rc` - Create release candidate from dev branch -- `finalize-release` - Create version branch, merge to main, create release -- `hotfix` - Create hotfix branch for emergency fixes - -**Trigger Pattern**: -```yaml -on: - workflow_dispatch: - inputs: - action: - type: choice - options: [start-release, create-rc, finalize-release, hotfix] - version: - type: string - required: true -``` - -**Usage**: Copy to `.gitea/workflows/release.yml` for automated release management. - -See [Release Management Documentation](../release-management/README.md) for complete release procedures. - -### 3. Dependency Review (`dependency-review.yml.template`) - -**Location**: `templates/workflows/generic/dependency-review.yml.template` - -Comprehensive dependency vulnerability scanning for pull requests. - -**Features**: -- **GitHub Dependency Review** - Scans dependencies in PRs -- **npm audit** - Node.js dependency security checks -- **Composer audit** - PHP dependency security checks -- **Python Safety** - Python dependency vulnerability scanning -- **License compliance** - Validates dependency licenses - -**Trigger Pattern**: -```yaml -on: - pull_request: - branches: [main, dev/**, rc/**] -``` - -**Usage**: Copy to `.gitea/workflows/dependency-review.yml` to enable dependency scanning on PRs. - -### 4. Standards Compliance (`standards-compliance.yml.template`) - -**Location**: `templates/workflows/standards-compliance.yml.template` - -MokoStandards compliance validation workflow. - -**Features**: -- **Repository structure** - Validates required directories and files -- **Documentation quality** - Checks README, CHANGELOG, and other docs -- **Coding standards** - Tab detection, encoding, line endings -- **License compliance** - SPDX header validation -- **Git hygiene** - .gitignore, large files, etc. -- **Workflow validation** - YAML syntax and required workflows - -**Trigger Pattern**: -```yaml -on: - push: - branches: [main, dev/**, rc/**] - pull_request: - branches: [main, dev/**, rc/**] - workflow_dispatch: -``` - -**Usage**: Copy to `.gitea/workflows/standards-compliance.yml` to enable compliance checks. - -### 5. Flush Actions Cache (`flush-actions-cache.yml.template`) - -**Location**: `templates/workflows/flush-actions-cache.yml.template` - -Cache management workflow for flushing GitHub Actions caches on demand. - -**Features**: -- **Manual trigger** - Run from Actions tab when needed -- **Filter by branch** - Target specific branch caches -- **Filter by key pattern** - Target specific dependency caches (composer, node) -- **Dry-run mode** - Preview deletions before executing -- **Comprehensive reporting** - Shows cache details before deletion -- **Automatic script download** - Downloads latest flush script from MokoStandards - -**Trigger Pattern**: -```yaml -on: - workflow_dispatch: - inputs: - branch: - description: 'Branch to filter caches (leave empty for all branches)' - key-pattern: - description: 'Key pattern to filter caches (e.g., composer, node)' - dry-run: - description: 'Dry run mode (show what would be deleted without deleting)' - type: boolean -``` - -**Common Use Cases**: -- Clear all caches when corrupted -- Clear branch-specific caches after branch deletion -- Clear dependency caches after major updates (Composer, npm) -- Preview cache usage with dry-run mode - -**Usage**: Copy to `.gitea/workflows/flush-actions-cache.yml` to enable cache management. - -See [flush_actions_cache.py documentation](/docs/api/maintenance/flush-actions-cache-py.md) for detailed script usage. - -### 6. CodeQL Analysis (`codeql-analysis.yml`) - -**Location**: `templates/workflows/generic/codeql-analysis.yml` - -Security scanning with GitHub's CodeQL engine (also available in `.gitea/workflows/`). - -See section below for complete details. - -## Platform-Specific Workflow Templates (`templates/workflows/`) - -The following templates are organized by platform in `templates/workflows/`. - -### 1. CI Template (`ci.yml`) - -**Location**: `.gitea/workflows/ci.yml` (MokoStandards root) - -Continuous Integration workflow that enforces repository standards through automated validation. - -**Features**: -- **Manifest validation** - Validates project manifests (Joomla XML, Dolibarr descriptors) -- **XML well-formedness** - Ensures all XML files are properly formatted -- **PHP syntax validation** - Checks PHP code across multiple versions -- **CHANGELOG structure** - Validates changelog formatting and completeness -- **License headers** - Verifies SPDX headers in all source files -- **Version alignment** - Ensures version numbers are consistent across files -- **Path separator checks** - Validates file paths -- **Tab detection** - Enforces space-over-tabs policy -- **Secret scanning** - Prevents accidental secret commits - -**Trigger Patterns**: -```yaml -on: - push: - branches: [main, dev/**, rc/**, version/**] - pull_request: - branches: [main, dev/**, rc/**, version/**] -``` - -**Usage**: Copy from MokoStandards `.gitea/workflows/ci.yml` to your repository. - -### 2. CodeQL Analysis Template (`codeql-analysis.yml`) - -**Location**: `.gitea/workflows/codeql-analysis.yml` (MokoStandards root) - -Security scanning workflow using GitHub's CodeQL engine for vulnerability detection. - -**Features**: -- **Multi-language support** - Analyzes Python, JavaScript, PHP, Go, etc. -- **Security-extended queries** - Uses comprehensive security query packs -- **Quality analysis** - Includes code quality checks -- **Scheduled scans** - Weekly automated security scans (Monday 6:00 AM UTC) -- **PR integration** - Scans all pull requests automatically - -**Trigger Patterns**: -```yaml -on: - push: - branches: [main, dev/**, rc/**] - pull_request: - branches: [main, dev/**, rc/**] - schedule: - - cron: '0 6 * * 1' # Weekly Monday 6:00 AM UTC - workflow_dispatch: -``` - -**Usage**: Copy from MokoStandards `.gitea/workflows/codeql-analysis.yml` to your repository. - -### 3. Dependency Review - -**Purpose**: Automated dependency vulnerability scanning - -Dependency scanning in MokoStandards repositories is handled through: -- **Dependabot configuration** - `.github/dependabot.yml` (configure for your project) -- **CodeQL analysis** - Includes dependency checks -- **Generic code quality workflow** - `templates/workflows/generic/code-quality.yml` - -**Recommended Approach**: -1. Enable Dependabot in repository settings -2. Create `.github/dependabot.yml` configuration -3. Use CodeQL for comprehensive security analysis - -### 4. Standards Compliance Template (`repo_health.yml`) - -**Location**: `templates/workflows/generic/repo_health.yml` - -Repository health and governance validation workflow that enforces MokoStandards compliance. - -**Features**: -- **Admin-only execution** - Requires admin permissions -- **Release configuration checks** - Validates SFTP deployment variables -- **SFTP connectivity testing** - Tests remote server access -- **Scripts governance** - Validates script directory structure -- **Repository artifacts** - Checks required files (README, LICENSE, CONTRIBUTING, etc.) -- **Content heuristics** - Validates document content and structure -- **Extended checks** (optional): - - CODEOWNERS presence - - Workflow action version pinning - - Documentation link integrity - - ShellCheck validation - - SPDX header compliance - - Git hygiene (stale branches) - -**Profiles**: -- `all` - Run all checks (default) -- `release` - Release configuration only -- `scripts` - Scripts governance only -- `repo` - Repository health only - -**Trigger Pattern**: -```yaml -on: - workflow_dispatch: - inputs: - profile: - type: choice - options: [all, release, scripts, repo] -``` - -**Usage**: Copy from `templates/workflows/generic/repo_health.yml` and customize for your project. - -### 5. Platform-Specific Workflows - -#### Joomla Workflows (`templates/workflows/joomla/`) - -**ci.yml** - Joomla extension CI workflow: -- Joomla manifest validation -- Extension structure checks -- PHP 7.4-8.2 compatibility -- XML schema validation - -**test.yml** - Comprehensive Joomla testing: -- PHPUnit tests with Joomla framework -- Code quality (PHPCS, PHPStan, Psalm) -- Matrix testing: PHP 7.4-8.2, Joomla 4.4-5.0 -- Code coverage with Codecov - -**release.yml** - Automated Joomla package creation: -- Version bumping in manifests -- ZIP package creation with proper structure -- Checksum generation (SHA256, MD5) -- GitHub release creation with changelog -- Release artifact upload - -#### Dolibarr Workflows (`templates/workflows/dolibarr/`) - -**ci.yml** - Dolibarr module CI workflow: -- Module structure validation -- PHP syntax checking (7.4-8.2) -- Dolibarr API usage validation (16.0-18.0) -- Database schema validation -- Security scanning (SQL injection, XSS, credentials) - -**test.yml** - Dolibarr module testing: -- PHPUnit tests with Dolibarr environment -- Automatic Dolibarr installation -- MySQL database integration -- Module linking and installation -- Code coverage reporting - -#### Generic Workflows (`templates/workflows/generic/`) - -**ci.yml** - Multi-language CI with auto-detection: -- Supports: Node.js, Python, PHP, Go, Ruby, Rust -- Automatic language detection -- Parallel testing across language matrices -- Language-specific linting -- Security scanning with Trivy - -**test.yml** - Comprehensive testing framework: -- Unit tests with coverage -- Integration tests (PostgreSQL, Redis) -- End-to-end tests with Playwright -- Codecov integration -- Test result summaries - -**deploy.yml** - Multi-environment deployment: -- Automatic environment detection -- Multi-language build support -- Staging and production deployment jobs -- Smoke tests after deployment -- Automatic rollback on failure -- Deployment notifications - -**code-quality.yml** - Advanced code analysis: -- Multi-language linting (ESLint, Flake8, PHPCS, golangci-lint, clippy) -- Code formatting validation -- Static analysis (CodeQL, PHPStan, Pylint) -- Dependency security (Snyk, npm audit, pip safety) -- Code complexity analysis - -## Platform Detection - -Workflows use automatic project type detection based on file presence. See [Project Type Detection](../reference/project-types.md) for complete details. - -### Quick Reference - -- **Joomla**: Detected by `joomla.xml` manifest file -- **Dolibarr**: Detected by `htdocs/` directory or `core/modules/` structure -- **Generic**: Fallback for all other projects - -## Usage Instructions - -### For New Projects - -1. **Choose appropriate templates**: - - Joomla → `templates/workflows/joomla/` - - Dolibarr → `templates/workflows/dolibarr/` - - Other → `templates/workflows/generic/` - -2. **Copy workflow files**: - ```bash - mkdir -p .github/workflows - cp /path/to/MokoStandards/templates/workflows/joomla/ci.yml .gitea/workflows/ - ``` - -3. **Customize for your project**: - - Update FILE INFORMATION headers with correct paths - - Adjust branch patterns if needed - - Configure environment-specific settings - - Add/remove validation scripts as appropriate - -4. **Commit and enable**: - ```bash - git add .gitea/workflows/ - git commit -m "Add MokoStandards workflows" - git push - ``` - -### For Existing Projects - -1. Review current workflows against templates -2. Identify gaps or outdated patterns -3. Update workflows incrementally -4. Test on feature branch before merging to main - -## Required Workflows - -All MokoStandards-governed repositories **MUST** implement: - -1. **CI workflow** - For build validation and testing -2. **Security scanning** - CodeQL or equivalent - -Recommended workflows: -- Repository health workflow -- Platform-specific test workflows -- Automated release workflows (for libraries/extensions) -- Deployment workflows (for applications) -- Code quality workflows - -## Workflow Dependencies - -### Common Requirements (All Workflows) - -- Git repository with proper branching structure -- Python 3.x for validation scripts -- Proper permissions configured in repository settings - -### CI Workflows Require - -**For Joomla**: -- `api/validate/manifest.sh` -- `api/validate/xml_wellformed.sh` -- Joomla XML manifest file - -**For Dolibarr**: -- Module descriptor (`core/modules/modMyModule.class.php`) -- Proper Dolibarr directory structure - -**For Generic**: -- Language-specific package managers (npm, pip, composer, etc.) -- Test configurations - -### Test Workflows Require - -- Test framework configuration (Jest, pytest, PHPUnit, etc.) -- Optional: Database services (configured in workflow) -- Optional: Browser testing tools (Playwright) - -### Deployment Workflows Require - -- Environment secrets in GitHub repository settings -- Deployment target configuration -- For SFTP deployments: See [SFTP Deployment Guide](../deployment/sftp.md) - -## Standards Compliance - -All workflows follow MokoStandards requirements: - -- ✅ SPDX license headers (GPL-3.0-or-later) -- ✅ Proper error handling and reporting -- ✅ Step summaries for GitHub Actions UI -- ✅ Audit trail generation -- ✅ Secure secret handling -- ✅ Versioned action dependencies - -## Best Practices - -1. **Pin action versions** - Use `@v4` not `@main` -2. **Test in feature branches** - Never merge untested workflows -3. **Use workflow concurrency** - Prevent duplicate runs -4. **Set appropriate timeouts** - Avoid hanging workflows -5. **Configure secrets properly** - Use GitHub repository secrets -6. **Monitor costs** - Track GitHub Actions minutes usage -7. **Document customizations** - Add comments for deviations -8. **Review step summaries** - Check GitHub Actions UI after runs -9. **Use matrix strategies** - Test across multiple versions -10. **Keep workflows DRY** - Use reusable workflows when possible - -## Integration with Health Scoring - -These workflows contribute to the [Health Scoring System](../policy/health-scoring.md): - -- **CI/CD Status**: 15 points - CI workflow passing -- **Workflows**: 10 points - Required workflows present -- **Security**: 15 points - CodeQL and dependency scanning enabled - -## Support and Troubleshooting - -### Common Issues - -**Workflow fails to find scripts**: -- Ensure scripts exist in expected locations -- Verify script permissions (`chmod +x`) -- Check FILE INFORMATION paths match actual structure - -**SFTP connectivity fails**: -- Verify all required secrets are configured -- Test credentials manually -- Check firewall/network access -- See [SFTP Deployment Guide](../deployment/sftp.md) - -**CodeQL fails**: -- Ensure language matrix includes project languages -- Remove languages with no code to analyze -- Review CodeQL queries configuration - -### Getting Help - -1. Review workflow logs in GitHub Actions UI -2. Check step summaries for detailed errors -3. Validate scripts locally before CI -4. Refer to [Project Types Documentation](../reference/project-types.md) -5. Consult [SFTP Deployment Guide](../deployment/sftp.md) - -For issues with templates: -- Open issue in MokoStandards repository -- Tag with `workflow-template` label -- Include workflow name and error details +- [WORKFLOW_STANDARDS.md](../WORKFLOW_STANDARDS.md) — Canonical workflow reference +- [Workflow Architecture](./workflow-architecture.md) +- [Workflow Inventory](./workflow-inventory.md) +- [Reusable Workflows](./reusable-workflows.md) +- [Release System](./release-system.md) +- [Build System](../build-system/README.md) +- [Health Scoring System](../policy/health-scoring.md) ## Metadata | Field | Value | |---|---| -| Document | Workflow Templates Documentation | +| Document | Workflow Templates — Secondary Reference | | Path | /docs/workflows/README.md | -| Repository | https://git.mokoconsulting.tech/MokoConsulting/MokoStandards | +| Repository | https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API | | Owner | Moko Consulting | | Status | Active | -| Version | 04.00.04 | -| Effective | 2026-01-07 | +| Version | 04.06.00 | +| Effective | 2026-05-05 | ## Version History | Version | Date | Changes | |---|---|---| -| 04.00.04 | 2026-02-08 | Consolidated workflow templates: removed duplicate build-universal (use build.yml.template), removed superseded release-cycle-simple (use release-cycle v2.0) | -| 04.00.04 | 2026-01-07 | Added public workflow templates documentation (build-universal, release-cycle, dependency-review, standards-compliance) | +| 04.06.00 | 2026-05-05 | Rewritten to reflect current architecture: templates live in template repos, sync engine clones at runtime, removed stale `templates/workflows/` references | +| 04.00.04 | 2026-02-08 | Consolidated workflow templates | +| 04.00.04 | 2026-01-07 | Added public workflow templates documentation | | 01.00.00 | 2026-01-07 | Initial comprehensive workflow documentation | - -## See Also - -- [Build System Documentation](../build-system/README.md) -- [Release Management Documentation](../release-management/README.md) -- [Health Scoring System](../policy/health-scoring.md) -- [SFTP Deployment Guide](../deployment/sftp.md) -- [Project Type Detection](../reference/project-types.md) -- [Repository Structure Schema](../guide/repository-structure-schema.md) -- [Workflow Templates (Technical)](../../templates/workflows/README.md) -- [Public Workflow Templates](../../templates/workflows/)