❗ For now this guide only works for people using Guganana's private MinimalUE build (you can request access here). We do have plans on extending this further and giving people the option to create their own versions of MinimalUE.
UnrealPluginCIWithGithubActions is a practical example on using GitHub Actions free tier with UnrealCodeBuilder to automate the compilation of your Code Plugins for the 3 latest Unreal Engine versions + automatically prepare them for distribution on the Unreal Engine Marketplace.
It relies heavily on our other tool, MinimalUE (WIP), to generate a trimmed and compressed version of Unreal Engine that can only compile projects (going from 50GB+ to 150MB on UE 5.1), allowing us to easily manage the engine inside the GitHub Actions environment.
Due to Unreal Engine's EULA, it's not possible to share the minimal versions of the engine publicly — thus, there will be two ways of getting this working for you:
- Creating your own MinimalUE build and hosting it privately (guide to be released in the future)
- Joining our private team, which uses our internal version of MinimalUE build that can only be accessed by GitHub Actions runners. Currently only inviting a limited number of people.
This repository already builds its source code every time we make a commit 😎 — Give it a look!
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': '"Segoe UI","Noto Sans"'}}}%%
graph TB
A(Your Code Plugin<br>repo on Github)
E(Generated Build Artifacts)
subgraph one["Run CompilePlugin.yml available on UnrealCodeBuilder Repo"]
direction LR
C[(MinimalUE<br>Build)]
D(UnrealCodeBuilder<br>Github Action)
Compile(Compile plugin for<br>latest major UE versions)
C -. Used by .- D
D --> Compile
end
A --> one
one --> E
style one fill:#55A6ee, stroke:transparent,color:#fff;
classDef customStyle fill:#fc5454, stroke:#fff, stroke-width:2px,color:white;
class A,C,D,E,Compile customStyle;
%%style A fill:transparent,stroke:#000,stroke-width:2px,margin:10px
This is still an ongoing effort — we hope to make it more widely available with time.
| Feature | Supported |
|---|---|
| Supported for UE versions | 4.27 | 5.0 | 5.1 |
| Compilation for Win64 | ✅ |
| Automatically prepare for Marketplace release | ✅ |
| Compilation tasks run in parallel | ✅ |
| Run tests after compilation | ❌ not yet |
| Compilation for MacOS | ❌ not yet |
| Compilation for Linux | ❌ not yet |
| Generate Precompiled binaries able to be distributed | ❌ not yet |
| Automatically deploy to File Hosting services | ❌ not yet |
To produce the build artifacts, UnrealCodeBuilder workflows requires you to specify additional information about your plugin (i.e. ProductName, Version, ReleaseFormat).
For that you need to recreate the folder and file structure found in .metadata, filling the files with the relevant data for your project.
- .metadata
- friendlyVersion
User-friendly version of your project.
e.g:1.0.2 - productName
Your plugin's name without any spaces.
e.g:MyVeryCoolPlugin - releaseVersionFormat
Dynamically evaluated format string allowing you to inject extra information into your version.
e.g:$env:friendlyVersion($($env:releaseSHA.Substring(0, 7)))would evaluate to1.0.2(abcdefg) - releaseNameFormat
Dynamically evaluated format string used to generate the artifact names.
e.g:$env:productName-$env:releaseVersion@$env:UEVersionwould evaluate toMyVeryCoolPlugin-1.0.2(abcdefg)@5.1
Make sure to always include $env:UEVersion in the string so you can diferentiate the build artifacts for each Unreal version
- friendlyVersion
For advanced users, adding more files into .metadata will turn their names/values into environment variables that can be queried by the "format" metadata files.
If you want to keep it simple, you can just copy the example files.
On this early version, our build tools are programmed to replace specific (hard-coded) snippets of text with the proper information for your release:
ENGINE_VERSION will get replaced with respective target Engine version.
DEV_VERSION_NAME gets replaced by the release version of your plugin. e.g: 1.0.2(abcdefg).
123456789 gets replaced by a unix timestamp of the moment the script is running — useful to fill the 'Version' field.
Here's an example on how we use it
UnrealPluginCIWithGithubActions/EmptyCodePlugin.uplugin
Lines 1 to 26 in 04348c7
With time we plan on moving to a more versatile and less hard-coded approach.
Now you can create your own Github Actions workflow and reference UnrealCodeBuilder's workflows:
On your repository, inside ./.github/workflows/, create your own workflow yaml file which replicates BuildAndGenerateArtifactsForMarketplace.yml:
To make the GitHub runners access our private MinimalUE build, you're required to set up the GUGANANA_BUILD_KEY and UNREALCODEBUILDER_ENGINE_ENDPOINT secrets:
- On your repository page, click on the settings panel.
- Expand the
Secrets and variablesoption on the side panel followed byActions. - Add a new Repository Secret - the secret name should be
GUGANANA_BUILD_KEYwhile the key is the string provided by us. - Create another secret for
UNREALCODEBUILDER_ENGINE_ENDPOINTwith the value provided by us.
You can now go to the Actions Panel to manually trigger a build. You should get the build artifacts for the latest 3 engine versions if it compiles successfuly.
Make sure to download the build artifacts and upload them to your preferred file hosting service so you can generate download links for the Unreal Engine Marketplace.
You're always free to extend your automation further and integrate it with other platforms.
When using UnrealCodeBuilder, we send a single telemetry event containing the repository name & repository owner. This helps us gauge the usage of our tools and know how important they are to the community.
No other data is collected. Your code is safe!