GB Studio CI Example

Introduction

This repository provides a ready-to-use GitHub Actions CI/CD pipeline for GB Studio projects, using the Docker image gb-studio-ci to build and deploy your game.

The workflows automate common tasks such as validating build targets, extracting project metadata, building game binaries, and publishing releases on itch.io or GitHub.

The repository includes three main workflows plus several utility workflows that handle modular tasks.

How to Use This Repository

You can use this repository as a template for your own GB Studio project:

• Create a new repository using the Use this template button or by downloading the source code.
• Customize your workflows by keeping only those you need.
• Adjust environment variables according to your needs.
• Commit your changes and monitor the result from the Actions tab.

Workflows

Main Branch CI (ci-main-branch.yml)

This workflow runs automatically on pushes and pull requests to your default branch, and can also be triggered manually.
It build your project and upload the result as artifacts. This is useful to detect breaking changes in your project or to test builds.

Target configuration

You can provide the targets by modifying the environment variable TARGET_LIST:

env:
  TARGET_LIST: 'rom, pocket, web'

Itch.io Deployment (ci-itchio-deploy.yml)

This workflow is triggered when a new tag matching the pattern v* is pushed to the repository. It builds specified targets and uploads them to your itch.io project using the butler command-line tool.

Api Key setup

You first need to configure your API key in order to be able to upload the builds to itch.io. In order to upload your project to itch.io you need to configure your api key, you can generate a new one in the api-keys section from your itch.io account settings.

Once generated, you need to create a new repository secret named ITCH_IO_API_KEY with the value of your secret key.

Project configuration

You also need to specify the target project by providing the ITCH_IO_USERNAME and the ITCH_IO_GAME to target.
As an example, to target the project pomdap.itch.io/gb-studio-ci-example:

env:
  ITCH_IO_USERNAME: pomdap
  ITCH_IO_GAME: gb-studio-ci-example

You can also specify the targets or if you want the source code to be uploaded as well:

env:
  TARGET_LIST: 'rom, pocket, web'
  UPLOAD_SOURCE: true

GitHub Release (ci-github-release.yml)

This workflow is triggered when a new tag matching the pattern v* is pushed to the repository.
It builds the specified targets and creates a GitHub Release, attaching all generated artifacts.

This can be used to deliver official game builds directly via the GitHub release page.

Target configuration

You can provide the targets by modifying the environment variable TARGET_LIST:

env:
  TARGET_LIST: 'rom, pocket, web'

Utility Workflows

These workflows are designed to be called from others to perform common tasks:

• utility-validate-target-list.yml: Validate and filter the list of build targets.
• utility-extract-project-configuration.yml: Extract project filepath, version, name, and ROM extension from the project files.
• utility-build-and-upload-artifact.yml: Build a game target using gb-studio-ci and upload the result as an artifact.

Each utility workflow is standalone and can be combined freely in your own workflows.