Data-Coupler/.gitea/workflows

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 REGISTRY_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 REGISTRY_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, verifica le variabili di registry:

env:
  REGISTRY: gitea.home-nas-ds.org  # La tua istanza Gitea self-hosted
  IMAGE_NAME: alessio/data-coupler  # username/repo sulla tua istanza

Importante:

• REGISTRY deve puntare alla tua istanza Gitea con Container Registry abilitato
• IMAGE_NAME deve essere nel formato username/repo della tua istanza
• Assicurati che il Container Registry sia abilitato su Gitea (Settings → Packages)

🚀 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.home-nas-ds.org/alessio/data-coupler:latest

# Versione development specifica
docker pull gitea.home-nas-ds.org/alessio/data-coupler:development-latest

# Versione staging
docker pull gitea.home-nas-ds.org/alessio/data-coupler:staging-latest

# Versione Windows
docker pull gitea.home-nas-ds.org/alessio/data-coupler:latest-windows

Docker Compose

Modifica il docker-compose.yml per usare le immagini Gitea:

services:
  data-coupler:
    image: gitea.home-nas-ds.org/alessio/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:

   • Gitea Actions usa le stesse variabili di GitHub Actions: github.*
   • Esempio: github.ref, github.sha, github.actor
   • Nota: Anche se il servizio è Gitea, le variabili mantengono il prefisso github per compatibilità

2. Username:

   • Nel workflow è hardcoded come alessio per semplicità
   • Puoi usare ${{ github.actor }} se preferisci (utente che ha triggerato il workflow)

3. Registry:

   • GitHub: ghcr.io → Gitea: gitea.home-nas-ds.org (istanza self-hosted)
   • Gitea non ha un registry pubblico centralizzato come GitHub

4. Secret Name:

   • GitHub: GITHUB_TOKEN (automatico) → Gitea: REGISTRY_TOKEN (configurato manualmente)
   • Nota: Il secret non può iniziare con GITEA_ per limitazioni di Gitea

5. 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

Verificare che il Container Registry sia Abilitato

Prima di tutto, verifica che il Container Registry sia abilitato sulla tua istanza Gitea:

1. Controlla la configurazione Gitea (app.ini):

   [packages]
   ENABLED = true
   

2. Verifica accesso al registry:

   curl https://gitea.home-nas-ds.org/v2/
   # Dovrebbe rispondere con status 401 (richiede autenticazione)
   # Se ottieni 404, il registry non è abilitato
   

3. Test autenticazione:

   echo "YOUR_TOKEN" | docker login gitea.home-nas-ds.org -u alessio --password-stdin
   

Errore di Autenticazione

Se ottieni errori di autenticazione:

1. Verifica che il secret REGISTRY_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

• Registry Self-Hosted: Questo workflow è configurato per usare un'istanza Gitea self-hosted (gitea.home-nas-ds.org)
• Container Registry: Assicurati che il Container Registry sia abilitato nella tua istanza Gitea (Settings → Packages)
• Accesso Pubblico/Privato: Le immagini sono private per default; configura le impostazioni del package per renderle pubbliche se necessario
• Esecuzione Manuale: Il workflow supporta anche l'esecuzione manuale tramite workflow_dispatch
• Manifest Multi-Platform: I manifest multi-platform permettono di usare lo stesso tag per Linux e Windows
• Alternative Registry: Se non hai un'istanza Gitea con registry, puoi configurare Docker Hub o altri registry modificando la variabile REGISTRY

🐳 Configurazione Registry Alternativi

Se il Container Registry di Gitea non è disponibile, puoi usare alternative:

Docker Hub

env:
  REGISTRY: docker.io
  IMAGE_NAME: username/data-coupler

# Nel login step:
- name: Log in to Docker Hub
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKER_USERNAME }}
    password: ${{ secrets.DOCKER_TOKEN }}

GitHub Container Registry (come fallback)

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: alessio/data-coupler

# Nel login step:
- name: Log in to GHCR
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

---

Versione: 1.0
Ultimo Aggiornamento: 24 Gennaio 2026
Maintainer: Alessio Dalsanto