Forgejo Static Pages – Deploy Service

Sistema di pubblicazione automatica di siti statici per Forgejo, simile a GitHub Pages / GitLab Pages.

Scelte tecniche

Linguaggio:

• Python + FastAPI

Tecnlogie:

• Docker
• Caddy
• Forgejo
• Garage S3

Motivi:

• codice leggibile
• gestione upload semplice
• ottimo supporto async
• container leggero
• facile validare token Forgejo

Sicurezza:

• Forgejo Actions token (GITHUB_TOKEN)
• Verifica via API Forgejo
• Path rigidamente controllato

una sola S3 key, solo nel container

Architettura

Forgejo Action
  ├─ upload artifact (Forgejo)
  └─ POST /deploy?run_id=XYZ
               │
               v
        deploy-service
           ├─ valida token
           ├─ scarica artifact da Forgejo
           ├─ safe extract
           └─ deploy versionato
                | 
                | S3 (master key)
                v
        Garage
        (bucket: forgejo-pages)
        /michele/blog
        /michele/docs
        /mario/blog
                |
                | static website
                v
        Caddy (reverse proxy)
                |
                v
        https://michele.forgejo.it/blog

Struttura del bucket s3

forgejo-pages/
├── michele/
│   ├── blog/
│   │   └── index.html
│   └── docs/
│       └── index.html
└── mario/
    └── blog/
        └── index.html


forgejo-pages/
└── michele/
    └── blog/
        ├── releases/
        │   ├── 2026-01-18T10-30-00/
        │   ├── 2026-01-18T11-05-00/
        │   └── 2026-01-18T11-40-12/
        └── current/
            └── index.html

Url di esempio

https://michele.forgejo.it/blog
https://michele.forgejo.it/docs
https://mario.forgejo.it/blog

Garage (s3)

Verrà utilizzato garage come disco s3, ma è sostituibile con servizi analoghi. Garage nei bucket pubblici permette di esporre pagine statiche html tramite http.

Caddy

Verrà usato caddy come server https, che si occuperà di ascoltare sulla porta https (443) e fare da reverse proxy. Esempio di Caddyfile:

*.forgejo.it {

    @user {
        host_regexp user ^(?P<user>[^.]+)\.forgejo\.it$
    }

    reverse_proxy @user https://garage.internal {
        header_up Host forgejo-pages.garage
        rewrite * /{re.user}{path}/current
    }

    encode gzip
}

✔ nessuna reload ✔ zero variabili runtime ✔ HTTPS automatico ✔ routing uniforme

Esempio di forgejo action

Sul repository occorre creare una nuova action, come questa:

- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: site
    path: dist/

- name: Trigger deploy
  run: |
    curl -X POST https://deploy.internal/deploy \
      -H "Authorization: Bearer $GITHUB_TOKEN" \
      -F "repo=$GITHUB_REPOSITORY" \
      -F "run_id=$GITHUB_RUN_ID"

      

✔ sicurezza ✔ audit ✔ controllo path

Struttura progetto

forgejo-deploy-service/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── app/
│   ├── main.py
│   ├── forgejo.py
│   └── s3.py
└── README.md

Possibili prossimi step

• aggiungere rate limit
• firmare le richieste con OIDC
• aggiungere rollback API
• scrivere un SECURITY.md
• aggiungere quota per utente