From 4b27c6a11d672352ffda01b9d705da9b9ef53b97 Mon Sep 17 00:00:00 2001 From: Alessio Dal Santo Date: Sat, 24 Jan 2026 12:18:41 +0100 Subject: [PATCH] [Docs] Aggiunta Gitea Actions per CI/CD automatico - Creato workflow Gitea Actions (.gitea/workflows/docker-build.yml) - Documentazione completa setup e configurazione - Aggiornati README.md e copilot-instructions.md - Supporto registry Gitea Container Registry (gitea.com) - Stessa strategia di tagging di GitHub Actions - Build multi-platform (Linux + Windows) --- .gitea/workflows/README.md | 219 ++++++++++++++++++++++++++++++ .gitea/workflows/docker-build.yml | 188 +++++++++++++++++++++++++ .github/copilot-instructions.md | 12 ++ README.md | 27 ++++ 4 files changed, 446 insertions(+) create mode 100644 .gitea/workflows/README.md create mode 100644 .gitea/workflows/docker-build.yml diff --git a/.gitea/workflows/README.md b/.gitea/workflows/README.md new file mode 100644 index 0000000..3a785a5 --- /dev/null +++ b/.gitea/workflows/README.md @@ -0,0 +1,219 @@ +# Gitea Actions per Data-Coupler + +## 📋 Panoramica + +Questo repository utilizza **Gitea Actions** per automatizzare la build e la pubblicazione delle immagini Docker del progetto Data-Coupler. + +## 🔧 Configurazione + +### Prerequisiti + +Per utilizzare Gitea Actions su questo repository, è necessario: + +1. **Gitea Account**: Avere un account su Gitea (gitea.com o istanza self-hosted) +2. **Repository Settings**: Abilitare Gitea Actions nelle impostazioni del repository +3. **Container Registry**: Avere accesso al Gitea Container Registry +4. **Secret Configuration**: Configurare il secret `GITEA_TOKEN` + +### Configurazione del Secret GITEA_TOKEN + +Il workflow richiede un token di accesso per pubblicare le immagini Docker sul registry: + +1. Vai su **Settings → Secrets** nel repository Gitea +2. Crea un nuovo secret chiamato `GITEA_TOKEN` +3. Il valore deve essere un Personal Access Token con i seguenti permessi: + - `write:packages` - Per pubblicare container images + - `read:packages` - Per leggere images esistenti + +#### Come Creare un Personal Access Token su Gitea + +1. Vai su **Settings → Applications** nel tuo profilo Gitea +2. Clicca su **Generate New Token** +3. Nome del token: `Data-Coupler Docker Build` +4. Seleziona i seguenti scopes: + - `write:packages` + - `read:packages` +5. Clicca su **Generate Token** +6. Copia il token generato (sarà mostrato solo una volta) + +### Configurazione del Repository Path + +Nel file `.gitea/workflows/docker-build.yml`, modifica la variabile `IMAGE_NAME`: + +```yaml +env: + REGISTRY: gitea.com + IMAGE_NAME: tuo-username/data-coupler # Modifica con il tuo username/organization +``` + +**Importante**: Sostituisci `alessiodalsanto` con il tuo username o nome dell'organization su Gitea. + +## 🚀 Workflow + +### Docker Build Workflow + +**File**: `.gitea/workflows/docker-build.yml` + +#### Trigger Events + +Il workflow si attiva automaticamente su: +- **Push** sui branch: `main`, `development`, `staging` +- **Manual dispatch** tramite interfaccia web + +#### Jobs + +Il workflow è composto da 3 job principali: + +##### 1. `build-linux` - Build Immagine Linux +- **Runner**: `ubuntu-latest` +- **Dockerfile**: `./Dockerfile` +- **Platform**: `linux/amd64` +- **Tags generati**: + - `latest` (per branch `main` e `development`) + - `development-latest` (per branch `development`) + - `staging-latest` (per branch `staging`) + - `-` (per ogni commit) + - `-` (con data/ora) + +##### 2. `build-windows` - Build Immagine Windows +- **Runner**: `windows-2022` +- **Dockerfile**: `./Dockerfile.windows` +- **Platform**: Windows Server 2022 +- **Tags generati**: Come Linux ma con suffisso `-windows` + +##### 3. `create-manifest` - Multi-Platform Manifest +- **Runner**: `ubuntu-latest` +- **Dipendenze**: `build-linux`, `build-windows` +- Crea manifest multi-piattaforma che combinano le immagini Linux e Windows + +### Strategia di Tagging + +#### Branch `main` +- `latest` - Tag condiviso per versione stabile +- `latest-windows` - Versione Windows +- `main-` - Tag specifico per commit +- `main-` - Tag con timestamp + +#### Branch `development` +- `latest` - Tag condiviso per ultime funzionalità +- `development-latest` - Tag specifico per development +- `latest-windows` / `development-latest-windows` - Versioni Windows +- `development-` - Tag specifico per commit +- `development-` - Tag con timestamp + +#### Branch `staging` +- `staging-latest` - Tag per ambiente di staging +- `staging-latest-windows` - Versione Windows +- `staging-` - Tag specifico per commit +- `staging-` - Tag con timestamp + +## 📦 Utilizzo delle Immagini + +### Pull delle Immagini + +#### Da Gitea Container Registry + +```bash +# Ultima versione stabile (main/development) +docker pull gitea.com/alessiodalsanto/data-coupler:latest + +# Versione development specifica +docker pull gitea.com/alessiodalsanto/data-coupler:development-latest + +# Versione staging +docker pull gitea.com/alessiodalsanto/data-coupler:staging-latest + +# Versione Windows +docker pull gitea.com/alessiodalsanto/data-coupler:latest-windows +``` + +### Docker Compose + +Modifica il `docker-compose.yml` per usare le immagini Gitea: + +```yaml +services: + data-coupler: + image: gitea.com/alessiodalsanto/data-coupler:latest + # ... resto della configurazione +``` + +## 🔍 Monitoraggio + +### Visualizzare lo Stato dei Workflow + +1. Vai nella tab **Actions** del repository Gitea +2. Seleziona il workflow **Build and Push Docker Images** +3. Visualizza i dettagli di ogni esecuzione + +### Log e Debug + +- I log di ogni job sono disponibili nell'interfaccia Gitea Actions +- Per debug dettagliato, attiva il manual dispatch con opzione `force_build` + +## 🔄 Differenze con GitHub Actions + +### Principali Differenze + +1. **Context Variables**: + - GitHub: `github.*` → Gitea: `gitea.*` + - Esempio: `github.actor` → `gitea.actor` + +2. **Registry**: + - GitHub: `ghcr.io` → Gitea: `gitea.com` + +3. **Secret Name**: + - GitHub: `GITHUB_TOKEN` (automatico) → Gitea: `GITEA_TOKEN` (configurato manualmente) + +4. **Attestation**: + - Il job di attestation non è presente su Gitea (feature GitHub specifica) + +### Compatibilità + +Gitea Actions è compatibile con la maggior parte delle GitHub Actions disponibili su GitHub Marketplace, incluse: +- `actions/checkout@v4` +- `docker/setup-buildx-action@v3` +- `docker/login-action@v3` +- `docker/build-push-action@v5` +- `docker/metadata-action@v5` + +## 🛠️ Troubleshooting + +### Errore di Autenticazione + +Se ottieni errori di autenticazione: +1. Verifica che il secret `GITEA_TOKEN` sia configurato correttamente +2. Assicurati che il token abbia i permessi `write:packages` +3. Controlla che il token non sia scaduto + +### Build Fallita + +Se la build fallisce: +1. Controlla i log del job specifico +2. Verifica che i Dockerfile siano presenti e corretti +3. Assicurati che le dipendenze NuGet siano accessibili + +### Immagini Non Pubblicate + +Se le immagini non vengono pubblicate: +1. Verifica che `IMAGE_NAME` sia corretto +2. Controlla che il registry sia accessibile +3. Verifica i permessi del token + +## 📚 Risorse + +- [Gitea Actions Documentation](https://docs.gitea.io/en-us/actions/) +- [GitHub Actions Compatibility](https://docs.gitea.io/en-us/usage/actions/comparison/) +- [Docker Build Push Action](https://github.com/docker/build-push-action) + +## 📝 Note + +- Le immagini sono private per default; configura le impostazioni del package per renderle pubbliche se necessario +- Il workflow supporta anche l'esecuzione manuale tramite `workflow_dispatch` +- I manifest multi-platform permettono di usare lo stesso tag per Linux e Windows + +--- + +**Versione**: 1.0 +**Ultimo Aggiornamento**: 24 Gennaio 2026 +**Maintainer**: Alessio Dalsanto diff --git a/.gitea/workflows/docker-build.yml b/.gitea/workflows/docker-build.yml new file mode 100644 index 0000000..e898d07 --- /dev/null +++ b/.gitea/workflows/docker-build.yml @@ -0,0 +1,188 @@ +name: Build and Push Docker Images + +on: + push: + branches: + - main + - development + - staging + workflow_dispatch: + inputs: + force_build: + description: 'Force build even without code changes' + required: false + default: false + type: boolean + +env: + # Gitea Container Registry + REGISTRY: gitea.com + # Repository path (format: owner/repo) + IMAGE_NAME: alessiodalsanto/data-coupler + +jobs: + build-linux: + name: Build Linux Container + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to Gitea Container Registry + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ gitea.actor }} + password: ${{ secrets.GITEA_TOKEN }} + + - name: Extract metadata for Docker + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + # Tag based on branch + type=raw,value=latest,enable=${{ gitea.ref == 'refs/heads/main' }} + type=raw,value=latest,enable=${{ gitea.ref == 'refs/heads/development' }} + type=raw,value=development-latest,enable=${{ gitea.ref == 'refs/heads/development' }} + type=raw,value=dev-latest,enable=${{ gitea.ref == 'refs/heads/dev' }} + type=raw,value=staging-latest,enable=${{ gitea.ref == 'refs/heads/staging' }} + # Tag with commit sha + type=sha,prefix={{branch}}-,format=short + # Tag with date + type=raw,value={{branch}}-{{date 'YYYYMMDD-HHmmss'}} + flavor: | + latest=false + + - name: Build and push Linux Docker image + id: build + uses: docker/build-push-action@v5 + with: + context: . + file: ./Dockerfile + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max + platforms: linux/amd64 + + build-windows: + name: Build Windows Container + runs-on: windows-2022 + permissions: + contents: read + packages: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Log in to Gitea Container Registry + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ gitea.actor }} + password: ${{ secrets.GITEA_TOKEN }} + + - name: Extract metadata for Docker + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + # Tag based on branch with windows suffix + type=raw,value=latest-windows,enable=${{ gitea.ref == 'refs/heads/main' }} + type=raw,value=latest-windows,enable=${{ gitea.ref == 'refs/heads/development' }} + type=raw,value=development-latest-windows,enable=${{ gitea.ref == 'refs/heads/development' }} + type=raw,value=dev-latest-windows,enable=${{ gitea.ref == 'refs/heads/dev' }} + type=raw,value=staging-latest-windows,enable=${{ gitea.ref == 'refs/heads/staging' }} + # Tag with commit sha + type=sha,prefix={{branch}}-windows-,format=short + # Tag with date + type=raw,value={{branch}}-windows-{{date 'YYYYMMDD-HHmmss'}} + flavor: | + latest=false + + - name: Build and push Windows Docker image + run: | + # Convert repository name to lowercase + $imageName = "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}".ToLower() + + # Build with temporary tag + docker build -t "${imageName}:temp-windows" -f Dockerfile.windows . + + # Parse and push all tags + $tags = "${{ steps.meta.outputs.tags }}" -split "`n" + foreach ($tag in $tags) { + $tag = $tag.Trim() + if ($tag) { + # Ensure tag is lowercase + $tag = $tag.ToLower() + Write-Host "Tagging and pushing: $tag" + docker tag "${imageName}:temp-windows" $tag + docker push $tag + } + } + + # Remove temporary tag + docker rmi "${imageName}:temp-windows" + shell: pwsh + + create-manifest: + name: Create Multi-Platform Manifest + runs-on: ubuntu-latest + needs: [build-linux, build-windows] + permissions: + contents: read + packages: write + + steps: + - name: Log in to Gitea Container Registry + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ gitea.actor }} + password: ${{ secrets.GITEA_TOKEN }} + + - name: Create and push manifest for main branch + if: gitea.ref == 'refs/heads/main' + run: | + IMAGE_LOWER=$(echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]') + docker buildx imagetools create -t ${IMAGE_LOWER}:latest \ + ${IMAGE_LOWER}:latest \ + ${IMAGE_LOWER}:latest-windows + + - name: Create and push manifest for development branch + if: gitea.ref == 'refs/heads/development' + run: | + IMAGE_LOWER=$(echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]') + docker buildx imagetools create -t ${IMAGE_LOWER}:latest \ + ${IMAGE_LOWER}:latest \ + ${IMAGE_LOWER}:latest-windows + docker buildx imagetools create -t ${IMAGE_LOWER}:development-latest \ + ${IMAGE_LOWER}:development-latest \ + ${IMAGE_LOWER}:development-latest-windows + + - name: Create and push manifest for dev branch + if: gitea.ref == 'refs/heads/dev' + run: | + IMAGE_LOWER=$(echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]') + docker buildx imagetools create -t ${IMAGE_LOWER}:dev-latest \ + ${IMAGE_LOWER}:dev-latest \ + ${IMAGE_LOWER}:dev-latest-windows + + - name: Create and push manifest for staging branch + if: gitea.ref == 'refs/heads/staging' + run: | + IMAGE_LOWER=$(echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]') + docker buildx imagetools create -t ${IMAGE_LOWER}:staging-latest \ + ${IMAGE_LOWER}:staging-latest \ + ${IMAGE_LOWER}:staging-latest-windows diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7d4c16c..53b1043 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -368,15 +368,26 @@ - `hotfix/*`: Fix urgenti ### CI/CD Pipeline: + +#### GitHub Actions (`.github/workflows/docker-build.yml`) - **Branch `main`**: Pubblica immagini Docker con tag `latest` - **Branch `development`**: Pubblica immagini Docker con tag `latest` e `development-latest` - **Branch `staging`**: Pubblica immagini Docker con tag `staging-latest` - **Ogni commit**: Crea tag con SHA e timestamp per tracciabilità +- **Registry**: GitHub Container Registry (`ghcr.io`) + +#### Gitea Actions (`.gitea/workflows/docker-build.yml`) +- **Stessa configurazione** di GitHub Actions +- **Registry**: Gitea Container Registry (`gitea.com`) +- **Supporto**: Istanze Gitea self-hosted +- **Setup**: Richiede secret `GITEA_TOKEN` con permessi `write:packages` +- **Documentazione**: `.gitea/workflows/README.md` **Note sui Tag Docker**: - `latest`: Condiviso tra `main` e `development` per garantire accesso alle ultime funzionalità - `development-latest`: Specifico per il branch `development`, utile per distinguere le versioni in sviluppo - `staging-latest`: Dedicato al branch `staging` per test pre-produzione +- Disponibile su **entrambi** i registry (GitHub e Gitea) ### Commit Messages: - Formato: `[Tipo] Descrizione breve` @@ -399,6 +410,7 @@ - **DELETION_SYNC_IMPLEMENTATION.md**: Sincronizzazione eliminazioni - **DOCKER_DEPLOYMENT.md**: Guida deployment Docker - **WINDOWS_SERVICE_DEPLOYMENT.md**: Deploy come Windows Service +- **.gitea/workflows/README.md**: Configurazione Gitea Actions ## 🎓 Best Practices per AI Assistants diff --git a/README.md b/README.md index d74a51e..99086c7 100644 --- a/README.md +++ b/README.md @@ -167,6 +167,33 @@ docker build -t data-coupler:local-windows -f Dockerfile.windows . 📚 **Documentazione Docker Completa**: Vedi [DOCKER_DEPLOYMENT.md](DOCKER_DEPLOYMENT.md) e [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md) +### 🔄 CI/CD Pipeline + +Il progetto supporta pipeline CI/CD automatiche su: + +**GitHub Actions** (`.github/workflows/docker-build.yml`): +- Build automatica su push ai branch `main`, `development`, `staging` +- Pubblicazione su GitHub Container Registry (`ghcr.io`) +- Multi-platform manifest (Linux + Windows) + +**Gitea Actions** (`.gitea/workflows/docker-build.yml`): +- Stessa configurazione di GitHub Actions +- Pubblicazione su Gitea Container Registry (`gitea.com`) +- Supporto per istanze Gitea self-hosted +- Configurazione: `.gitea/workflows/README.md` + +**Immagini su Gitea**: +```bash +# Pull da Gitea Container Registry +docker pull gitea.com/alessiodalsanto/data-coupler:latest + +# Versioni disponibili +docker pull gitea.com/alessiodalsanto/data-coupler:development-latest +docker pull gitea.com/alessiodalsanto/data-coupler:staging-latest +``` + +📚 **Setup Gitea**: Vedi [.gitea/workflows/README.md](.gitea/workflows/README.md) + ## Caratteristiche di Sicurezza - **Crittografia**: Le password vengono crittografate prima del salvataggio