godot-export: a GitHub Action that reads your export presets for you

The action replaces a shell script of export commands

Godot projects can be exported from the command line, but every project ends up writing its own wrapper script: find the right binary, download the matching export templates, run one export command per preset, and remember that the templates must match the engine version exactly. godot-export takes that job over as a GitHub Action.

The description of the project is one line: a workflow action to automatically export your Godot games, supporting standard and Mono builds. It is written in TypeScript, packaged with the usual GitHub Action structure, action.yml at the root with the compiled bundle under dist and the sources under src. The repository also carries examples, including a plain project, a project-mono and a project-godot-4, which is a useful hint about what the author tests against.

The audience is a game team that already has a Godot project and an export presets file, and wants its continuous integration to publish actual binaries. It does not help a team that has never defined a preset, because the action reads the presets rather than defining them.

How the action decides what to build

The mechanism is direct. The action reads export_presets.cfg from the project to determine which builds to make, and whenever the action runs, each of your defined exports runs. The resulting executables can then be optionally attached to a release.

So the source of truth is the Godot project file, not a matrix in the workflow. Add a preset in the editor, commit the file, and the next run builds one more target. Nothing in the action has to be updated for a new platform.

The internals match that design. The runtime dependencies are the GitHub Actions toolkit packages @actions/core, @actions/exec, @actions/io and @actions/cache, plus ini for parsing the preset file and sanitize-filename for the output names. There is no Godot-specific build wrapper or template manager in the dependency list, which is consistent with the action downloading and invoking the engine rather than embedding it.

Output handling is also part of the action, not the workflow. archive_output puts each export into a .zip, and archive_root_folder decides whether the files sit at the root of that archive or under a root folder instead.

Defining a preset that the action can name

Before anything runs in CI, the project needs at least one export preset. The setup instruction is to open Project -> Export in the Godot editor and create a configuration. Then set the file name in the Export Path box, because that is how the action knows how to name your binary. The example given uses win.exe in the Export Path for a Windows export, and executables can be named however you like as long as the extension is appropriate, such as .exe or .x86_64.

That Export Path field is doing more work than it looks. It supplies both the file name and the extension the action uses to recognise a platform, so a preset with a wrong extension produces a broken artefact rather than a clear error.

The workflow side then needs three required inputs. godot_executable_download_url points at the Linux Headless version of Godot you want to use, and the documentation is explicit that exporting fails if you do not use the headless build. godot_export_templates_download_url is the link to the .tpz archive of export templates. relative_project_path is the path to the directory holding project.godot, set to ./ when that file sits at the repository root, and it must not include project.godot itself.

Optional inputs cover the rest: cache reuses the GitHub Actions workflow cache for the templates and the engine binary, export_debug switches to debug mode exports, verbose passes the --verbose flag, and export_as_pack exports the project files as a .pck file.

wine_path exists only for the Windows icon step

One input needs its own explanation because it drags a Windows compatibility layer onto a Linux runner. wine_path is the absolute path to the wine binary, and when it is set, Godot uses it to run rcedit to update Windows exe icons. The documentation points at the setup Windows icons example configuration for the wiring.

So a plain export needs no wine at all, and the icon rewriting is opt-in. That is the right default for most projects, but if your pipeline already needs a custom .ico stamped into the executable, you now need wine installed on the runner and the path passed in, which is a bigger environment change than the rest of the action combined.

A related documentation gap is worth noting. The source project does not state which rcedit build is used, how the icon file is located in the repository, or what happens when wine is missing but wine_path is set. If icon stamping matters to your release, treat that part of the pipeline as something you have to verify yourself rather than assume.

The macOS .zip trap that silently exports your source

There is one failure mode in the setup guidance that deserves more than a footnote, because it does not fail loudly.

For Godot versions before 3.2, the file extension for the macOS export must be anything but .zip. If a macOS preset uses .zip on a Godot version earlier than 3.2, the project source files are exported instead of a macOS application. The documentation links this to a known issue with the Godot command line export, and the author reports working around it by using a .z extension for macOS builds.

The failure mode is that the action itself runs, produces an artefact, and attaches a zip to the release while the contents are your project source rather than an application. Nothing in the workflow output says the export is wrong. Anyone adding a macOS preset to an old project should set the extension deliberately and open the artefact once before shipping it.

Related to this, the Export Path extension is how the action names binaries, so the same field that causes this trap also controls output names across every platform.

Mono support, Godot 3 compatibility and preset path precedence

Three inputs deal with project variants and output placement, and each one is worth understanding before you wire them up.

Mono builds are supported, and the repository includes a project-mono example, so a C# flavoured Godot project is not an unsupported corner. The use_godot_3 boolean switches the action to the Godot 3 executable, and the documentation warns that godot_executable_download_url and godot_export_templates_download_url still need to be configured to download the matching version, which is the usual failure point when engines and templates drift apart.

Output placement has a precedence rule. relative_export_path moves exports to a directory relative to the repository root, and use_preset_export_path instead moves them to the directory defined in export_presets.cfg, resolved relative to relative_project_path. use_preset_export_path is prioritised over relative_export_path and overrides it. Two inputs that both seem to control the same thing, with the documented winner being the preset based one.

archive_root_folder refines the zipped output by putting the exported files under a root folder rather than at the archive root, which matters for players who unzip and run the file directly.

Compared with a hand-written export workflow

The alternative is what most projects start with: a workflow step that downloads the headless engine and templates with curl, then a sequence of godot --export-release commands listed by hand for each preset. The difference in approach is where the list of platforms lives.

In the hand-written version, the platform list appears twice, once in the workflow and once in export_presets.cfg, and the two drift. godot-export keeps it in one place, the Godot project file, so a new target is a new preset. The cost is that the action takes over the engine acquisition step, because godot_executable_download_url and godot_export_templates_download_url are required inputs and the headless build is not optional.

That last point is the real trade-off for self-hosted runners. A pipeline that already pins its own Godot binary, or that exports on a machine with the engine preinstalled, keeps that control with the hand-written script. A pipeline that just wants binaries attached to a GitHub release gets a lot of wiring done for it, including caching the templates and the engine between runs.

Releases, source layout and the MIT licence

The project is MIT licensed, with the LICENSE file at the root, so using the action inside your own CI carries no additional conditions beyond the MIT terms. That is one difference from the maintenance fee model used by some other action authors, and it means there is no separate commercial condition to evaluate here.

On maintenance, the repository is not archived and the last push was on 2026-05-28, with releases v8.0.0 on 2026-05-28, v7.0.0 on 2025-08-22 and v6.0.0 on 2024-10-12. The version numbers are large, which usually signals breaking changes to the action inputs in a GitHub Action, so read the release notes for the version you move to rather than assuming input names are stable.

The source layout is conventional: src holds the TypeScript, dist holds the compiled bundle that the action actually runs, and action.yml describes the interface. The build script in package.json runs the linter, bundles with ncc into dist and removes the stray output directory:

  "scripts": {
    "build": "yarn lint && ncc build ./src/main.ts -o dist && shx rm -rf dist/godot-export",
    "lint": "eslint . --ext .ts"
  },

The test script in package.json is a placeholder that exits with an error saying no test is specified. That last detail is the honest signal about quality: the action has a lint step but no automated test suite in the repository, so behaviour changes are verified by running exports, not by a test run.

Editorial conclusion

Use godot-export if your project already keeps export_presets.cfg under version control and you want a tag to produce downloadable binaries for each platform, since the action derives everything from those presets and needs no per-platform script. Skip it if you build on your own runners outside GitHub Actions, or if your pipeline must control the Godot binary rather than have the action download it, because godot_executable_download_url is required. Before adopting it, confirm that every preset in export_presets.cfg has an Export Path with the right extension, because the action names binaries from that field and will fail on a macOS preset that still uses .zip with Godot older than 3.2.

Frequently asked questions

Official sources

1. firebelley/godot-export on GitHub
2. Issues
3. License: MIT
4. README
5. Releases