222 lines
4.6 KiB
Markdown
222 lines
4.6 KiB
Markdown
# Gitea CI/CD Workflow
|
|
|
|
This directory contains the Gitea Actions workflow for building and deploying the SQDC Dashboard.
|
|
|
|
## Workflow: build-deploy.yml
|
|
|
|
### Triggers
|
|
|
|
- **Push** to any branch
|
|
- **Pull Request** to any branch
|
|
|
|
### Jobs
|
|
|
|
#### 1. Build Job
|
|
|
|
Runs on every push and pull request.
|
|
|
|
**Steps:**
|
|
1. Checkout code
|
|
2. Set up Node.js 18
|
|
3. Install dependencies (`npm ci`)
|
|
4. Run tests
|
|
5. Build React application
|
|
6. Login to container registry
|
|
7. Build Docker image
|
|
8. Tag image with commit SHA and `latest`
|
|
9. Push to registry: `gitea.vidoks.fr/sortifal/pfee`
|
|
|
|
**Artifacts:**
|
|
- Docker image pushed to registry with tags:
|
|
- `gitea.vidoks.fr/sortifal/pfee:<commit-sha>`
|
|
- `gitea.vidoks.fr/sortifal/pfee:latest`
|
|
|
|
#### 2. Deploy Job
|
|
|
|
Runs on push to any branch (not on PRs).
|
|
|
|
**Steps:**
|
|
1. Checkout code
|
|
2. Set up kubectl
|
|
3. Configure kubectl with k3s config
|
|
4. Create registry credentials secret
|
|
5. Apply Kubernetes manifests (namespace, deployment, service, ingress)
|
|
6. Update deployment with new image
|
|
7. Wait for rollout to complete
|
|
8. Verify deployment status
|
|
|
|
**Requirements:**
|
|
- Successful build job
|
|
- Push to protected branches only
|
|
|
|
#### 3. Notify Job
|
|
|
|
Runs after build and deploy jobs complete (success or failure).
|
|
|
|
**Steps:**
|
|
1. Check deployment result
|
|
2. Display success or failure message
|
|
3. Exit with error code if deployment failed
|
|
|
|
## Required Secrets
|
|
|
|
Configure these in Gitea repository settings:
|
|
|
|
| Secret | Description |
|
|
|--------|-------------|
|
|
| `KUBE_CONFIG` | Plain text kubeconfig for k3s cluster |
|
|
| `REGISTRY_URL` | Container registry URL (gitea.vidoks.fr) |
|
|
| `REGISTRY_USER` | Registry username |
|
|
| `REGISTRY_PASSWORD` | Registry password or access token |
|
|
|
|
## Workflow Behavior
|
|
|
|
### On Pull Request
|
|
|
|
- Builds and tests the code
|
|
- Pushes image to registry
|
|
- **Does not deploy** to Kubernetes
|
|
|
|
### On Push to any branch
|
|
|
|
- Builds and tests the code
|
|
- Pushes image to registry
|
|
- **Deploys** to Kubernetes cluster
|
|
- Updates running deployment with new image
|
|
- Verifies deployment success
|
|
|
|
## Image Versioning
|
|
|
|
Each build creates two image tags:
|
|
|
|
1. **Commit SHA tag**: `gitea.vidoks.fr/sortifal/pfee:<commit-sha>`
|
|
- Immutable, specific version
|
|
- Used for rollbacks
|
|
|
|
2. **Latest tag**: `gitea.vidoks.fr/sortifal/pfee:latest`
|
|
- Points to most recent build
|
|
- Used by default in deployment
|
|
|
|
## Monitoring
|
|
|
|
### View Workflow Runs
|
|
|
|
1. Go to repository on Gitea
|
|
2. Click "Actions" tab
|
|
3. Select workflow run to view logs
|
|
|
|
### Check Deployment Status
|
|
|
|
```bash
|
|
# View all resources
|
|
kubectl get all -n sqdc-dashboard
|
|
|
|
# View deployment status
|
|
kubectl rollout status deployment/sqdc-dashboard -n sqdc-dashboard
|
|
|
|
# View pod logs
|
|
kubectl logs -f deployment/sqdc-dashboard -n sqdc-dashboard
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Failures
|
|
|
|
**Tests failing:**
|
|
```bash
|
|
# Run tests locally
|
|
npm test
|
|
```
|
|
|
|
**Build errors:**
|
|
```bash
|
|
# Run build locally
|
|
npm run build
|
|
```
|
|
|
|
### Registry Push Failures
|
|
|
|
**Authentication errors:**
|
|
- Verify `REGISTRY_USER` and `REGISTRY_PASSWORD` are correct
|
|
- Ensure token has `write:package` permission
|
|
|
|
**Network errors:**
|
|
- Check registry URL is accessible: `gitea.vidoks.fr`
|
|
|
|
### Deployment Failures
|
|
|
|
**kubectl connection errors:**
|
|
- Verify `KUBE_CONFIG` is valid and not base64 encoded
|
|
- Test locally: `kubectl get nodes`
|
|
|
|
**Image pull errors:**
|
|
- Check registry credentials secret exists
|
|
- Verify image was pushed successfully
|
|
|
|
**Rollout timeout:**
|
|
- Increase timeout in workflow (default: 5m)
|
|
- Check pod logs for errors
|
|
|
|
## Manual Operations
|
|
|
|
### Manual Deploy
|
|
|
|
```bash
|
|
# Using the deploy script
|
|
./scripts/deploy.sh gitea.vidoks.fr <user> <password> sortifal/pfee
|
|
|
|
# Or manually with kubectl
|
|
kubectl apply -f k8s/
|
|
kubectl set image deployment/sqdc-dashboard dashboard=gitea.vidoks.fr/sortifal/pfee:latest -n sqdc-dashboard
|
|
```
|
|
|
|
### Rollback
|
|
|
|
```bash
|
|
# Using the rollback script
|
|
./scripts/rollback.sh
|
|
|
|
# Or manually
|
|
kubectl rollout undo deployment/sqdc-dashboard -n sqdc-dashboard
|
|
```
|
|
|
|
### Skip Workflow
|
|
|
|
Add `[skip ci]` to commit message:
|
|
|
|
```bash
|
|
git commit -m "docs: Update README [skip ci]"
|
|
```
|
|
|
|
## Customization
|
|
|
|
### Change Deployment Conditions
|
|
|
|
Edit the `if` condition in deploy job to deploy only on specific branches:
|
|
|
|
```yaml
|
|
# Deploy on any push
|
|
if: github.event_name == 'push'
|
|
|
|
# Or deploy only on specific branches
|
|
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/production'
|
|
```
|
|
|
|
### Add Slack/Email Notifications
|
|
|
|
Add steps in notify job to send alerts.
|
|
|
|
### Add More Tests
|
|
|
|
Add test steps in build job:
|
|
|
|
```yaml
|
|
- name: Run linter
|
|
run: npm run lint
|
|
|
|
- name: Run integration tests
|
|
run: npm run test:integration
|
|
```
|
|
|
|
For more details, see [DEPLOYMENT.md](../../DEPLOYMENT.md) and [SETUP-REGISTRY.md](../../SETUP-REGISTRY.md).
|