godot-ci

Docker image to export Godot Engine games and deploy to GitLab/GitHub Pages and Itch.io using GitLab CI and GitHub Actions.

Docker Hub

https://hub.docker.com/r/barichello/godot-ci/

How To Use

.gitlab-ci.yml and .github/workflows/godot-ci.yml are included in this project as reference.
For live projects, examples and tutorials using this template check the list below:

• Video tutorial by Kyle Luce
• Video tutorial series by David Snopek
• Repository examples: test-project | game-off.
• Test deploys using this tool: GitHub Pages | GitLab Pages | Itch.io.

Mono/C#

To build a Godot project with Mono (C#) enabled, you must do two things for each job:

1. Change the container's image tag from barichello/godot-ci:VERSION to barichello/godot-ci:mono-VERSION in .gitlab-ci.yml (Gitlab) or godot-ci.yml (Github). (e.g. barichello/godot-ci:mono-3.2.1).
2. You will also need to change your "Setup" step's run commands (looks like run: mv /root/.local ...) from ending with ...${GODOT_VERSION}.stable to ending with ...${GODOT_VERSION}.stable.mono. You will need to do this for both directories in the command.

mv /root/.local/share/godot/templates/${GODOT_VERSION}.stable ~/.local/share/godot/templates/${GODOT_VERSION}.stable

becomes:

mv /root/.local/share/godot/templates/${GODOT_VERSION}.stable.mono ~/.local/share/godot/templates/${GODOT_VERSION}.stable.mono

Android

To build a debug release (debug.keystore), use the android_debug job example in the gitlab-ci.yml file.

If you want to export for Android with your own keystore, you can do this with the following steps:

1. Take your generated keystore and convert it to Base64: Linux & macOS: base64 release.keystore -w 0 Windows: certutil -encodehex -f release.keystore encoded.txt 0x40000001
2. Go to GitLab Project > Settings > CI/CD > Variables and copy the Base64-encoded keystore value in a new variable SECRET_RELEASE_KEYSTORE_BASE64 as type variable.
3. Create a second variable SECRET_RELEASE_KEYSTORE_USER as type variable with the alias of your keystore as value.
4. Create a third variable SECRET_RELEASE_KEYSTORE_PASSWORD as type variable with the password of your keystore as value.
5. Use the android job example in the gitlab-ci.yml file.

GDNative/C++

See this repository for automating GDNative C++ compilation, which is based off this repository.

Modules

You have to compile Godot with the modules included first. See this excellent repository by Calinou for automating Godot builds.

After that, you would use the custom build to export your project as usual. See this guide by Greenfox on how to use a custom Godot build for automated exports.

iOS

Not available yet. Automating Xcode projects is doable but not trivial, and macOS runners only recently became available for GitHub actions, so it will happen eventually.

Platforms

Here's a mapping between each supported CI service, the template jobs and a live example.

Environment configuration

First you need to remove unused jobs/stages from the .yml file you are using as a template(.gitlab-ci.yml or .github/workflows/godot-ci.yml).
Then you have to add these environments to a configuration panel depending on the chosen CI and jobs:

• GitHub: https://github.com/<username>/<project-name>/settings/secrets
• GitLab: https://gitlab.com/<username>/<repo-name>/settings/ci_cd

GitHub Pages

Secrets needed for a GitHub Pages deploy via GitLab CI:

Others variables are set automatically by the gitlab-runner, see the documentation for predefined variables.

Itch.io

Deployment to Itch.io is done via Butler.
Secrets needed for a Itch.io deploy via GitLab CI:

Troubleshoot

Problems while exporting

• Check that the export presets file (export_presets.cfg) is committed to version control. In other words, export_presets.cfg must not be in .gitignore.
  • Make sure you don't accidentally commit Android release keystore or Windows codesigning credentials. These credentials cannot be revoked if they are leaked!
• Check that the export names on export_presets.cfg match the ones used in your CI script (case-sensitive). Export preset names that contain spaces must be written within quotes (single or double).
• Check the paths used in your CI script. Some commands may be running in the wrong place if you are keeping the project in a folder (like the test-project template) or not.

Authentication errors with Butler

• If using GitLab, check that the 'protected' tag is disabled in the CI/CD variables panel.

Additional Resources

Greenfox has an excellent repo that is also for automating Godot exports.