witchpixels/godot-ci repository overview

⁠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/seanmaxwell/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.