Data-Coupler/.gitea/workflows/README.md

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:

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)
  • <branch>-<sha> (per ogni commit)
  • <branch>-<timestamp> (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-<sha> - Tag specifico per commit
• main-<timestamp> - 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-<sha> - Tag specifico per commit
• development-<timestamp> - Tag con timestamp

Branch staging

• staging-latest - Tag per ambiente di staging
• staging-latest-windows - Versione Windows
• staging-<sha> - Tag specifico per commit
• staging-<timestamp> - Tag con timestamp

📦 Utilizzo delle Immagini

Pull delle Immagini

Da Gitea Container Registry

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

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
• GitHub Actions Compatibility
• 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