Butler itch.io Deployment

Release automation · Released

Butler itch.io Deployment turns game publishing into a repeatable GitHub Actions job. A push to the main branch builds or selects the game files, installs itch.io’s Butler command-line tool, and sends each platform build to the correct itch.io channel.

The workflow also supports a manual run from GitHub Actions. This gives a developer control over release timing without rebuilding the upload commands on a local machine.

The standard publishing workflow

The general workflow publishes an existing build folder. It includes examples for:

• HTML games from a www folder
• Windows builds
• macOS builds
• Linux builds
• several platform builds in one release job

Each upload follows the same Butler pattern:

butler push build-folder username/game-name:channel

The folder points to the game files. The project name identifies the itch.io page. The channel tells itch.io whether the upload belongs to HTML, Windows, macOS, or Linux.

One release job might use:

butler push www username/game-name:html
butler push build/windows username/game-name:windows
butler push build/macos username/game-name:mac
butler push build/linux username/game-name:linux

Developers remove the platforms they do not ship and replace the sample project name with their itch.io account and game slug.

Secure itch.io access

The workflow reads the Butler API key from a GitHub Actions secret named BUTLER_API_KEY. The key stays out of the workflow file and game source.

The secret enters the environment only during the upload step:

env:
  BUTLER_API_KEY: $

This setup avoids storing a release credential in source files or repeating it in local shell history.

Turbo game builds

A second workflow handles web games made with the Turbo game engine. It prepares Rust, adds the WebAssembly target, installs the Turbo CLI, and runs turbo export.

Turbo writes the HTML and WebAssembly build to www. Butler then publishes the folder to the itch.io HTML channel.

This path joins build and release work in one job:

1. Check out the game source.
2. Prepare Rust and WebAssembly.
3. Install the Turbo CLI.
4. Export the web build.
5. Install Butler.
6. Publish the build to itch.io.

Why I use it

Manual uploads are easy to forget or perform differently from one release to the next. This workflow keeps platform folders, itch.io channels, credentials, and release steps in one visible process.

GitHub Actions records each run and its output. A failed build or upload leaves a log, while a successful run publishes the same way every time.

The templates work as a starting point. A game project still needs its own build folders, itch.io page, API secret, account name, game slug, and selected platform channels.

Role

Developer

Technologies

GitHub Actions, YAML, Butler, itch.io, Turbo, Rust, WebAssembly