PFEE/dashboard-sqdc/.gitea/workflows/README.md

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 main or dashboard branches
• Pull Request to main or dashboard branches

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 only on push to main or dashboard branches (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 main/dashboard

• 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

# 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:

# Run tests locally
npm test

Build errors:

# 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

# 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

# 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:

git commit -m "docs: Update README [skip ci]"

Customization

Change Deployment Conditions

Edit the if condition in deploy job:

if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dashboard'

Add Slack/Email Notifications

Add steps in notify job to send alerts.

Add More Tests

Add test steps in build job:

- name: Run linter
  run: npm run lint

- name: Run integration tests
  run: npm run test:integration

For more details, see DEPLOYMENT.md and SETUP-REGISTRY.md.