[opensourcedex]

godot-ci is a free, open source orchestration & scheduling project written in Dockerfile and released under MIT. It has 1,151 GitHub stars, 169 forks and 43 open issues, and was last pushed 13 days ago. On this registry it ranks #91 of 130 tracked projects in Orchestration & Scheduling, with 5 head-to-head comparisons available. It gained 17 stars over the last 30 tracked days.

What is godot-ci?

godot-ci is a Docker image plus ready-made CI templates that export Godot Engine games and deploy them to GitLab Pages, GitHub Pages, or Itch.io, aimed at Godot developers who want automated builds without maintaining their own export toolchain.

What it is

godot-ci is published as the Docker image barichello/godot-ci on Docker Hub, and the repository also ships reference pipeline definitions: .gitlab-ci.yml for GitLab CI and .github/workflows/godot-ci.yml for GitHub Actions. The repository is written as a Dockerfile, licensed under MIT, and sits inside the Godot Engine ecosystem, where it acts as the build and deployment layer between a Godot project and its hosting target. The README points to live test deploys for GitHub Pages, GitLab Pages, and Itch.io, so the templates are exercised against real pipelines rather than described abstractly.

The concrete problem it solves is exported-template plumbing. A Godot project can only be exported headlessly when the matching export templates exist on the machine doing the work, and a clean CI runner has none. The image pre-installs them and a Setup step moves them into place with mv /root/.local/share/godot/export_templates/${GODOT_VERSION}.stable ~/.local/share/godot/export_templates/${GODOT_VERSION}.stable, after which the export jobs run. That replaces the hand-rolled Dockerfile and manual template-fetch script a team would otherwise maintain per project, and it removes the manual upload step to the pages host.

Key capabilities

  • Version-tagged images: barichello/godot-ci:VERSION, with mono-VERSION variants for Mono (C#) projects, for example barichello/godot-ci:mono-3.2.1.
  • Included CI templates for two services: .gitlab-ci.yml (GitLab CI) and .github/workflows/godot-ci.yml (GitHub Actions).
  • Template jobs covering Godot exports, GitHub Pages deployment, GitLab Pages deployment, and Itch.io deployment.
  • Android export support: an android_debug job using debug.keystore, and a release path using a Base64-encoded keystore stored in CI variables SECRET_RELEASE_KEYSTORE_BASE64, SECRET_RELEASE_KEYSTORE_USER, and SECRET_RELEASE_KEYSTORE_PASSWORD.
  • Mono/C# export support by retargeting the Setup step from ${GODOT_VERSION}.stable to ${GODOT_VERSION}.stable.mono in both directories moved.
  • Documented extension points for the cases the image does not cover directly: GDNative/C++ compilation through godot-cpp-ci, custom module builds through Calinou's godot-builds-ci, and custom Godot builds through Greenfox's godot-build-automation.
  • Video tutorials and repository examples linked from the README, including test-project and game-off.

Who uses it and how

  • Godot developers hosting on GitLab who want each push to export the game and publish it to GitLab Pages through the provided job set.
  • Developers on GitHub who use the Godot Actions workflow to export and publish to GitHub Pages.
  • Teams shipping to Itch.io who need a repeatable build-and-upload step rather than a manual butler run from a laptop.
  • Mono/C# projects that switch the image tag and the Setup step path, then reuse the same job definitions.
  • Android projects that store a release keystore and its alias and password as protected CI variables and export signed builds from the pipeline.

Getting started

Pull the image from Docker Hub at https://hub.docker.com/r/barichello/godot-ci/, or copy the included .gitlab-ci.yml or .github/workflows/godot-ci.yml and set its container image to barichello/godot-ci:VERSION for the Godot version in use.

How it compares

Within the Godot automation space, this project occupies the export-and-deploy slot rather than the build-the-engine slot: godot-cpp-ci handles GDNative C++ compilation and is based off this repository, godot-builds-ci compiles Godot with modules included, and godot-build-automation covers using a custom Godot build for automated exports. Teams with C++ bindings, custom modules, or patched engine builds typically combine those with this image instead of replacing it.

When to use it — and when not to

iOS export is not available yet, and the README is explicit that automating Xcode projects is doable but not trivial, so anyone needing iOS builds from CI must look elsewhere for now. Projects that use custom modules need a Godot build compiled with those modules first, which is outside this image's scope. Self-hosters must run a Docker-capable CI runner and manage release secrets themselves as CI variables; there is no bundled database, storage, or SMTP component to operate, and the 43 open issues indicate the pipeline examples still need per-project adjustment.

project readme (upstream, from github) — read inline

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:

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/export_templates/${GODOT_VERSION}.stable ~/.local/share/godot/export_templates/${GODOT_VERSION}.stable

becomes:

mv /root/.local/share/godot/export_templates/${GODOT_VERSION}.stable.mono ~/.local/share/godot/export_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.

CI Template Example
GitLab CI Godot Exports / GitHub Pages / GitLab Pages / Itch.io GitLab CI Pipelines
GitHub Actions Godot Exports GitHub Actions running

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///settings/secrets
  • GitLab: https://gitlab.com///settings/ci_cd

GitHub Pages

Secrets needed for a GitHub Pages deploy via GitLab CI:

Variable Description Example
REMOTE_URL The git remote where the web export will be hosted (in this case GitHub), it should contain your deploy/personal access token https://:@github.com//.git
GIT_EMAIL Git email of the account that will commit to the gh-pages branch. email@example.com
GIT_USERNAME Username of the account that will commit to the gh-pages branch. username

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:

Variable Description Example
ITCHIO_USERNAME Your username on Itch.io, as in your personal page will be at https://.itch.io username
ITCHIO_GAME the name of your game on Itchio, as in your game will be available at https://.itch.io/ game
BUTLER_API_KEY An Itch.io API key is necessary for Butler so that the CI can authenticate on Itch.io on your behalf. Make that API key Masked(GitLab CI) to keep it secret xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Frequently asked questions

Is godot-ci free to use?

godot-ci is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does godot-ci do?

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

What is godot-ci written in?

godot-ci is primarily written in Dockerfile. Its source is publicly available at https://github.com/abarichello/godot-ci, and it has 1,151 GitHub stars.