|
1 | | -# 🚀 GitHub Actions CI/CD Pipelines |
| 1 | +# GitHub Actions CI/CD |
2 | 2 |
|
3 | | -This project is configured with comprehensive CI/CD pipelines for automated testing, code quality checks, security scanning, and deployment. |
| 3 | +CI/CD pipelines for automated testing, code quality checks, security scanning, and deployment. |
4 | 4 |
|
5 | | -## 📋 Workflow Overview |
| 5 | +## Workflows |
6 | 6 |
|
7 | | -### 🧪 Test Pipeline (`test.yml`) |
| 7 | +### Test Pipeline (`test.yml`) |
8 | 8 |
|
9 | | -**Triggers**: Push to main/develop branches, PRs to main/develop branches |
| 9 | +Runs on push/PR to main/develop branches. |
10 | 10 |
|
11 | | -**Included Jobs**: |
| 11 | +- Linting and TypeScript type checking |
| 12 | +- Unit tests (Node.js 20, 22) |
| 13 | +- Integration tests |
| 14 | +- Code coverage (>95% statements, >90% branches, 100% functions) |
| 15 | +- Security audit (dependency scan + CodeQL) |
| 16 | +- Build verification |
12 | 17 |
|
13 | | -- 🔍 **Code Quality Checks**: Linting, TypeScript type checking |
14 | | -- 🧪 **Unit Tests**: Multi Node.js version testing (20, 22) |
15 | | -- 🔗 **Integration Tests**: Complete functional integration tests |
16 | | -- 📊 **Code Coverage**: Generate coverage reports and upload to Codecov |
17 | | -- 🔒 **Security Scanning**: Dependency security audit and CodeQL analysis |
18 | | -- 🏗️ **Build Test**: Verify the project can build successfully |
19 | | -- 📋 **Test Summary**: Aggregate all test results |
| 18 | +### Code Quality Pipeline (`quality.yml`) |
20 | 19 |
|
21 | | -**Coverage Requirements**: |
| 20 | +Runs on push/PR + daily scheduled checks. |
22 | 21 |
|
23 | | -- Statement Coverage: > 95% |
24 | | -- Branch Coverage: > 90% |
25 | | -- Function Coverage: 100% |
26 | | -- Line Coverage: > 95% |
| 22 | +- Prettier formatting check |
| 23 | +- TypeScript type safety |
| 24 | +- Dependency security check |
| 25 | +- Code complexity analysis |
| 26 | +- JSDoc coverage |
27 | 27 |
|
28 | | -### 🔍 Code Quality Pipeline (`quality.yml`) |
| 28 | +### Release Pipeline (`release.yml`) |
29 | 29 |
|
30 | | -**Triggers**: Push/PR + Daily scheduled checks |
| 30 | +Triggers: tag push, release publication, manual trigger. |
31 | 31 |
|
32 | | -**Included Jobs**: |
| 32 | +- Pre-release validation (full test suite) |
| 33 | +- Production build |
| 34 | +- Deploy to staging/production |
| 35 | +- Auto-generate GitHub Release notes |
33 | 36 |
|
34 | | -- 💅 **Code Formatting Check**: Prettier formatting validation |
35 | | -- 📘 **TypeScript Check**: Type safety verification |
36 | | -- 📦 **Dependency Check**: Outdated packages and security vulnerability checks |
37 | | -- 🧮 **Code Complexity Analysis**: Code quality metrics |
38 | | -- 📚 **Documentation Check**: JSDoc coverage check |
39 | | -- 📋 **Quality Summary**: Comprehensive quality score |
| 37 | +### Dependency Management (`dependencies.yml`) |
40 | 38 |
|
41 | | -**Quality Score Standards**: |
| 39 | +Weekly Monday checks + manual trigger. |
42 | 40 |
|
43 | | -- 🎉 **Excellent** (90%+): Outstanding code quality |
44 | | -- 👍 **Good** (75%+): Stable code quality |
45 | | -- ⚠️ **Fair** (60%+): Needs improvement |
46 | | -- ❌ **Needs Improvement** (<60%): Multiple issues need to be addressed |
| 41 | +- Security audit |
| 42 | +- Outdated package detection |
| 43 | +- Auto-update dependencies (patch/minor/major/all) |
47 | 44 |
|
48 | | -### 🚀 Release Pipeline (`release.yml`) |
| 45 | +## Configuration |
49 | 46 |
|
50 | | -**Triggers**: Tag push, Release publication, Manual trigger |
51 | | - |
52 | | -**Included Jobs**: |
53 | | - |
54 | | -- 🔍 **Pre-Release Validation**: Full test suite verification |
55 | | -- 🏗️ **Build Release Package**: Production build |
56 | | -- 🚀 **Deploy to Staging**: Pre-release environment deployment |
57 | | -- 🌟 **Deploy to Production**: Production environment deployment |
58 | | -- 📝 **Create GitHub Release**: Auto-generate Release notes |
59 | | -- 📢 **Post-Release Notification**: Deployment status notification |
60 | | - |
61 | | -**Deployment Environments**: |
62 | | - |
63 | | -- **Staging**: <https://staging.example.com> |
64 | | -- **Production**: <https://console.example.com> |
65 | | - |
66 | | -### 📦 Dependency Management Pipeline (`dependencies.yml`) |
67 | | - |
68 | | -**Triggers**: Weekly Monday scheduled check, Manual trigger |
69 | | - |
70 | | -**Included Jobs**: |
71 | | - |
72 | | -- 🔒 **Security Audit**: Dependency security vulnerability scanning |
73 | | -- 📋 **Update Check**: Check for outdated dependency packages |
74 | | -- 🔄 **Auto Update**: Automatically update dependencies and test |
75 | | -- 📊 **Dependency Analysis**: Generate dependency analysis report |
76 | | - |
77 | | -**Update Strategies**: |
78 | | - |
79 | | -- **patch**: Only update patch versions (default) |
80 | | -- **minor**: Update minor versions |
81 | | -- **major**: Update major versions |
82 | | -- **all**: Update all versions |
83 | | - |
84 | | -## 🔧 Configuration Requirements |
85 | | - |
86 | | -### Environment Variables |
87 | | - |
88 | | -Configure the following Secrets in GitHub repository settings: |
| 47 | +### Required Secrets |
89 | 48 |
|
90 | 49 | ```bash |
91 | | -# Codecov integration (optional) |
92 | | -CODECOV_TOKEN=your_codecov_token |
93 | | - |
94 | | -# Deployment related (configure as needed) |
95 | | -DEPLOY_SSH_KEY=your_ssh_private_key |
| 50 | +CODECOV_TOKEN=your_codecov_token # Optional |
| 51 | +DEPLOY_SSH_KEY=your_ssh_private_key # If deploying |
96 | 52 | STAGING_HOST=staging.example.com |
97 | 53 | PRODUCTION_HOST=console.example.com |
98 | 54 | ``` |
99 | 55 |
|
100 | | -### Branch Protection Rules |
101 | | - |
102 | | -It is recommended to set protection rules for `main` and `develop` branches: |
103 | | - |
104 | | -```yaml |
105 | | -# .github/branch-protection.yml |
106 | | -main: |
107 | | - required_status_checks: |
108 | | - - "🔍 Code Quality" |
109 | | - - "🧪 Unit Tests" |
110 | | - - "🔗 Integration Tests" |
111 | | - - "📊 Code Coverage" |
112 | | - enforce_admins: true |
113 | | - required_pull_request_reviews: |
114 | | - required_approving_review_count: 1 |
115 | | - dismiss_stale_reviews: true |
116 | | - restrictions: null |
117 | | -``` |
118 | | -
|
119 | | -## 📊 Monitoring and Reporting |
120 | | -
|
121 | | -### Test Reports |
122 | | -
|
123 | | -The following reports are generated after each run: |
124 | | -
|
125 | | -- 📊 **Coverage Report**: `coverage/` directory |
126 | | -- 🧪 **Test Results**: JUnit XML format |
127 | | -- 🔒 **Security Report**: Security audit results |
128 | | -- 📋 **Quality Metrics**: Code quality analysis |
129 | | - |
130 | | -### Quality Metrics |
131 | | - |
132 | | -- **Code Coverage**: Display coverage changes in PRs |
133 | | -- **Dependency Security**: Number and severity of security vulnerabilities |
134 | | -- **Code Complexity**: File size and function complexity |
135 | | -- **Test Results**: Test execution status and duration |
136 | | - |
137 | | -## 🚨 Troubleshooting |
138 | | - |
139 | | -### Test Failures |
140 | | - |
141 | | -1. **View Failed Tests**: Check detailed logs in the Actions page |
142 | | -2. **Reproduce Locally**: Run tests locally using the same Node.js version |
143 | | -3. **Fix Issues**: Fix code or update tests |
144 | | -4. **Resubmit**: Push the fixed code |
145 | | - |
146 | | -### Deployment Failures |
147 | | - |
148 | | -1. **Check Deployment Logs**: Review detailed output of deployment steps |
149 | | -2. **Verify Environment**: Confirm target environment availability |
150 | | -3. **Rollback**: If needed, manually rollback to the previous version |
151 | | -4. **Fix and Retry**: Fix issues and trigger deployment again |
152 | | - |
153 | | -### Dependency Issues |
154 | | - |
155 | | -1. **Security Vulnerabilities**: Automatically create Issues, prioritize fixing high-severity vulnerabilities |
156 | | -2. **Update Failures**: Check test failure reasons, manually resolve compatibility issues |
157 | | -3. **License Issues**: Check license compatibility of new dependencies |
158 | | - |
159 | | -## 🔄 Workflow |
160 | | - |
161 | | -### Development Workflow |
162 | | - |
163 | | -1. **Create Feature Branch**: `git checkout -b feature/new-feature` |
164 | | -2. **Develop and Test**: Develop locally and run tests |
165 | | -3. **Commit Code**: Follow Conventional Commits specification, **commit messages must be in English** |
166 | | -4. **Create PR**: Fill in detailed information using PR template |
167 | | -5. **Automatic Checks**: CI/CD automatically runs all checks |
168 | | -6. **Code Review**: Team members review code |
169 | | -7. **Merge Code**: Merge after all checks pass |
170 | | - |
171 | | -**Commit Convention**: |
172 | | - |
173 | | -- ✅ Correct: `git commit -m "feat: add user authentication"` |
174 | | -- ❌ Wrong: `git commit -m "功能: 添加用户认证"` |
175 | | -- ✅ Correct: `git commit -m "fix: resolve bucket creation issue"` |
176 | | -- ❌ Wrong: `git commit -m "修复: 解决存储桶创建问题"` |
177 | | - |
178 | | -All commit messages must be in English, including titles and descriptions. |
179 | | - |
180 | | -### Release Workflow |
181 | | - |
182 | | -1. **Prepare Release**: Ensure all features are completed and tested |
183 | | -2. **Create Tag**: `git tag v1.0.0 && git push origin v1.0.0` |
184 | | -3. **Automatic Deployment**: CI/CD automatically executes release process |
185 | | -4. **Verify Deployment**: Check Staging environment |
186 | | -5. **Production Deployment**: Manually approve production environment deployment |
187 | | -6. **Monitor**: Monitor production environment health |
188 | | - |
189 | | -## 📈 Performance Optimization |
190 | | - |
191 | | -### Pipeline Optimization |
192 | | - |
193 | | -- **Parallel Execution**: Run independent jobs in parallel whenever possible |
194 | | -- **Cache Strategy**: Use pnpm cache to speed up dependency installation |
195 | | -- **Conditional Execution**: Conditionally run jobs based on changed content |
196 | | -- **Resource Limits**: Set reasonable timeout durations |
| 56 | +## Development Workflow |
197 | 57 |
|
198 | | -### Test Optimization |
| 58 | +1. Create feature branch: `git checkout -b feature/new-feature` |
| 59 | +2. Develop and test locally |
| 60 | +3. Commit using Conventional Commits (English only) |
| 61 | +4. Create PR |
| 62 | +5. CI/CD runs automatically |
| 63 | +6. Code review |
| 64 | +7. Merge after all checks pass |
199 | 65 |
|
200 | | -- **Test Layering**: Unit tests > Integration tests > E2E tests |
201 | | -- **Concurrent Testing**: Utilize Vitest's concurrency capabilities |
202 | | -- **Selective Testing**: Only test code related to changes |
203 | | -- **Mock Strategy**: Reasonably use Mocks to reduce external dependencies |
| 66 | +**Commit messages must be in English:** |
204 | 67 |
|
205 | | -## 🔗 Related Links |
| 68 | +- ✅ `git commit -m "feat: add user authentication"` |
| 69 | +- ❌ `git commit -m "功能: 添加用户认证"` |
206 | 70 |
|
207 | | -- [GitHub Actions Documentation](https://docs.github.com/en/actions) |
208 | | -- [Vitest Documentation](https://vitest.dev/) |
209 | | -- [Codecov Documentation](https://docs.codecov.com/) |
210 | | -- [Project Test Documentation](../tests/README.md) |
| 71 | +## Troubleshooting |
211 | 72 |
|
212 | | -## 📞 Support |
| 73 | +**Test failures**: Check Actions logs, reproduce locally, fix and push. |
213 | 74 |
|
214 | | -If you encounter issues while using CI/CD pipelines: |
| 75 | +**Deployment failures**: Check deployment logs, verify environment, rollback if needed. |
215 | 76 |
|
216 | | -1. Check [GitHub Issues](../../issues) for known issues |
217 | | -2. Create a new [Bug Report](../../issues/new?template=bug_report.md) |
218 | | -3. Contact project maintainers |
| 77 | +**Dependency issues**: Auto-created Issues for security vulnerabilities, manually resolve compatibility issues. |
219 | 78 |
|
220 | | ---- |
| 79 | +## Links |
221 | 80 |
|
222 | | -🤖 **Automation makes development more efficient!** This CI/CD pipeline ensures code quality, improves development efficiency, and allows the team to focus on feature development rather than repetitive manual tasks. |
| 81 | +- [GitHub Actions Docs](https://docs.github.com/en/actions) |
| 82 | +- [Vitest Docs](https://vitest.dev/) |
| 83 | +- [Project Tests](../tests/README.md) |
0 commit comments