New product announcement 🎉 Satori - LiveOps to know your players, deliver features, run experiments and schedule events

Builders are used to clone your custom Runtime Code written in TypeScript, Go, and Lua. A builder represents the “CI” portion of a traditional CI/CD pipeline, deployment is a separate process.

Builders conditionally compile your code against a selected Nakama image and package it into a Docker image. Your 20 most recent builder images are stored at all times.

These images are then available for deployment in your project’s Configuration tab, enabling you to quickly deploy a new image or return to a previous one whenever needed.

From the Builders dashboard you can view and manage your existing CI pipelines (builders) across all projects, and create new builders.

Builders dashboard
Builders dashboard

Each tile on the dashboard provides the details of the corresponding builder:

  • Status: Icon indicates the status of the most recent build process.
  • Builder name: The name of this builder, used to build the resultant image. This cannot be edited once set.
  • Organization: The organization this builder belongs to.
  • Description: The user provided builder description.
  • Repository: The Git repository this builder is linked to.
  • Branch Nakama Version: The Nakama version associated with this builder. Any custom code must use the same Nakama version.

Best practices

Before you start creating builders and deploying new projects, be sure to keep in mind the following:

  • The repository should only contain source code relevant for the server module (i.e. do not place your Unity project there).
  • Beside your custom runtime code files, all other files will be removed from the builder except for the following extensions: .yml, .json, .txt, and .md.


  • Your main.go and mod files must be in the root directory, all others can be in subfolders. The shared object or Dockerfile do not need to be committed.


  • You must include the (single) compiled bundled JavaScript file, not TypeScript.
  • In your Project configuration, set the runtime.js_entrypoint parameter to the location of your bundled JS file (e.g. build/index.js).
  • After pushing any changes to your JS bundle, trigger a new build based on that latest commit.


  • You must include at least one file in the root directory, all other Lua modules can then be included in subfolders.

  • Builders are designed to ignore your Lua test files as follows:

    • All .lua files in a /tests directory
    • Any files named in the format *.test.lua or *_test.lua

Creating builders

You can create a new builder from your Organization or Builders dashboards.

  1. From the dashboard page, select the New Builder tile. The Create your Builder page is displayed.
    Create Builder
    Create Builder
  2. Provide the following details for your new builder:
  • Organization: The Organization this builder will be associated with. Use the drop-down to select from your available Organizations.
  • Builder Name: Enter a unique identifier for your builder. This name will be used for the Docker images created by this builder. Only alphanumeric characters may be used and cannot exceed 20 characters in length.
  • Description: Enter a short description of this builder for easy identification.
  • Nakama Image: Use the drop-down to select the Nakama version this builder will use.
  1. Click Create to finalize your new builder, then proceed to the builder details page to connect it to your desired repository and complete setup.

Connecting to source control

To link your new builder to a desired repository, navigate to the Edit tab in your builder settings:

Select Builder repository
Select Builder repository

Use the drop-down of your source control provider (Git) to enter your connection details, then click Connect.

Managing builders

Select any builder tile from your Organization or Builders dashboards to view its details page and manage the configuration.

There are eight tabs available in the project details page:


Builder into tab
Builder into tab

The Info tab provides all relevant details for this builder, such as the associated repository and Nakama image, and the recent status for this builder.


Builder trigger tab
Builder trigger tab

The Trigger tab enables you to view all recent commits for the linked repository and selected branch, then trigger a new image build using your desired commit SHA.

After selecting Trigger you can view the progress on the Info tab and, when finished, use this new image to update any projects in your organization.


Builder history tab
Builder history tab

The History tab displays all previously triggered builds. Select any listed build to view additional details.


Builder logs tab
Builder logs tab

The Logs tab enables you to view all logs generated by this builder, and filter according to logging level and any desired time period.


Builder edit tab
Builder edit tab

The Edit tab enables you to change available builder settings, such as the linked repository, description, and Nakama image used.


Builder team tab
Builder team tab

The Team tab enables you to view existing team members, manage their permission level for this builder, and add or remove team members from the builder entirely.

Users must have previously registered with Heroic Cloud before they can be added here.


Builder audit tab
Builder audit tab

The Audit tab enables you to view a list of all user actions performed on this builder. You can filter this list according to the Category and Action performed.


Builder deletion tab
Builder deletion tab

The Deletion tab enables you to delete the builder entirely. This is a non-reversible operation that deletes all resources.