Fix PHP CodeSniffer dependency conflict, add dev tools, implement platform-aware build system, and prepare dual-repository CI/CD migration #33
308
docs/CI_MIGRATION_PLAN.md
Normal file
308
docs/CI_MIGRATION_PLAN.md
Normal file
@@ -0,0 +1,308 @@
|
|||||||
|
# CI/CD Migration to .github-private Repository
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This document outlines the plan and preparation steps for migrating CI/CD workflows to a centralized `.github-private` repository. This approach provides:
|
||||||
|
|
||||||
|
- **Security**: Keep sensitive CI/CD logic and configurations private
|
||||||
|
- **Reusability**: Share common workflows across multiple repositories
|
||||||
|
- **Maintainability**: Centralize CI/CD updates in one location
|
||||||
|
- **Organization**: Separate CI/CD infrastructure from application code
|
||||||
|
|
||||||
|
## Current State
|
||||||
|
|
||||||
|
### Workflows in `.github/workflows/`
|
||||||
|
1. `php_quality.yml` - PHP code quality checks (PHPCS, PHPStan, PHP Compatibility)
|
||||||
|
2. `release_pipeline.yml` - Release and build pipeline
|
||||||
|
3. `ci.yml` - Continuous integration checks
|
||||||
|
4. `repo_health.yml` - Repository health monitoring
|
||||||
|
5. `version_branch.yml` - Version branch management
|
||||||
|
6. `joomla_testing.yml` - Joomla-specific testing
|
||||||
|
7. `deploy_staging.yml` - Staging deployment
|
||||||
|
|
||||||
|
### Scripts in `scripts/`
|
||||||
|
- `scripts/lib/` - Shared Python libraries (common.py, extension_utils.py, joomla_manifest.py)
|
||||||
|
- `scripts/release/` - Release automation scripts
|
||||||
|
- `scripts/validate/` - Validation scripts
|
||||||
|
- `scripts/run/` - Runtime scripts
|
||||||
|
|
||||||
|
## Migration Strategy
|
||||||
|
|
||||||
|
### Phase 1: Preparation (Current)
|
||||||
|
|
||||||
|
**Files to Keep in Main Repository:**
|
||||||
|
- Simple trigger workflows that call reusable workflows
|
||||||
|
- Repository-specific configuration files
|
||||||
|
- Application scripts that are part of the product
|
||||||
|
|
||||||
|
**Files to Move to .github-private:**
|
||||||
|
- Complex workflow definitions
|
||||||
|
- Shared workflow templates
|
||||||
|
- Sensitive deployment scripts
|
||||||
|
- Organization-wide CI/CD tooling
|
||||||
|
|
||||||
|
### Phase 2: Structure Setup
|
||||||
|
|
||||||
|
Create `.github-private` repository with structure:
|
||||||
|
```
|
||||||
|
.github-private/
|
||||||
|
├── .github/
|
||||||
|
│ └── workflows/
|
||||||
|
│ ├── reusable-php-quality.yml
|
||||||
|
│ ├── reusable-release-pipeline.yml
|
||||||
|
│ ├── reusable-joomla-testing.yml
|
||||||
|
│ └── reusable-deploy-staging.yml
|
||||||
|
├── scripts/
|
||||||
|
│ ├── shared/
|
||||||
|
│ │ ├── extension_utils.py
|
||||||
|
│ │ └── deployment/
|
||||||
|
│ └── templates/
|
||||||
|
└── docs/
|
||||||
|
└── WORKFLOWS.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 3: Conversion
|
||||||
|
|
||||||
|
**Main Repository Workflows (Simplified Callers):**
|
||||||
|
|
||||||
|
Example `php_quality.yml`:
|
||||||
|
```yaml
|
||||||
|
name: PHP Code Quality
|
||||||
|
|
||||||
|
on:
|
||||||
|
pull_request:
|
||||||
|
branches: [ main, dev/*, rc/* ]
|
||||||
|
push:
|
||||||
|
branches: [ main, dev/*, rc/* ]
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
quality:
|
||||||
|
uses: mokoconsulting-tech/.github-private/.github/workflows/reusable-php-quality.yml@main
|
||||||
|
with:
|
||||||
|
php-versions: '["8.0", "8.1", "8.2", "8.3"]'
|
||||||
|
secrets: inherit
|
||||||
|
```
|
||||||
|
|
||||||
|
**Centralized Reusable Workflow:**
|
||||||
|
|
||||||
|
Located in `.github-private/.github/workflows/reusable-php-quality.yml`:
|
||||||
|
```yaml
|
||||||
|
name: Reusable PHP Quality Workflow
|
||||||
|
|
||||||
|
on:
|
||||||
|
workflow_call:
|
||||||
|
inputs:
|
||||||
|
php-versions:
|
||||||
|
required: false
|
||||||
|
type: string
|
||||||
|
default: '["8.0", "8.1", "8.2", "8.3"]'
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
# Full implementation here
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 4: Migration Steps
|
||||||
|
|
||||||
|
1. **Create .github-private repository**
|
||||||
|
- Initialize with README and LICENSE
|
||||||
|
- Set up branch protection rules
|
||||||
|
- Configure team access
|
||||||
|
|
||||||
|
2. **Move workflows to .github-private**
|
||||||
|
- Convert to reusable workflows with `workflow_call` triggers
|
||||||
|
- Test each workflow in isolation
|
||||||
|
- Add proper input parameters and secrets handling
|
||||||
|
|
||||||
|
3. **Update main repository workflows**
|
||||||
|
- Replace with simplified caller workflows
|
||||||
|
- Update documentation
|
||||||
|
- Test integration
|
||||||
|
|
||||||
|
4. **Migrate shared scripts**
|
||||||
|
- Move organization-wide scripts to .github-private
|
||||||
|
- Keep product-specific scripts in main repo
|
||||||
|
- Update import paths and references
|
||||||
|
|
||||||
|
5. **Update documentation**
|
||||||
|
- Document workflow calling conventions
|
||||||
|
- Update development guides
|
||||||
|
- Create troubleshooting guides
|
||||||
|
|
||||||
|
## Configuration Requirements
|
||||||
|
|
||||||
|
### Secrets to Configure
|
||||||
|
|
||||||
|
**In .github-private repository:**
|
||||||
|
- Deployment credentials (FTP_HOST, FTP_USER, FTP_KEY, etc.)
|
||||||
|
- API tokens for external services
|
||||||
|
- Signing keys
|
||||||
|
|
||||||
|
**In main repository:**
|
||||||
|
- Inherit secrets from organization level
|
||||||
|
- Repository-specific overrides only
|
||||||
|
|
||||||
|
### Variables to Configure
|
||||||
|
|
||||||
|
**Organization-level variables:**
|
||||||
|
- DEPLOY_DRY_RUN
|
||||||
|
- FTP_PATH_SUFFIX
|
||||||
|
- PHP_VERSIONS (default)
|
||||||
|
|
||||||
|
**Repository-level variables:**
|
||||||
|
- Repository-specific configurations
|
||||||
|
- Feature flags
|
||||||
|
|
||||||
|
## Workflow Categorization
|
||||||
|
|
||||||
|
### Workflows to Centralize (Move to .github-private)
|
||||||
|
|
||||||
|
1. **php_quality.yml** ✓
|
||||||
|
- Reason: Standardized quality checks across all PHP projects
|
||||||
|
- Type: Reusable workflow
|
||||||
|
- Sensitivity: Low
|
||||||
|
|
||||||
|
2. **release_pipeline.yml** ✓
|
||||||
|
- Reason: Complex release logic, contains sensitive deployment steps
|
||||||
|
- Type: Reusable workflow
|
||||||
|
- Sensitivity: High
|
||||||
|
|
||||||
|
3. **deploy_staging.yml** ✓
|
||||||
|
- Reason: Contains deployment credentials and logic
|
||||||
|
- Type: Reusable workflow
|
||||||
|
- Sensitivity: High
|
||||||
|
|
||||||
|
4. **joomla_testing.yml** ✓
|
||||||
|
- Reason: Shared across Joomla projects
|
||||||
|
- Type: Reusable workflow
|
||||||
|
- Sensitivity: Low
|
||||||
|
|
||||||
|
### Workflows to Keep Local (Main Repository)
|
||||||
|
|
||||||
|
1. **ci.yml**
|
||||||
|
- Reason: Project-specific CI steps
|
||||||
|
- Can call centralized reusable workflows if needed
|
||||||
|
|
||||||
|
2. **repo_health.yml**
|
||||||
|
- Reason: Repository-specific health checks
|
||||||
|
- Keep local with option to extend from centralized base
|
||||||
|
|
||||||
|
3. **version_branch.yml**
|
||||||
|
- Reason: Project-specific versioning strategy
|
||||||
|
- Keep local
|
||||||
|
|
||||||
|
## Scripts Categorization
|
||||||
|
|
||||||
|
### Scripts to Centralize
|
||||||
|
|
||||||
|
1. **scripts/lib/extension_utils.py** ✓
|
||||||
|
- Shared across all extension projects
|
||||||
|
- Platform detection logic
|
||||||
|
|
||||||
|
2. **scripts/lib/common.py** ✓
|
||||||
|
- Universal utility functions
|
||||||
|
- No project-specific logic
|
||||||
|
|
||||||
|
### Scripts to Keep Local
|
||||||
|
|
||||||
|
1. **scripts/lib/joomla_manifest.py**
|
||||||
|
- Joomla-specific, but project may have customizations
|
||||||
|
- Evaluate based on actual usage
|
||||||
|
|
||||||
|
2. **scripts/validate/** (most)
|
||||||
|
- Project-specific validation rules
|
||||||
|
- Keep local unless truly generic
|
||||||
|
|
||||||
|
3. **scripts/release/package_extension.py**
|
||||||
|
- Uses shared libraries but has project-specific logic
|
||||||
|
- Keep local, depend on centralized libs
|
||||||
|
|
||||||
|
## Benefits After Migration
|
||||||
|
|
||||||
|
### For Development Team
|
||||||
|
- ✅ Simplified workflow files in main repository
|
||||||
|
- ✅ Easier to understand and maintain
|
||||||
|
- ✅ Consistent CI/CD across all projects
|
||||||
|
- ✅ Faster updates (update once, applies everywhere)
|
||||||
|
|
||||||
|
### For Security
|
||||||
|
- ✅ Sensitive credentials isolated in private repository
|
||||||
|
- ✅ Controlled access to deployment logic
|
||||||
|
- ✅ Audit trail for CI/CD changes
|
||||||
|
|
||||||
|
### For Organization
|
||||||
|
- ✅ Centralized CI/CD governance
|
||||||
|
- ✅ Standardized processes across projects
|
||||||
|
- ✅ Reduced duplication
|
||||||
|
- ✅ Easier onboarding for new projects
|
||||||
|
|
||||||
|
## Testing Plan
|
||||||
|
|
||||||
|
### Pre-Migration Testing
|
||||||
|
1. ✅ Document all current workflows and their triggers
|
||||||
|
2. ✅ Identify all secrets and variables used
|
||||||
|
3. ✅ Create inventory of external dependencies
|
||||||
|
|
||||||
|
### During Migration
|
||||||
|
1. Create .github-private repository in test organization first
|
||||||
|
2. Convert one workflow at a time
|
||||||
|
3. Test with feature branches
|
||||||
|
4. Validate all trigger conditions work
|
||||||
|
5. Verify secret inheritance
|
||||||
|
|
||||||
|
### Post-Migration Validation
|
||||||
|
1. Run full CI/CD pipeline on test branch
|
||||||
|
2. Verify all workflows execute correctly
|
||||||
|
3. Check deployment to staging
|
||||||
|
4. Monitor for any broken integrations
|
||||||
|
5. Update runbooks and documentation
|
||||||
|
|
||||||
|
## Rollback Plan
|
||||||
|
|
||||||
|
If issues arise during migration:
|
||||||
|
|
||||||
|
1. **Immediate Rollback**: Revert caller workflow to inline implementation
|
||||||
|
2. **Keep Both**: Maintain both local and centralized workflows temporarily
|
||||||
|
3. **Gradual Migration**: Move workflows one at a time with validation periods
|
||||||
|
|
||||||
|
## Timeline
|
||||||
|
|
||||||
|
- **Week 1**: Create .github-private repository, set up structure
|
||||||
|
- **Week 2**: Convert and test php_quality.yml
|
||||||
|
- **Week 3**: Convert and test release_pipeline.yml and deploy_staging.yml
|
||||||
|
- **Week 4**: Convert remaining workflows, finalize documentation
|
||||||
|
- **Week 5**: Complete migration, monitor, and optimize
|
||||||
|
|
||||||
|
## Action Items
|
||||||
|
|
||||||
|
### Immediate (This PR)
|
||||||
|
- [x] Create migration plan document
|
||||||
|
- [ ] Review and approve migration strategy
|
||||||
|
- [ ] Identify team members responsible for migration
|
||||||
|
|
||||||
|
### Next Steps
|
||||||
|
- [ ] Create .github-private repository
|
||||||
|
- [ ] Set up repository structure
|
||||||
|
- [ ] Configure secrets and variables at organization level
|
||||||
|
- [ ] Begin workflow conversion (starting with php_quality.yml)
|
||||||
|
- [ ] Test reusable workflow pattern
|
||||||
|
- [ ] Document lessons learned
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [GitHub Reusable Workflows Documentation](https://docs.github.com/en/actions/using-workflows/reusing-workflows)
|
||||||
|
- [GitHub Security Best Practices](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)
|
||||||
|
- [Workflow Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
For questions or issues during migration:
|
||||||
|
- Review this document
|
||||||
|
- Check GitHub Actions documentation
|
||||||
|
- Contact: DevOps team
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Status**: Draft - Awaiting Review
|
||||||
|
**Author**: GitHub Copilot
|
||||||
|
**Date**: 2026-01-04
|
||||||
|
**Version**: 1.0
|
||||||
314
docs/MIGRATION_CHECKLIST.md
Normal file
314
docs/MIGRATION_CHECKLIST.md
Normal file
@@ -0,0 +1,314 @@
|
|||||||
|
# .github-private Migration Checklist
|
||||||
|
|
||||||
|
This checklist guides the migration of CI/CD workflows from individual repositories to a centralized `.github-private` repository.
|
||||||
|
|
||||||
|
## Phase 1: Planning and Preparation
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
- [x] Create CI_MIGRATION_PLAN.md
|
||||||
|
- [x] Create REUSABLE_WORKFLOWS.md
|
||||||
|
- [x] Create migration checklist
|
||||||
|
- [ ] Review and approve migration plan with team
|
||||||
|
- [ ] Identify workflow owners and stakeholders
|
||||||
|
- [ ] Schedule migration windows
|
||||||
|
|
||||||
|
### Repository Inventory
|
||||||
|
- [x] List all workflows in current repository
|
||||||
|
- [x] Identify workflows to centralize
|
||||||
|
- [x] Identify workflows to keep local
|
||||||
|
- [x] Document workflow dependencies
|
||||||
|
- [x] List all secrets used by workflows
|
||||||
|
- [x] List all variables used by workflows
|
||||||
|
|
||||||
|
### Risk Assessment
|
||||||
|
- [ ] Identify critical workflows that cannot have downtime
|
||||||
|
- [ ] Create rollback procedures
|
||||||
|
- [ ] Set up monitoring for workflow failures
|
||||||
|
- [ ] Communicate migration plan to team
|
||||||
|
|
||||||
|
## Phase 2: .github-private Repository Setup
|
||||||
|
|
||||||
|
### Repository Creation
|
||||||
|
- [ ] Create `.github-private` repository in organization
|
||||||
|
- [ ] Set repository to Private
|
||||||
|
- [ ] Initialize with README
|
||||||
|
- [ ] Add LICENSE file
|
||||||
|
- [ ] Create initial branch structure (main, develop)
|
||||||
|
|
||||||
|
### Repository Configuration
|
||||||
|
- [ ] Configure branch protection rules for main
|
||||||
|
- [ ] Set up team access and permissions
|
||||||
|
- [ ] Enable GitHub Actions for repository
|
||||||
|
- [ ] Configure repository settings (issues, wiki, etc.)
|
||||||
|
|
||||||
|
### Directory Structure
|
||||||
|
- [ ] Create `.github/workflows/` directory
|
||||||
|
- [ ] Create `scripts/` directory for shared scripts
|
||||||
|
- [ ] Create `docs/` directory for documentation
|
||||||
|
- [ ] Create `templates/` directory for workflow templates
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
- [ ] Add README.md explaining repository purpose
|
||||||
|
- [ ] Add USAGE.md with workflow calling examples
|
||||||
|
- [ ] Add CONTRIBUTING.md for workflow maintenance
|
||||||
|
- [ ] Document secret and variable requirements
|
||||||
|
|
||||||
|
## Phase 3: Secrets and Variables Setup
|
||||||
|
|
||||||
|
### Organization-Level Secrets
|
||||||
|
- [ ] Migrate FTP_HOST to organization secrets
|
||||||
|
- [ ] Migrate FTP_USER to organization secrets
|
||||||
|
- [ ] Migrate FTP_KEY to organization secrets (if used)
|
||||||
|
- [ ] Migrate FTP_PASSWORD to organization secrets (if used)
|
||||||
|
- [ ] Migrate FTP_PATH to organization secrets
|
||||||
|
- [ ] Review and migrate other deployment credentials
|
||||||
|
|
||||||
|
### Organization-Level Variables
|
||||||
|
- [ ] Create DEPLOY_DRY_RUN variable
|
||||||
|
- [ ] Create FTP_PATH_SUFFIX variable
|
||||||
|
- [ ] Create FTP_PROTOCOL variable (default: sftp)
|
||||||
|
- [ ] Create FTP_PORT variable (default: 22)
|
||||||
|
- [ ] Document all organization variables
|
||||||
|
|
||||||
|
### Access Configuration
|
||||||
|
- [ ] Grant .github-private repository access to organization secrets
|
||||||
|
- [ ] Configure repository-level secret overrides if needed
|
||||||
|
- [ ] Test secret accessibility from workflows
|
||||||
|
|
||||||
|
## Phase 4: Workflow Migration (Priority Order)
|
||||||
|
|
||||||
|
### Workflow 1: php_quality.yml (Low Risk)
|
||||||
|
- [ ] Create reusable-php-quality.yml in .github-private
|
||||||
|
- [ ] Convert workflow to use workflow_call trigger
|
||||||
|
- [ ] Add input parameters:
|
||||||
|
- [ ] php-versions (JSON array)
|
||||||
|
- [ ] php-extensions (string)
|
||||||
|
- [ ] working-directory (string)
|
||||||
|
- [ ] Test reusable workflow independently
|
||||||
|
- [ ] Update main repository to call reusable workflow
|
||||||
|
- [ ] Test end-to-end integration
|
||||||
|
- [ ] Monitor for issues (1 week)
|
||||||
|
- [ ] Document lessons learned
|
||||||
|
|
||||||
|
### Workflow 2: joomla_testing.yml (Low Risk)
|
||||||
|
- [ ] Create reusable-joomla-testing.yml in .github-private
|
||||||
|
- [ ] Convert workflow to use workflow_call trigger
|
||||||
|
- [ ] Add input parameters as needed
|
||||||
|
- [ ] Test reusable workflow independently
|
||||||
|
- [ ] Update main repository to call reusable workflow
|
||||||
|
- [ ] Test end-to-end integration
|
||||||
|
- [ ] Monitor for issues (1 week)
|
||||||
|
|
||||||
|
### Workflow 3: deploy_staging.yml (High Risk)
|
||||||
|
- [ ] Create reusable-deploy-staging.yml in .github-private
|
||||||
|
- [ ] Convert workflow to use workflow_call trigger
|
||||||
|
- [ ] Add input parameters for deployment configuration
|
||||||
|
- [ ] Configure secret requirements
|
||||||
|
- [ ] Test in non-production environment first
|
||||||
|
- [ ] Create detailed rollback plan
|
||||||
|
- [ ] Update main repository to call reusable workflow
|
||||||
|
- [ ] Perform controlled test deployment
|
||||||
|
- [ ] Monitor deployment logs closely
|
||||||
|
- [ ] Keep original workflow as backup for 2 weeks
|
||||||
|
|
||||||
|
### Workflow 4: release_pipeline.yml (High Risk)
|
||||||
|
- [ ] Create reusable-release-pipeline.yml in .github-private
|
||||||
|
- [ ] Convert workflow to use workflow_call trigger
|
||||||
|
- [ ] Add input parameters:
|
||||||
|
- [ ] release_classification
|
||||||
|
- [ ] platform (joomla, dolibarr)
|
||||||
|
- [ ] Configure all secret requirements
|
||||||
|
- [ ] Test with test release on feature branch
|
||||||
|
- [ ] Update main repository to call reusable workflow
|
||||||
|
- [ ] Perform test release to RC channel
|
||||||
|
- [ ] Monitor release process
|
||||||
|
- [ ] Keep original workflow as backup for 2 weeks
|
||||||
|
|
||||||
|
### Workflows to Keep Local
|
||||||
|
- [ ] Review ci.yml - Keep local or convert?
|
||||||
|
- [ ] Review repo_health.yml - Keep local
|
||||||
|
- [ ] Review version_branch.yml - Keep local
|
||||||
|
- [ ] Document decision rationale
|
||||||
|
|
||||||
|
## Phase 5: Script Migration
|
||||||
|
|
||||||
|
### Shared Scripts
|
||||||
|
- [ ] Copy scripts/lib/extension_utils.py to .github-private
|
||||||
|
- [ ] Copy scripts/lib/common.py to .github-private
|
||||||
|
- [ ] Update import paths in reusable workflows
|
||||||
|
- [ ] Test script functionality in new location
|
||||||
|
- [ ] Update documentation with new paths
|
||||||
|
|
||||||
|
### Script Dependencies
|
||||||
|
- [ ] Document Python version requirements
|
||||||
|
- [ ] Document required pip packages
|
||||||
|
- [ ] Create requirements.txt if needed
|
||||||
|
- [ ] Test scripts in clean environment
|
||||||
|
|
||||||
|
### Local Script Updates
|
||||||
|
- [ ] Update scripts/release/detect_platform.py to use centralized libs
|
||||||
|
- [ ] Update scripts/release/package_extension.py if needed
|
||||||
|
- [ ] Maintain backward compatibility where possible
|
||||||
|
|
||||||
|
## Phase 6: Testing and Validation
|
||||||
|
|
||||||
|
### Unit Testing
|
||||||
|
- [ ] Test each reusable workflow in isolation
|
||||||
|
- [ ] Verify all input parameters work correctly
|
||||||
|
- [ ] Verify secret inheritance works
|
||||||
|
- [ ] Test error handling and failure cases
|
||||||
|
|
||||||
|
### Integration Testing
|
||||||
|
- [ ] Test full CI pipeline on feature branch
|
||||||
|
- [ ] Test PR workflows
|
||||||
|
- [ ] Test release workflow (dry-run)
|
||||||
|
- [ ] Test deployment workflow (to staging)
|
||||||
|
- [ ] Verify all notifications work
|
||||||
|
|
||||||
|
### Performance Testing
|
||||||
|
- [ ] Compare workflow run times (before/after)
|
||||||
|
- [ ] Check for any performance regressions
|
||||||
|
- [ ] Optimize workflow caching if needed
|
||||||
|
|
||||||
|
### Security Testing
|
||||||
|
- [ ] Verify secrets are not exposed in logs
|
||||||
|
- [ ] Test permission boundaries
|
||||||
|
- [ ] Review workflow security best practices
|
||||||
|
- [ ] Run security scan on workflow files
|
||||||
|
|
||||||
|
## Phase 7: Documentation Updates
|
||||||
|
|
||||||
|
### Main Repository Documentation
|
||||||
|
- [ ] Update README.md with workflow links
|
||||||
|
- [ ] Update CONTRIBUTING.md with workflow information
|
||||||
|
- [ ] Update docs/WORKFLOW_GUIDE.md
|
||||||
|
- [ ] Update docs/JOOMLA_DEVELOPMENT.md if needed
|
||||||
|
- [ ] Update docs/QUICK_START.md if needed
|
||||||
|
|
||||||
|
### .github-private Documentation
|
||||||
|
- [ ] Complete README.md
|
||||||
|
- [ ] Complete USAGE.md with all workflows
|
||||||
|
- [ ] Add TROUBLESHOOTING.md
|
||||||
|
- [ ] Add workflow diagrams/flowcharts
|
||||||
|
- [ ] Document secret requirements per workflow
|
||||||
|
|
||||||
|
### Team Communication
|
||||||
|
- [ ] Send announcement email about migration
|
||||||
|
- [ ] Schedule knowledge sharing session
|
||||||
|
- [ ] Create FAQ document
|
||||||
|
- [ ] Update team wiki/confluence
|
||||||
|
|
||||||
|
## Phase 8: Monitoring and Optimization
|
||||||
|
|
||||||
|
### Initial Monitoring (Week 1)
|
||||||
|
- [ ] Monitor all workflow runs daily
|
||||||
|
- [ ] Check for unusual failures
|
||||||
|
- [ ] Collect feedback from team
|
||||||
|
- [ ] Fix any immediate issues
|
||||||
|
|
||||||
|
### Extended Monitoring (Weeks 2-4)
|
||||||
|
- [ ] Review workflow metrics weekly
|
||||||
|
- [ ] Identify optimization opportunities
|
||||||
|
- [ ] Address any recurring issues
|
||||||
|
- [ ] Refine documentation based on questions
|
||||||
|
|
||||||
|
### Optimization
|
||||||
|
- [ ] Optimize workflow caching strategies
|
||||||
|
- [ ] Reduce workflow duplication
|
||||||
|
- [ ] Improve error messages and logging
|
||||||
|
- [ ] Add workflow run time monitoring
|
||||||
|
|
||||||
|
## Phase 9: Cleanup
|
||||||
|
|
||||||
|
### Remove Old Workflows (After 2-4 Weeks)
|
||||||
|
- [ ] Remove old php_quality.yml (keep backup)
|
||||||
|
- [ ] Remove old joomla_testing.yml (keep backup)
|
||||||
|
- [ ] Remove old deploy_staging.yml (keep backup)
|
||||||
|
- [ ] Remove old release_pipeline.yml (keep backup)
|
||||||
|
- [ ] Archive backup workflows in separate branch
|
||||||
|
|
||||||
|
### Remove Redundant Scripts
|
||||||
|
- [ ] Remove scripts now in .github-private (if fully migrated)
|
||||||
|
- [ ] Update .gitignore if needed
|
||||||
|
- [ ] Clean up unused dependencies
|
||||||
|
|
||||||
|
### Documentation Cleanup
|
||||||
|
- [ ] Remove outdated documentation
|
||||||
|
- [ ] Archive old workflow docs
|
||||||
|
- [ ] Update all references to new structure
|
||||||
|
|
||||||
|
## Phase 10: Expansion and Maintenance
|
||||||
|
|
||||||
|
### Apply to Other Repositories
|
||||||
|
- [ ] Identify other repositories to migrate
|
||||||
|
- [ ] Adapt workflows for repository-specific needs
|
||||||
|
- [ ] Migrate repositories incrementally
|
||||||
|
- [ ] Document repository-specific configurations
|
||||||
|
|
||||||
|
### Ongoing Maintenance
|
||||||
|
- [ ] Schedule quarterly workflow reviews
|
||||||
|
- [ ] Keep dependencies updated
|
||||||
|
- [ ] Monitor for GitHub Actions changes
|
||||||
|
- [ ] Collect and implement improvement suggestions
|
||||||
|
|
||||||
|
### Version Management
|
||||||
|
- [ ] Tag stable versions of workflows (@v1, @v2)
|
||||||
|
- [ ] Use semantic versioning for workflow releases
|
||||||
|
- [ ] Maintain changelog for workflow changes
|
||||||
|
- [ ] Communicate breaking changes to users
|
||||||
|
|
||||||
|
## Rollback Procedures
|
||||||
|
|
||||||
|
### If Critical Issue Occurs
|
||||||
|
1. [ ] Identify failing workflow
|
||||||
|
2. [ ] Revert main repository to use local workflow
|
||||||
|
3. [ ] Fix issue in .github-private
|
||||||
|
4. [ ] Test fix thoroughly
|
||||||
|
5. [ ] Re-enable centralized workflow
|
||||||
|
|
||||||
|
### Rollback Commands
|
||||||
|
```bash
|
||||||
|
# Revert to specific commit
|
||||||
|
git checkout <commit-before-migration> -- .github/workflows/workflow-name.yml
|
||||||
|
|
||||||
|
# Or restore from backup branch
|
||||||
|
git checkout backup/pre-migration -- .github/workflows/
|
||||||
|
|
||||||
|
# Commit and push
|
||||||
|
git commit -m "Rollback workflow-name to local implementation"
|
||||||
|
git push
|
||||||
|
```
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
- [ ] All workflows execute successfully in new structure
|
||||||
|
- [ ] No increase in workflow failures
|
||||||
|
- [ ] Deployment success rate maintained
|
||||||
|
- [ ] Team comfortable with new structure
|
||||||
|
- [ ] Documentation complete and accurate
|
||||||
|
- [ ] Rollback procedures tested and documented
|
||||||
|
- [ ] At least 2 team members trained on new system
|
||||||
|
|
||||||
|
## Notes and Lessons Learned
|
||||||
|
|
||||||
|
_(Add notes during migration process)_
|
||||||
|
|
||||||
|
### What Went Well
|
||||||
|
-
|
||||||
|
|
||||||
|
### What Could Be Improved
|
||||||
|
-
|
||||||
|
|
||||||
|
### Unexpected Issues
|
||||||
|
-
|
||||||
|
|
||||||
|
### Recommendations for Future Migrations
|
||||||
|
-
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Migration Status**: Not Started
|
||||||
|
**Start Date**: TBD
|
||||||
|
**Expected Completion**: TBD
|
||||||
|
**Migration Lead**: TBD
|
||||||
|
**Last Updated**: 2026-01-04
|
||||||
307
docs/REUSABLE_WORKFLOWS.md
Normal file
307
docs/REUSABLE_WORKFLOWS.md
Normal file
@@ -0,0 +1,307 @@
|
|||||||
|
# Reusable Workflow Templates for .github-private
|
||||||
|
|
||||||
|
This directory contains example templates for reusable workflows that will be moved to the `.github-private` repository.
|
||||||
|
|
||||||
|
## Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
.github-private/
|
||||||
|
├── .github/
|
||||||
|
│ └── workflows/
|
||||||
|
│ ├── reusable-php-quality.yml
|
||||||
|
│ ├── reusable-release-pipeline.yml
|
||||||
|
│ ├── reusable-joomla-testing.yml
|
||||||
|
│ └── reusable-deploy-staging.yml
|
||||||
|
└── docs/
|
||||||
|
└── USAGE.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage in Main Repositories
|
||||||
|
|
||||||
|
### Basic Pattern
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: Workflow Name
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [ main ]
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
job-name:
|
||||||
|
uses: mokoconsulting-tech/.github-private/.github/workflows/reusable-workflow-name.yml@main
|
||||||
|
with:
|
||||||
|
# Input parameters
|
||||||
|
parameter-name: value
|
||||||
|
secrets: inherit
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example: PHP Quality Check
|
||||||
|
|
||||||
|
**In main repository** (`.github/workflows/php_quality.yml`):
|
||||||
|
```yaml
|
||||||
|
name: PHP Code Quality
|
||||||
|
|
||||||
|
on:
|
||||||
|
pull_request:
|
||||||
|
branches: [ main, dev/*, rc/* ]
|
||||||
|
push:
|
||||||
|
branches: [ main, dev/*, rc/* ]
|
||||||
|
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
php-quality:
|
||||||
|
uses: mokoconsulting-tech/.github-private/.github/workflows/reusable-php-quality.yml@main
|
||||||
|
with:
|
||||||
|
php-versions: '["8.0", "8.1", "8.2", "8.3"]'
|
||||||
|
php-extensions: 'mbstring, xml, curl, zip'
|
||||||
|
working-directory: '.'
|
||||||
|
secrets: inherit
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example: Release Pipeline
|
||||||
|
|
||||||
|
**In main repository** (`.github/workflows/release.yml`):
|
||||||
|
```yaml
|
||||||
|
name: Release Pipeline
|
||||||
|
|
||||||
|
on:
|
||||||
|
workflow_dispatch:
|
||||||
|
inputs:
|
||||||
|
release_classification:
|
||||||
|
description: 'Release classification'
|
||||||
|
required: true
|
||||||
|
default: 'auto'
|
||||||
|
type: choice
|
||||||
|
options:
|
||||||
|
- auto
|
||||||
|
- rc
|
||||||
|
- stable
|
||||||
|
|
||||||
|
permissions:
|
||||||
|
contents: write
|
||||||
|
id-token: write
|
||||||
|
attestations: write
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
release:
|
||||||
|
uses: mokoconsulting-tech/.github-private/.github/workflows/reusable-release-pipeline.yml@main
|
||||||
|
with:
|
||||||
|
release_classification: ${{ inputs.release_classification }}
|
||||||
|
platform: 'joomla' # or 'dolibarr'
|
||||||
|
secrets: inherit
|
||||||
|
```
|
||||||
|
|
||||||
|
## Reusable Workflow Template Examples
|
||||||
|
|
||||||
|
### Template: reusable-php-quality.yml
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: Reusable PHP Quality Workflow
|
||||||
|
|
||||||
|
on:
|
||||||
|
workflow_call:
|
||||||
|
inputs:
|
||||||
|
php-versions:
|
||||||
|
description: 'JSON array of PHP versions to test'
|
||||||
|
required: false
|
||||||
|
type: string
|
||||||
|
default: '["8.0", "8.1", "8.2", "8.3"]'
|
||||||
|
php-extensions:
|
||||||
|
description: 'PHP extensions to install'
|
||||||
|
required: false
|
||||||
|
type: string
|
||||||
|
default: 'mbstring, xml, curl, zip'
|
||||||
|
working-directory:
|
||||||
|
description: 'Working directory'
|
||||||
|
required: false
|
||||||
|
type: string
|
||||||
|
default: '.'
|
||||||
|
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
compatibility-check:
|
||||||
|
name: PHP Compatibility Check
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- name: Checkout repository
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Setup PHP
|
||||||
|
|
|||||||
|
uses: shivammathur/setup-php@v2
|
||||||
|
with:
|
||||||
|
php-version: '8.1'
|
||||||
|
extensions: ${{ inputs.php-extensions }}
|
||||||
|
|
||||||
|
- name: Install dependencies
|
||||||
|
run: |
|
||||||
|
composer global require "squizlabs/php_codesniffer:^3.0" --with-all-dependencies
|
||||||
|
composer global require "phpcompatibility/php-compatibility:^9.0" --with-all-dependencies
|
||||||
|
phpcs --config-set installed_paths ~/.composer/vendor/phpcompatibility/php-compatibility
|
||||||
|
|
||||||
|
- name: Check PHP 8.0+ Compatibility
|
||||||
|
working-directory: ${{ inputs.working-directory }}
|
||||||
|
run: phpcs --standard=PHPCompatibility --runtime-set testVersion 8.0- src/
|
||||||
|
|
||||||
|
phpcs:
|
||||||
|
name: PHP_CodeSniffer
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
strategy:
|
||||||
|
matrix:
|
||||||
|
php-version: ${{ fromJson(inputs.php-versions) }}
|
||||||
|
steps:
|
||||||
|
- name: Checkout repository
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Setup PHP
|
||||||
|
uses: shivammathur/setup-php@v2
|
||||||
|
with:
|
||||||
|
php-version: ${{ matrix.php-version }}
|
||||||
|
extensions: ${{ inputs.php-extensions }}
|
||||||
|
|
||||||
|
- name: Install PHP_CodeSniffer
|
||||||
|
run: composer global require "squizlabs/php_codesniffer:^3.0" --with-all-dependencies
|
||||||
|
|
||||||
|
- name: Run PHP_CodeSniffer
|
||||||
|
working-directory: ${{ inputs.working-directory }}
|
||||||
|
run: phpcs --standard=phpcs.xml src/
|
||||||
|
|
||||||
|
phpstan:
|
||||||
|
name: PHPStan Static Analysis
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
strategy:
|
||||||
|
matrix:
|
||||||
|
php-version: ${{ fromJson(inputs.php-versions) }}
|
||||||
|
steps:
|
||||||
|
- name: Checkout repository
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Setup PHP
|
||||||
|
uses: shivammathur/setup-php@v2
|
||||||
|
with:
|
||||||
|
php-version: ${{ matrix.php-version }}
|
||||||
|
extensions: ${{ inputs.php-extensions }}
|
||||||
|
|
||||||
|
- name: Install PHPStan
|
||||||
|
run: |
|
||||||
|
composer global require phpstan/phpstan "^1.0" --with-all-dependencies
|
||||||
|
|
||||||
|
- name: Run PHPStan
|
||||||
|
working-directory: ${{ inputs.working-directory }}
|
||||||
|
run: phpstan analyse --configuration=phpstan.neon
|
||||||
|
```
|
||||||
|
|
||||||
|
### Template: reusable-release-pipeline.yml
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: Reusable Release Pipeline
|
||||||
|
|
||||||
|
on:
|
||||||
|
workflow_call:
|
||||||
|
inputs:
|
||||||
|
release_classification:
|
||||||
|
description: 'Release classification (auto, rc, stable)'
|
||||||
|
required: false
|
||||||
|
type: string
|
||||||
|
default: 'auto'
|
||||||
|
platform:
|
||||||
|
description: 'Extension platform (joomla, dolibarr)'
|
||||||
|
required: false
|
||||||
|
type: string
|
||||||
|
default: 'joomla'
|
||||||
|
secrets:
|
||||||
|
FTP_HOST:
|
||||||
|
required: true
|
||||||
|
FTP_USER:
|
||||||
|
required: true
|
||||||
|
FTP_KEY:
|
||||||
|
required: false
|
||||||
|
FTP_PASSWORD:
|
||||||
|
required: false
|
||||||
|
FTP_PATH:
|
||||||
|
required: true
|
||||||
|
FTP_PROTOCOL:
|
||||||
|
required: false
|
||||||
|
FTP_PORT:
|
||||||
|
required: false
|
||||||
|
|
||||||
|
permissions:
|
||||||
|
contents: write
|
||||||
|
id-token: write
|
||||||
|
attestations: write
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
guard:
|
||||||
|
name: Guardrails and Metadata
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
outputs:
|
||||||
|
version: ${{ steps.meta.outputs.version }}
|
||||||
|
# ... other outputs
|
||||||
|
steps:
|
||||||
|
# Guard logic here
|
||||||
|
|
||||||
|
build-and-release:
|
||||||
|
name: Build and Release
|
||||||
|
needs: guard
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- name: Checkout
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Detect Platform
|
||||||
|
id: platform
|
||||||
|
run: |
|
||||||
|
python3 scripts/release/detect_platform.py src
|
||||||
|
|
||||||
|
- name: Build ZIP
|
||||||
|
run: |
|
||||||
|
# Build logic here
|
||||||
|
|
||||||
|
# ... remaining steps
|
||||||
|
```
|
||||||
|
|
||||||
|
## Benefits of Centralized Workflows
|
||||||
|
|
||||||
|
1. **Single Source of Truth**: Update workflow logic in one place
|
||||||
|
2. **Version Control**: Pin to specific versions (@v1, @main, @sha)
|
||||||
|
3. **Testing**: Test changes in .github-private before rolling out
|
||||||
|
4. **Security**: Keep sensitive logic private
|
||||||
|
5. **Reusability**: Use same workflow across multiple repositories
|
||||||
|
|
||||||
|
## Migration Checklist
|
||||||
|
|
||||||
|
- [ ] Create .github-private repository
|
||||||
|
- [ ] Set up repository permissions and protection rules
|
||||||
|
- [ ] Move workflow files and convert to reusable format
|
||||||
|
- [ ] Update main repository workflows to call reusable workflows
|
||||||
|
- [ ] Configure secrets at organization level
|
||||||
|
- [ ] Test all workflows end-to-end
|
||||||
|
- [ ] Update documentation
|
||||||
|
- [ ] Train team on new workflow structure
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Workflow Not Found
|
||||||
|
- Ensure .github-private repository has correct permissions
|
||||||
|
- Verify workflow path is correct
|
||||||
|
- Check that target branch/tag exists
|
||||||
|
|
||||||
|
### Secrets Not Available
|
||||||
|
- Use `secrets: inherit` in caller workflow
|
||||||
|
- Configure secrets at organization or repository level
|
||||||
|
- Verify secret names match between caller and reusable workflow
|
||||||
|
|
||||||
|
### Inputs Not Passed Correctly
|
||||||
|
- Check input types (string, boolean, number)
|
||||||
|
- Verify required vs optional inputs
|
||||||
|
- Use correct JSON format for arrays
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [Reusing Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows)
|
||||||
|
- [workflow_call Event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_call)
|
||||||
|
- [Calling Reusable Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow)
|
||||||
Reference in New Issue
Block a user
The REUSABLE_WORKFLOWS.md document mentions calling workflows from
.github-privaterepository on line 134, but the heading on line 117 states this is for MokoStandards (Public). This is inconsistent with the dual-repository architecture described in the PR where public workflows should call MokoStandards and private workflows should call .github-private.The workflow call should reference
mokoconsulting-tech/MokoStandardsinstead ofmokoconsulting-tech/.github-privatefor PHP Quality checks as they are categorized as public/community workflows.