Getting started with GitHub Pages#

While this was the default recommended way to host your map in the past, we now recommend hosting your maps on the WorkAdventure server directly.
It is easier to set up and maintain. However, hosting your maps on GitHub Pages is still a valid option and will keep being supported.

Start by creating a GitHub account if you don't already have one.

Then, go to the GitHub map starter kit repository page and click the "Use this template" button.

You will be prompted to enter a repository name for your map.

Make sure to check the "Include all branches" checkbox, otherwise the GitHub Pages deployment process will not be setup automatically.

If you miss that step, don't worry, you can always fix that by clicking on the Settings tab of your repository and scroll down to the GitHub Pages section. Then select the gh-pages branch. It might already be selected, but please be sure to click on it nonetheless (otherwise GitHub will not enable GitHub pages).

Wait a few minutes... GitHub will deploy a new website with the content of the repository. The address of the website is visible in the "GitHub Pages" section.

Click on the link. You should be redirected directly to WorkAdventure, on your map!

Update your map on GH Pages#

:::caution Important
Before your push on GitHub, you need to instruct the CI/CD pipeline you want to deploy to GitHub pages. To do this,
set up your environment variable in .env file like this : UPLOAD_MODE=GH_PAGES
:::

After making this change, just push to GitHub and your map will be deployed to GitHub Pages.

Testing your map#

To test your map, you need to find its URL. There are 2 kinds of URLs in WorkAdventure:

• Test URLs are in the form https://play.workadventu.re/_/[instance]/[server]/[path to map]
• Registered URLs are in the form https://play.workadventu.re/@/[organization]/[world]/[map]

Assuming your JSON map is hosted at "https://myuser.github.io/myrepo/map.json", then you can browse your map at "https://play.workadventu.re/_/global/myuser.github.io/myrepo/map.json". Here, "global" is a name of an "instance" of your map. You can put anything instead of "global" here. People on the same instance of the map can see each others. If 2 users use 2 different instances, they are on the same map, but in 2 parallel universes. They cannot see each other.

This will connect you to a "public" instance. Anyone can come and connect to a public instance. If you want to manage invitations, or to perform some moderation, you will need to create a "private" instance. Private instances are available in "pro" accounts.

Need some help?#

WorkAdventure is a constantly evolving project and there is plenty of room for improvement regarding map editing.
If you are facing any troubles, do not hesitate to seek help in our Discord server or open an "issue" in the GitHub WorkAdventure account.