315 lines
9.9 KiB
Markdown
315 lines
9.9 KiB
Markdown
# .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
|