ci-actions

Raccolta di composite actions GitHub riutilizzabili. Attualmente contiene:

• docker-build-publish - build da Dockerfile con push opzionale e supporto multiarch.
• npm-build - installa le dipendenze npm ed esegue uno script di build sul workspace.
• swagger - copia gli asset statici di swagger-ui-dist nella directory indicata nel repository (checkout).
• vulnscan - scansione vulnerabilità di immagini container con Trivy e notifica opzionale via Telegram.

docker-build-publish

Costruisce immagini Docker usando Buildx a partire da un Dockerfile. Se push=true pubblica i tag sul registry; se sono indicate piu piattaforme (es. linux/amd64,linux/arm64) produce una immagine multiarch.

Inputs (docker-build-publish)

• context (no): build context path.
• dockerfile (no): path del Dockerfile.
• image (si): repository immagine, es. ghcr.io/org/app (se metti http:// o https:// viene rimosso automaticamente).
• tags (si): tag separati da virgola o newline, es. latest,1.2.3.
• platforms (no): piattaforme target separate da virgola/newline.
• push (no): se true, usa buildx --push; se false, usa --load.
• registry_user (no): utente registry, usato solo con push=true.
• registry_password (no): password/token registry, usato solo con push=true.
• build_args (no): build args KEY=VALUE separati da virgola/newline.
• target (no): target stage del Dockerfile (--target).

Note:

• push=false con piu piattaforme non e supportato e fallisce con errore esplicito.
• image deve essere una reference Docker (senza schema URL); se passi http:// o https:// viene normalizzato in automatico.
• Se tags contiene reference complete (es. ghcr.io/org/app:dev), vengono usate cosi come sono.

Esempi docker-build-publish

Build single-arch senza publish:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: paspo/ci-actions/docker-build-publish@main
        with:
          image: ghcr.io/org/app
          tags: latest
          dockerfile: ./Dockerfile
          context: .
          platforms: linux/amd64
          push: false

Build e publish multiarch:

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: paspo/ci-actions/docker-build-publish@main
        with:
          image: ghcr.io/org/app
          tags: |
            latest
            1.2.3
          platforms: linux/amd64,linux/arm64
          push: true
          registry_user: ${{ github.actor }}
          registry_password: ${{ secrets.GITHUB_TOKEN }}

npm-build

Action basata su Docker: usa Node.js 25 (Alpine) per installare le dipendenze ed eseguire uno script npm sul checkout. Lavora direttamente nel $GITHUB_WORKSPACE, quindi gli output (es. dist/, build/, node_modules/) restano disponibili agli step successivi (upload artifact, deploy, ecc.).

Logica di install:

• se esiste package-lock.json o npm-shrinkwrap.json → npm ci (riproducibile, fallisce se il lockfile non è allineato).
• altrimenti → npm install.

Inputs

• working_directory (no, default .): sottocartella di $GITHUB_WORKSPACE dove si trova package.json (utile per monorepo).
• build_script (no, default build): nome dello script npm da eseguire (npm run <build_script>).

Uso

Build standard in root:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: paspo/ci-actions/npm-build@main

Monorepo + script custom:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: paspo/ci-actions/npm-build@main
        with:
          working_directory: packages/web
          build_script: build:prod
      - uses: actions/upload-artifact@v4
        with:
          name: web-dist
          path: packages/web/dist

swagger

Action basata su Docker: installa swagger-ui-dist nell’immagine e copia i file nella directory richiesta nel workspace del job ($GITHUB_WORKSPACE), così gli artifact restano nel checkout (compatibile con actions/upload-artifact, deploy statico, ecc.).

Inputs

• dist_path (no, default dist): percorso relativo rispetto alla root del repository dove vengono copiati i file di Swagger UI.

Outputs

• dist_path: percorso assoluto nella macchina virtuale del runner della directory di output.

Uso

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: swagger
        uses: paspo/ci-actions/swagger@main
        with:
          dist_path: dist/swagger-ui
      - run: echo "Built at ${{ steps.swagger.outputs.dist_path }}"

vulnscan

Effettua il login al registry quando registry_user e registry_password sono impostati (obbligatorio per immagini private), scarica l'immagine indicata, la analizza con Trivy in modalità client-server e fa fallire il job se vengono rilevate vulnerabilità. In caso di failure e se le credenziali Telegram sono impostate, invia una notifica.

Inputs

Nome	Descrizione	Required
image	Immagine da scansionare (es. ghcr.io/org/app:1.2.3).	sì
registry_user	Utente per l'autenticazione al registry.	no (sì per immagini private)
registry_password	Password/token per l'autenticazione al registry.	no (sì per immagini private)
trivy_server	URL del server Trivy da usare in modalità client-server.	sì
trivy_token	Token di autenticazione per il server Trivy.	sì
telegram_to	Chat ID Telegram a cui inviare la notifica in caso di vulnerabilità.	no
telegram_token	Token del bot Telegram.	no

Se user e password sono entrambi valorizzati, il registry per il docker login viene dedotto dall'hostname nell'input image (se contiene ., : o è localhost/127.0.0.1); altrimenti il login è su Docker Hub. Con password vuota docker tenterebbe un login interattivo e fallirebbe in CI: in quel caso lo step viene saltato (adatto a immagini pubbliche o test con act senza secret).

Runner / container del job: serve il client Docker (docker sul PATH), perché l’action esegue docker login e docker pull. Immagini minimali (es. node:*) non includono il CLI: il job fallisce con docker: command not found anche se il daemon è sul host. Usa un’immagine di job che includa docker (es. Ubuntu e pacchetto docker.io / immagini tipo catthehacker/ubuntu:act-*) oppure installa il client prima di questa action. Questo vale per tutte le arch (amd64/arm64): la differenza di comportamento di solito dipende dall’immagine scelta per matrix arm64 vs amd64, non dall’action.

Uso

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: paspo/ci-actions/vulnscan@main
        with:
          image: ghcr.io/org/app:1.2.3
          registry_user: ${{ secrets.REG_USER }}
          registry_password: ${{ secrets.REG_PASS }}
          trivy_server: https://trivy.example.com
          trivy_token: ${{ secrets.TRIVY_TOKEN }}
          telegram_to: ${{ secrets.TG_CHAT }}
          telegram_token: ${{ secrets.TG_TOKEN }}

Testing locale con act

L'action è pensata per i runner GitHub-hosted e richiede il CLI docker sul runner. Se vuoi testarla in locale con act:

Prerequisiti:

• Docker in esecuzione sulla workstation.
• act installato.

Configurazione: il repo fornisce un .actrc che fissa ubuntu-latest (e ubuntu-22.04/ubuntu-24.04) sulle immagini catthehacker/ubuntu:act-*, che includono già moby-cli, Node.js e jq richiesti dall'action. Il socket Docker /var/run/docker.sock viene montato di default da act.

Workflow di test: le composite action non sono invocabili direttamente da act; serve un workflow che le richiami. Esempio da creare in .github/workflows/test-vulnscan.yml nel consumer (o temporaneamente in questo repo per sviluppo):

on: workflow_dispatch
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./vulnscan
        with:
          image: alpine:3.19
          # registry_user / registry_password: solo se l'immagine è privata
          trivy_server: ${{ secrets.TRIVY_SERVER }}
          trivy_token: ${{ secrets.TRIVY_TOKEN }}

Invocazione:

act workflow_dispatch -W .github/workflows/test-vulnscan.yml --secret-file .secrets

Dove .secrets contiene le variabili in formato KEY=value (aggiungilo a .gitignore).

Se non ti serve l'iterazione locale, puoi ignorare questa sezione: l'action funziona out-of-the-box sui runner GitHub-hosted.