Continuous Integration

The Wonderland Editor Docker Image allows setting up efficient continuous integration and delivery of Wonderland Engine projects.

This page describes how to set up efficient automated builds and deployment with the most popular CI services:

Additionally, this page describes how to set up automation for uploading builds to:

Gitlab CI / Gitlab Pages 

Using any docker runner (e.g. the gitlab.com shared runners) on Gitlab.

Configuration 

Your .gitlab-ci.yml should look like follows:

 1stages:
 2  - build
 3  - deploy
 4
 5package:
 6  image: wonderlandengine/editor:latest
 7  stage: build
 8  script:
 9    # Set up the WLE_CREDENTIALS variable for WonderlandEditor to log in
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    # Only deploy to pages on main/master branch
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 is a variable containing an access token. We will configure it in the next step.

Variables 

Find variables for Gitlab CI in the Gitlab web interface: Settings > CI/CD > Variables.

Click “Add Variable” and name it WLE_CREDENTIALS. Its value should be an API-Token, which you can retrieve in the account page, under “API-Token”. Fill in the name and expiration date, then click “Create New API-Token”. The token can be copied from the newly created entry at the top of the list.

For public projects make sure to enable “Protect variable” to prevent unmerged merge requests from being able to access the CI variable.

Cache 

The most time-consuming task in the editor is compressing textures. This is significantly faster, if the results are cached (in the cache/ directory). It is therefore useful to either specify this folder for the CI cache, or check in the files into source control.

GitHub Workflows / GitHub Pages 

Using any docker-enabled runner (e.g. the GitHub hosted runners) on GitHub.

Configuration 

Your workflow file (e.g. .github/workflows/github-pages.yml) should look like follows:

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

Project.wlp is your project file.

$WLE_CREDENTIALS is a secret containing email:password. We will configure it in the next step.

The deploy-pages job will only run on the default branch of your repository (usually main).

Secrets 

Find secrets for GitHub Workflows in the GitHub web interface: Settings > Secrets > Actions.

Click “New repository secret” on the top right and name it WLE_CREDENTIALS. Its value should be an API-Token, which you can retrieve in the account page, under “API-Token”. Fill in the name and expiration date, then click “Create New API-Token”. The token can be copied from the newly created entry at the top of the list.

Secrets are not passed to pullrequests from forks, which means your workflow may not run for pullrequests from outside collaborators.

Bitbucket CI 

Using any docker-enabled runner (e.g. the GitHub hosted runners) on GitHub.

Configuration 

Your pipelines file (e.g. bitbucket-pipelines.yml) should look like follows:

 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 is your project file.

$WLE_CREDENTIALS is a secret containing email:password. We will configure it in the next step.

Note that Bitbucket currently does not offer a service for static page hosting like Gitlab Pages or GitHub Pages. Instead, you can combine this with deploy to netlify.

Deploy to Netlify 

Here we are using Netlify CLI for the “continuous deployment”.

Configuration 

Configure .gitlab-ci.yml as described in Gitlab CI.

Add deploy to the stages:

1stages:
2  - build
3  - deploy

Then append the following deploy job to the end of the file:

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

Variables 

Find variables for Gitlab CI in the Gitlab web interface: Settings > CI/CD > Variables.

Add a variable with a key as NETLIFY_AUTH_TOKEN and set its value to the netlify access token. You can create it here.

Similarly, add another variable with a key as NETLIFY_SITE_ID. Set its value to the “Site ID” of the site that you want to deploy. This will be found on site settings > General > Site details > Site information. (In case you haven’t created a site, follow the guide here).

Publish to HeyVR 

To publish from CI to HeyVR you can use the inofficial “heyvr-cli” package on npm.

The final publishing step needs to be done in the HeyVR developer portal.

Authentication 

Retrieve an API key in your HeyVR Account Settings under “Developer Access Token”.

Add a CI variable or secret HEYVR_ACCESS_TOKEN with the token as a value.

For GitHub Workflows you need to add the token to the environment:

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

Pushing Builds 

When pushing builds from CI, make sure the project is packaged into the deploy/ folder and add the following command to your CI script:

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

The “heyvr-game-id” is the slug of the game you created on heyvr.

For GitHub Actions, replace $CI_COMMIT_TAG with ${{ github.ref_name }}.

Publish to Itch.io 

Itch.io provides a CLI tool called “butler” for uploading builds to your game pages.

Authentication 

To automate publishing for Gitlab CI or GitHub Workflows, you will need to retrieve an API key by running:

1butler login

The command will print the path to the file it wrote API key to. Copy the contents and add a CI variable or secret called BUTLER_API_KEY.

See the Itch.io documentation page for more information.

Installing Butler 

To have the butler command available on your CI job, you can use a docker image that comes with butler pre-installed:

1    image: dosowisko/butler

Here we use dosowisko/butler, but there are many alternatives.

Pushing Builds 

When pushing builds from CI, make sure the project is packaged into the deploy/ folder and add the following command to your CI script:

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

See the Itch.io documentation page.

Explicit Version 

You may also append an explicit version number when deploying from tags. For Gitlab CI, use --userversion $CI_COMMIT_TAG and for GitHub Actions use --userversion ${{ github.ref_name }}.