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.

For example, you can use it like this to replace files in snapshot release:

steps:
- ...
# Example GitHub Actions step that releases all *.zip, *tar.gz files
# as new files in the "snapshot" release.
- name: Release Artifacts
  if: ${{ github.ref == 'refs/heads/master' }}
  run: gh release --repo MY-ORGANIZATION/MY-PROJECT upload snapshot --clobber *.zip *.tar.gz
  env:
    GH_TOKEN: ${{ github.token }}

See step at the end of this workflow for a working example.

Note

Above example step overwrites the snapshot release files every time it is done, while the release tag stays the same. It works and is useful for snapshot releases. But it is not a normal release setup: "normal" release should be done once, building binaries from the proper tag, and the released files should not change later. Tweak above example as you wish, e.g. to build on specific tag and/or to create a new release every time by gh release create ….

See GitHub Actions docs for details.

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