Automated Godot builds, published to via github

Posted on <2022-03-31 Thu>

With Ludum Dare 50 just around the corner, here's a quick recipe for having automated builds of your godot game pushed to whenever you push code. If that sounds like nonsense then here's a hopefully explanatory gif:


If you want to jump in and see the setup, a demo repo here shows a simple project using github actions to push to this page. This is all made easy thanks to the work of abarichello and josephbmanley and their github actions, and of course the godot developers for creating a game engine that makes it so easy to do headless builds :).

If you want the details, read on:

Godot Project Setup

You'll need a godot project set up with at least one export target defined: godot-to-itch-exports.png 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 to publish to.

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

Even if it's completely empty and private, we'll need an 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:, 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 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

The Fun Bit

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

    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:

    runs-on: ubuntu-20.04
          - name: "windows"
            output: "GodotToItchDemo.exe"
          - name: "linux"
            output: "GodotToItchDemo.x86_64"
          - name: "mac"
            output: ""
          - 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 This matrix will run an action per platform, so we can avoid duplicating the steps to follow.

NB: if you are doing web builds, 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.

  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

  - name: Checkout
    uses: actions/checkout@v2
      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
      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/${{ }}
    godot -v --export ${{}}  ./build/${{ }}/${{ 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 project.

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

The End

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