From df999fde9919a0e517ba12f8eea0cafdcc0a14cb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 4 Jan 2026 21:29:50 +0000 Subject: [PATCH] Prepare CI/CD migration to .github-private repository Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com> --- docs/CI_MIGRATION_PLAN.md | 308 +++++++++++++++++++++++++++++++++++ docs/MIGRATION_CHECKLIST.md | 314 ++++++++++++++++++++++++++++++++++++ docs/REUSABLE_WORKFLOWS.md | 307 +++++++++++++++++++++++++++++++++++ 3 files changed, 929 insertions(+) create mode 100644 docs/CI_MIGRATION_PLAN.md create mode 100644 docs/MIGRATION_CHECKLIST.md create mode 100644 docs/REUSABLE_WORKFLOWS.md diff --git a/docs/CI_MIGRATION_PLAN.md b/docs/CI_MIGRATION_PLAN.md new file mode 100644 index 0000000..223cb34 --- /dev/null +++ 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 diff --git a/docs/MIGRATION_CHECKLIST.md b/docs/MIGRATION_CHECKLIST.md new file mode 100644 index 0000000..c0e74cb --- /dev/null +++ b/docs/MIGRATION_CHECKLIST.md @@ -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 -- .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 diff --git a/docs/REUSABLE_WORKFLOWS.md b/docs/REUSABLE_WORKFLOWS.md new file mode 100644 index 0000000..54fb252 --- /dev/null +++ b/docs/REUSABLE_WORKFLOWS.md @@ -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)