Builders

Builders are the bridge between your source code and your Nakama deployments. Without a builder, you can’t deploy custom code to Heroic Cloud. A builder connects to your Git repository (GitHub, GitLab, or Bitbucket), compiles your server code against a specific Nakama version, and produces a container image that you deploy to one or more Nakama instances. Builders can be triggered manually or programmatically through the API for CI/CD automation.

Supported server runtimes #

Nakama supports three runtimes for custom game server logic: Go, TypeScript/JavaScript, and Lua. All three can run simultaneously within the same deployment — they aren’t mutually exclusive.

See the Nakama documentation for details on writing server modules in each language.

Go #

The builder compiles Go modules into a native binary. Go offers the highest performance and direct access to all Nakama APIs.

TypeScript / JavaScript #

The Heroic Cloud builder looks for a pre-bundled JavaScript (.js) file. Bundle TypeScript outside of Heroic Cloud before committing — the builder doesn’t compile or bundle TypeScript. Use a bundler such as esbuild or webpack to produce a single .js file, then commit that output to your repository.

TypeScript/JavaScript runs inside a sandboxed virtual machine (JSVM). Configure the min and max VM pool settings in your Nakama configuration to control how many VM instances are available to handle concurrent requests. The default pool size is 64. If you need higher concurrency, increase the pool count — each VM instance consumes memory, so scale your Nakama CPU tier accordingly.

Lua #

Lua modules are interpreted at runtime. At least one .lua file must be present at the root of your repository. Like TypeScript/JavaScript, Lua runs inside a sandboxed VM. The same pool sizing considerations apply.

Creating a builder #

Give your builder a unique name (no spaces or special characters), then connect it to a Git repository. Heroic Cloud supports GitHub, GitLab, and Bitbucket via OAuth or a Personal Access Token. A builder can’t produce images until a repository is connected.

See Repository setup for the required repository structure and step-by-step connection instructions.

How builds work #

When a build is triggered, the builder:

  1. Pulls your source code from the connected repository (specific branch and commit).
  2. Compiles it against the specified Nakama version.
  3. Produces a container image tagged with the Nakama version and commit hash.

After the build completes, the image is available for deployment to any Nakama instance in the same organization.

What happens when a build fails? #

A failed build doesn’t affect any running deployments. The failed image isn’t deployed anywhere. Your existing instances continue running the last successfully deployed image. Inspect the build logs to diagnose the issue, fix your code, and trigger a new build.

Triggering builds #

Trigger builds three ways:

  • Manually from the dashboard for ad-hoc builds and initial setup.
  • Programmatically via the Heroic Cloud API using a service user secret. This is the foundation of CI/CD automation. See the CI/CD guide.
  • Automatically on every push to your connected repository, via auto-deploy. See Auto-deploy.

Deploying images #

After a build completes, deploy the resulting image to any Nakama instance. Deployments use a rolling update (no downtime). Images can also be deployed automatically using auto-deploy. See Set up CI/CD for Nakama.

Sharing builders across titles #

Builders can belong to multiple titles simultaneously. This is useful when multiple games share the same server code base. If you later need to diverge the code for different games, create separate builders and repositories.

Auto-deployers #

Auto-deployers connect a builder to one or more Nakama instances, automatically deploying a newly built image when the build completes successfully. This removes the need to manually deploy after every build. Configure auto-deployers from the builder settings. See Set up CI/CD for Nakama for details.

Permissions #

Builder access is controlled by the same layered permission model as other resources. The key permission is Trigger, which controls who can start builds. For CI/CD service users, Trigger is typically the only permission they need. See Access control.

See also #