Prepare CI/CD migration to .github-private repository

Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>
2026-01-04 21:29:50 +00:00
parent 52a7d341ef
commit df999fde99
3 changed files with 929 additions and 0 deletions
--- a/docs/CI_MIGRATION_PLAN.md
+++ b/docs/CI_MIGRATION_PLAN.md
@@ -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