210 lines
4.6 KiB
Markdown
210 lines
4.6 KiB
Markdown
# CI/CD Setup Guide
|
|
|
|
## Overview
|
|
This project uses **GitHub Actions** for continuous integration and deployment.
|
|
|
|
## Workflows
|
|
|
|
### 1. CI Workflow (`.github/workflows/ci.yml`)
|
|
|
|
Runs on every push and pull request to main/develop branches.
|
|
|
|
**Steps:**
|
|
1. Checkout code
|
|
2. Setup Node.js (18.x, 20.x matrix)
|
|
3. Install dependencies
|
|
4. Run linter
|
|
5. Run type check
|
|
6. Run tests
|
|
7. Generate coverage report
|
|
8. Upload coverage to Codecov
|
|
9. Build application
|
|
10. Upload build artifacts
|
|
11. Security audit
|
|
|
|
### 2. Deploy Workflow (`.github/workflows/deploy.yml`)
|
|
|
|
Runs on push to main branch or manual trigger.
|
|
|
|
**Steps:**
|
|
1. Checkout code
|
|
2. Setup Node.js
|
|
3. Install dependencies
|
|
4. Run tests
|
|
5. Build for production
|
|
6. Deploy to Netlify/Vercel
|
|
7. Notify deployment status
|
|
|
|
## Required Secrets
|
|
|
|
Configure these in GitHub Settings > Secrets and variables > Actions:
|
|
|
|
### For CI
|
|
- `CODECOV_TOKEN` - Codecov upload token (optional)
|
|
- `SNYK_TOKEN` - Snyk security scanning token (optional)
|
|
- `VITE_BACKEND_API_URL` - API URL for build
|
|
|
|
### For Deployment
|
|
|
|
#### Netlify
|
|
- `NETLIFY_AUTH_TOKEN` - Netlify authentication token
|
|
- `NETLIFY_SITE_ID` - Netlify site ID
|
|
- `VITE_BACKEND_API_URL_PROD` - Production API URL
|
|
- `VITE_SENTRY_DSN` - Sentry DSN for error tracking
|
|
|
|
#### Vercel (Alternative)
|
|
- `VERCEL_TOKEN` - Vercel authentication token
|
|
- `VERCEL_ORG_ID` - Vercel organization ID
|
|
- `VERCEL_PROJECT_ID` - Vercel project ID
|
|
- `VITE_BACKEND_API_URL_PROD` - Production API URL
|
|
- `VITE_SENTRY_DSN` - Sentry DSN
|
|
|
|
## Setup Instructions
|
|
|
|
### 1. Enable GitHub Actions
|
|
GitHub Actions is enabled by default for all repositories.
|
|
|
|
### 2. Configure Secrets
|
|
|
|
Go to your repository:
|
|
```
|
|
Settings > Secrets and variables > Actions > New repository secret
|
|
```
|
|
|
|
Add all required secrets listed above.
|
|
|
|
### 3. Configure Codecov (Optional)
|
|
|
|
1. Sign up at [codecov.io](https://codecov.io)
|
|
2. Add your repository
|
|
3. Copy the upload token
|
|
4. Add as `CODECOV_TOKEN` secret
|
|
|
|
### 4. Configure Netlify
|
|
|
|
1. Sign up at [netlify.com](https://netlify.com)
|
|
2. Create a new site
|
|
3. Get your Site ID from Site settings
|
|
4. Generate a Personal Access Token
|
|
5. Add both as secrets
|
|
|
|
### 5. Configure Vercel (Alternative)
|
|
|
|
1. Sign up at [vercel.com](https://vercel.com)
|
|
2. Install Vercel CLI: `npm i -g vercel`
|
|
3. Run `vercel login`
|
|
4. Run `vercel link` in your project
|
|
5. Get tokens from Vercel dashboard
|
|
6. Add as secrets
|
|
|
|
## Manual Deployment
|
|
|
|
### Trigger via GitHub UI
|
|
1. Go to Actions tab
|
|
2. Select "Deploy to Production"
|
|
3. Click "Run workflow"
|
|
4. Select branch
|
|
5. Click "Run workflow"
|
|
|
|
### Trigger via CLI
|
|
```bash
|
|
gh workflow run deploy.yml
|
|
```
|
|
|
|
## Monitoring
|
|
|
|
### View Workflow Runs
|
|
```
|
|
Repository > Actions tab
|
|
```
|
|
|
|
### View Logs
|
|
Click on any workflow run to see detailed logs.
|
|
|
|
### Notifications
|
|
Configure notifications in:
|
|
```
|
|
Settings > Notifications > Actions
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Fails
|
|
1. Check logs in Actions tab
|
|
2. Verify all secrets are set correctly
|
|
3. Test build locally: `npm run build`
|
|
|
|
### Tests Fail
|
|
1. Run tests locally: `npm run test:run`
|
|
2. Check for environment-specific issues
|
|
3. Verify test setup is correct
|
|
|
|
### Deployment Fails
|
|
1. Check deployment logs
|
|
2. Verify API URL is correct
|
|
3. Check Netlify/Vercel dashboard for errors
|
|
|
|
## Best Practices
|
|
|
|
1. **Always run tests before merging**
|
|
2. **Use pull requests for code review**
|
|
3. **Keep secrets secure** - never commit them
|
|
4. **Monitor build times** - optimize if needed
|
|
5. **Review security audit results**
|
|
6. **Keep dependencies updated**
|
|
|
|
## Advanced Configuration
|
|
|
|
### Branch Protection Rules
|
|
|
|
Recommended settings:
|
|
```
|
|
Settings > Branches > Add rule
|
|
|
|
Branch name pattern: main
|
|
☑ Require a pull request before merging
|
|
☑ Require status checks to pass before merging
|
|
- test
|
|
- build
|
|
☑ Require branches to be up to date before merging
|
|
☑ Do not allow bypassing the above settings
|
|
```
|
|
|
|
### Caching
|
|
|
|
The workflows use npm caching to speed up builds:
|
|
```yaml
|
|
- uses: actions/setup-node@v4
|
|
with:
|
|
cache: 'npm'
|
|
```
|
|
|
|
### Matrix Testing
|
|
|
|
Tests run on multiple Node.js versions:
|
|
```yaml
|
|
strategy:
|
|
matrix:
|
|
node-version: [18.x, 20.x]
|
|
```
|
|
|
|
## Cost Optimization
|
|
|
|
GitHub Actions is free for public repositories and includes:
|
|
- 2,000 minutes/month for private repos (free tier)
|
|
- Unlimited for public repos
|
|
|
|
Tips to reduce usage:
|
|
1. Use caching
|
|
2. Run tests only on changed files
|
|
3. Skip redundant jobs
|
|
4. Use self-hosted runners for heavy workloads
|
|
|
|
## Resources
|
|
|
|
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
|
|
- [Netlify Deploy Action](https://github.com/nwtgck/actions-netlify)
|
|
- [Vercel Deploy Action](https://github.com/amondnet/vercel-action)
|
|
- [Codecov Action](https://github.com/codecov/codecov-action)
|
|
|