Automated Godot builds, published to itch.io via github

You'll need a godot project set up with at least one export target defined: You'll likely have a nicer time all round if you use one word names for your exports. In the demo project you'll see I've defined builds for linux, windows, mac and web, and I'm also using them as the "channels" on itch.io to publish to.

If you haven't already got a github repo setup for your codebase, you'll need to do that too.

Even if it's completely empty and private, we'll need an itch.io game page ready to go. We need three pieces of information: your itch username, the name of your project's itch page, as it appears in the url, and an API key.

For example, my project's page is: https://tfinch.itch.io/godot-to-itch-demo, so my itch username is tfinch, and the game name we need is "godot-to-itch-demo." In order to get an API key for your itch account, head over to https://itch.io/user/settings/api-keys and generate one. This is a powerful key so treat it like a password and don't post it in a discord chat.

Store the API key in a secret variable for your github project, called BUTLER_CREDENTIALS. You can find these at github.com/YOU/YOURPROJECTNAME/settings/secrets/actions.

Now to make it work, create the file ".github/workflows/build.yml" in your repo. Add the following to it, with a few small edits:

name: Build + Publish Game

on:
  push:
    branches: main

To begin with we give our workflow a name, and specify it should only run when we push to the main branch. Next, we specify our build job:

jobs:
  build:
    runs-on: ubuntu-20.04
    strategy:
      matrix:
        platform:
          - name: "windows"
            output: "GodotToItchDemo.exe"
          - name: "linux"
            output: "GodotToItchDemo.x86_64"
          - name: "mac"
            output: "GodotToItchDemo.zip"
          - name: "web"
            output: "index.html"

We list all the platforms/export targets we want to build, and specify what filename to output (this is important in particular for web builds, where it should be index.html for itch.io.) This matrix will run an action per platform, so we can avoid duplicating the steps to follow.

NB: if you are doing web builds, itch.io can get a bit confused as to which one is the html game if you push multiple releases. The easiest way to get it working is to do a one-off manual build of your web game, upload to itch, then subsequent automatic builds should work fine.

container:
  image: barichello/godot-ci:3.4.2

Make sure to specify a container image for the version that matches your godot version. You can find the available tags here. I'm using 3.4.2

steps:
  - name: Checkout
    uses: actions/checkout@v2
    with:
      lfs: true
  - name: Setup
    run: |
      mkdir -v -p ~/.local/share/godot/templates
      mv /root/.local/share/godot/templates/${GODOT_VERSION}.stable ~/.local/share/godot/templates/${GODOT_VERSION}.stable
    env:
      GODOT_VERSION: 3.4.2

Make sure to set this godot version as well if you change it above. These two steps just checkout the code and make sure that godot is setup to export your project.

Next, we actually build the project. Here we see the matrix above being used - the platform name is used as a folder name for the build, and the output is used to specify the output filename.

- name: Build
  run: |
    mkdir -v -p build/${{ matrix.platform.name }}
    godot -v --export ${{ matrix.platform.name}}  ./build/${{ matrix.platform.name }}/${{ matrix.platform.output }}

Lastly we upload the build to itch. Make sure to replace ITCH_GAME and ITCH_USER with your details, and note the use of our BUTLER_CREDENTIALS secret. I'm using the export name here as the channel to publish to on our itch.io project.

- name: Deploy to Itch
  uses: josephbmanley/butler-publish-itchio-action@master
  env:
    BUTLER_CREDENTIALS: ${{ secrets.BUTLER_CREDENTIALS }}
    CHANNEL: ${{ matrix.platform.name }}
    ITCH_GAME: godot-to-itch-demo
    ITCH_USER: tfinch
    PACKAGE: build/${{ matrix.platform.name }}

Assuming your game builds without a hitch, you should have automated deployment to itch.io setup. Good luck this weekend if you're jamming!