GitHub Actions | Manual | Castle Game Engine

GitHub Actions

Table of Contents

1. Introduction
2. Usage
3. Under the hood
4. Taking it further: Make a release

1. Introduction

You can use GitHub Actions to have automatic builds for your projects, done by GitHub, after every commit.

2. Usage

Download this file: build.yml and place it at .github/workflows/build.yml path in your project. That is, create a subdirectory .github, then subdirectory workflows, then put the build.yml file inside.

See the sample project castle-game using it.
Then commit, push and just watch the GitHub "Actions" tab as it picks up the commit and automatically rebuilds the project for:
- Windows (x86_64)
- Linux (x86_64)
- Android (APK contains both 32-bit and 64-bit ARM code)
- macOS (x86_64)
Ready files are available in the "Artifacts" section. Download them, unpack — this is a ready binary release of your game, for 4 systems above. You don’t need to build yourself, you can just upload these files as "release" on GitHub or anywhere else.

3. Under the hood

The actions execute on GitHub-hosted servers, completely free for open-source projects. They rely on Castle Game Engine Docker image and use the latest CGE "snapshot" revision and latest stable FPC (3.2.2) now. The build is done by executing CGE build tool with proper options. You don’t really need to understand it all — our build.yml just does it for you.

You can customize the way it works in a myriad of ways. See GitHub Actions docs.

4. Taking it further: Make a release

The builds described above (actions' artifacts) will disappear after some time (90 days by default). Also, users need to be signed-in to GitHub to be able to download them. So this is not a complete final solution, yet.

If you want to distribute the builds to users, you should upload them e.g. as "release" on GitHub or anywhere else.

You can automate this too, using GitHub CLI. It is available both in CGE Docker images and in GitHub-hosted servers themselves. You would use it like this to replace files in snapshot release:

gh release --repo MY-ORGANIZATION/MY-PROJECT upload snapshot --clobber \
  *-win64-x86_64.zip \
  *-linux-x86_64.tar.gz \
  *-darwin-x86_64.zip \
  *.apk

Be sure to define environment variable GITHUB_TOKEN to make it work. See GitHub Actions docs.

To improve this documentation just edit this page and create a pull request to cge-www repository.