Upload to itch.io with butler

Home Edit

This post goes over how to upload a game to itch.io with butler and GitHub Actions.


You can use butler to upload your game locally to itch.io with the command-line.

First login to butler:

butler login

Then push your game to itch.io:

butler push directory user/game:channel
  • Replace directory with the folder or .zip file of your built game
  • Replace user with your itch.io username
  • Replace game with your game name
  • Replace channel with your project type (e.g., html5, linux, windows, osx, etc.)

GitHub Actions

To upload your game to itch.io with GitHub Actions, use setup-butler:

# .github/workflows/upload.yml
name: Upload to itch.io
on: push
    runs-on: ubuntu-latest
      - name: Setup butler
        uses: remarkablegames/setup-butler@v1

      - name: Upload to itch.io
        run: butler push directory user/game:channel
          BUTLER_API_KEY: ${{ secrets.BUTLER_API_KEY }}

The BUTLER_API_KEY is your itch.io API key. Generate a key and add it to your repository’s Settings > Secrets and variables > Actions.


Using an example workflow where:

  • build is located at the dist folder
  • itch.io username is remarkablegames
  • game name is inversion
  • game is an html5 project

Then the workflow step is:

 - name: Upload to itch.io
-  run: butler push directory user/game:channel
+  run: butler push dist remarkablegames/inversion:html5
     BUTLER_API_KEY: ${{ secrets.BUTLER_API_KEY }}