309 lines
8.6 KiB
Markdown
309 lines
8.6 KiB
Markdown
# 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
|