Integrazione Continua

L’immagine Docker di Wonderland Editor permette di configurare un’integrazione continua e consegna efficiente dei progetti di Wonderland Engine.

Questa pagina descrive come configurare build e distribuzione automatizzata in modo efficiente con i servizi CI più popolari:

Inoltre, questa pagina descrive come impostare l’automazione per il caricamento delle build su:

Gitlab CI / Gitlab Pages

Usando qualsiasi runner docker (ad esempio i runner condivisi di gitlab.com) su Gitlab.

Configurazione

Il tuo .gitlab-ci.yml dovrebbe apparire come segue:

 1stages:
 2  - build
 3  - deploy
 4
 5package:
 6  image: wonderlandengine/editor:latest
 7  stage: build
 8  script:
 9    # Imposta la variabile WLE_CREDENTIALS per il login su WonderlandEditor
10    - WonderlandEditor --windowless --package --project Project.wlp
11  cache:
12    key: ${CI_COMMIT_REF_SLUG}
13    paths:
14      - cache/
15  artifacts:
16    paths:
17      - deploy
18
19pages:
20  image: alpine:3.14
21  stage: deploy
22  rules:
23    # Distribuire solo sulle pagine nel branch principale/master
24    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
25  before_script:
26    - apk add gzip
27  script:
28    - gzip -k deploy/*.*
29    - mv deploy public
30  artifacts:
31    paths:
32      - public

$WLE_CREDENTIALS è una variabile che contiene un token di accesso. La configureremo nel passaggio successivo.

Variabili

Trova le variabili per Gitlab CI nell’interfaccia web di Gitlab: Impostazioni > CI/CD > Variabili.

Clicca “Aggiungi Variabile” e nomina WLE_CREDENTIALS. Il suo valore dovrebbe essere un token API, che puoi ottenere nella pagina dell’account, sotto “API-Token”. Compila il nome e la data di scadenza, quindi clicca “Crea Nuovo API-Token”. Il token può essere copiato dall’entrata appena creata in cima alla lista.

Per progetti pubblici assicurati di abilitare “Proteggi variabile” per evitare che le richieste di merge non uniti possano accedere alla variabile CI.

Cache

L’attività più lunga nell’editor è la compressione delle texture. Questo processo è significativamente più veloce se i risultati sono memorizzati nella cache (nella directory cache/). È quindi utile specificare questa cartella per il cache CI, o controllare i file nel controllo sorgente.

GitHub Workflows / GitHub Pages

Usando qualsiasi runner abilitato a docker (ad esempio i runner ospitati da GitHub) su GitHub.

Configurazione

Il tuo file di workflow (ad esempio .github/workflows/github-pages.yml) dovrebbe apparire come segue:

 1on: [push]
 2
 3permissions:
 4  contents: read
 5  pages: write
 6  id-token: write
 7
 8jobs:
 9  package:
10    runs-on: ubuntu-latest
11    container:
12      image: wonderlandengine/editor:latest
13    steps:
14    - name: Install Git
15      run: apt-get update && apt-get install -y git git-lfs
16    - uses: actions/checkout@v4
17      with:
18        lfs: true
19    - name: Package
20      run: /usr/local/bin/entrypoint.sh WonderlandEditor --windowless --package --project Project.wlp --output ./public/
21      env:
22          WLE_CREDENTIALS: ${{ secrets.WLE_CREDENTIALS }}
23    - name: Gzip
24      run: find ./public/ -type f ! -name '*.gz' -exec gzip -k "{}" \;
25    - name: Upload artifact
26        uses: actions/upload-pages-artifact@v3
27        with:
28          path: ./public
29
30  deploy-pages:
31    needs: package
32    runs-on: ubuntu-latest
33    if: ${{ format('refs/heads/{0}', github.event.repository.default_branch) == github.ref }}
34    steps:
35      - name: Deploy to GitHub Pages
36        uses: actions/deploy-pages@v4

Project.wlp è il tuo file di progetto.

$WLE_CREDENTIALS è un segreto contenente email:password. La configureremo nel passaggio successivo.

Il job deploy-pages si eseguirà solo sul branch predefinito del tuo repository (di solito main).

Segreti

Trova i segreti per le GitHub Workflows nell’interfaccia web di GitHub: Impostazioni > Segreti > Azioni.

Clicca “Nuovo segreto repository” in alto a destra e nomina WLE_CREDENTIALS. Il suo valore dovrebbe essere un token API, che puoi ottenere nella pagina dell’account, sotto “API-Token”. Compila il nome e la data di scadenza, quindi clicca “Crea Nuovo API-Token”. Il token può essere copiato dall’entrata appena creata in cima alla lista.

I segreti non vengono passati a pull request da fork, il che significa che il tuo workflow potrebbe non eseguirsi per pull request da collaboratori esterni.

Bitbucket CI

Usando qualsiasi runner abilitato a docker (ad esempio i runner ospitati da GitHub) su GitHub.

Configurazione

Il tuo file di pipeline (ad esempio bitbucket-pipelines.yml) dovrebbe apparire come segue:

 1image: wonderlandengine/editor:latest
 2
 3pipelines:
 4  default:
 5    - step:
 6        name: 'Build'
 7        script:
 8          - /usr/local/bin/entrypoint.sh WonderlandEditor --windowless --package --project Project.wlp
 9        artifacts:
10          - deploy/**

Project.wlp è il tuo file di progetto.

$WLE_CREDENTIALS è un segreto contenente email:password. La configureremo nel passaggio successivo.

Si noti che Bitbucket attualmente non offre un servizio per l’hosting di pagine statiche come Gitlab Pages o GitHub Pages. Invece, puoi combinare questo con deploy to netlify.

Deploy to Netlify

Qui stiamo usando Netlify CLI per la “distribuzione continua”.

Configurazione

Configura .gitlab-ci.yml come descritto in Gitlab CI.

Aggiungi deploy agli stadi:

1stages:
2  - build
3  - deploy

Poi aggiungi il seguente job di deploy alla fine del file:

1netlify:
2  image: node:15
3  stage: deploy
4  script:
5    - npm install -g netlify-cli
6    - netlify deploy --dir=public --prod

Variabili

Trova le variabili per Gitlab CI nell’interfaccia web di Gitlab: Impostazioni > CI/CD > Variabili.

Aggiungi una variabile con una chiave come NETLIFY_AUTH_TOKEN e imposta il suo valore sul token di accesso netlify. Puoi crearlo qui.

Allo stesso modo, aggiungi un’altra variabile con una chiave come NETLIFY_SITE_ID. Imposta il suo valore sull’“ID sito” del sito che vuoi distribuire. Questo si troverà su impostazioni del sito > Generale > Dettagli del sito > Informazioni sul sito. (Nel caso tu non abbia creato un sito, segui la guida qui).

Pubblicare su HeyVR

Per pubblicare da CI su HeyVR puoi utilizzare il pacchetto non ufficiale “heyvr-cli” su npm.

L’ultimo passaggio di pubblicazione deve essere fatto nel portale sviluppatori di HeyVR.

Autenticazione

Recupera una chiave API nelle Impostazioni account di HeyVR sotto “Developer Access Token”.

Aggiungi una variabile CI o un segreto HEYVR_ACCESS_TOKEN con il token come valore.

Per le GitHub Workflows devi aggiungere il token all’ambiente:

1  env:
2    HEYVR_ACCESS_TOKEN: ${{ secrets.HEYVR_ACCESS_TOKEN }}

Push delle Build

Quando pubblichi build da CI, assicurati che il progetto sia confezionato nella cartella deploy/ e aggiungi il seguente comando al tuo script CI:

1  - npm i -g heyvr-cli
2  - heyvr --version $CI_COMMIT_TAG --gameId "heyvr-game-id"

L’“ID gioco heyvr” è lo slug del gioco che hai creato su heyvr.

Per le GitHub Actions, sostituisci $CI_COMMIT_TAG con ${{ github.ref_name }}.

Pubblicare su Itch.io

Itch.io fornisce uno strumento CLI chiamato “butler” per caricare build sulle pagine dei tuoi giochi.

Autenticazione

Per automatizzare la pubblicazione per Gitlab CI o GitHub Workflows, dovrai recuperare una chiave API eseguendo:

1butler login

Il comando stamperà il percorso al file a cui ha scritto la chiave API. Copia il contenuto e aggiungi una variabile CI o un segreto chiamato BUTLER_API_KEY.

Consulta la pagina di documentazione Itch.io per ulteriori informazioni.

Installazione di Butler

Per avere il comando butler disponibile nel tuo job CI, puoi usare un’immagine docker che viene fornita con butler pre-installato:

1    image: dosowisko/butler

Qui usiamo dosowisko/butler, ma ci sono molte alternative.

Push delle Build

Quando pubblichi build da CI, assicurati che il progetto sia confezionato nella cartella deploy/ e aggiungi il seguente comando al tuo script CI:

1  - butler push ./deploy user/game:channel-name

Consulta la pagina di documentazione Itch.io.

Versione Esplicita

Puoi anche aggiungere un numero di versione esplicito quando distribuisci dai tag. Per Gitlab CI, usa --userversion $CI_COMMIT_TAG e per le GitHub Actions usa --userversion ${{ github.ref_name }}.