Builders and repository setup

Builders are the bridge between your source code and your Nakama deployments. A builder connects to your Git repository, compiles your custom server code against a specific Nakama version, and produces a container image that you deploy to one or more Nakama instances.

Overview #

Without a builder, you can’t deploy custom code to Heroic Cloud. The workflow is: you write game server logic in your repository, a builder compiles it into a container image, and you deploy that image to a Nakama instance. Builders support GitHub, GitLab, and Bitbucket, and can be triggered manually or programmatically through the API for CI/CD automation.

A single builder can serve multiple Nakama instances and even multiple titles. This makes it the single source of truth for your server binary.

Supported server runtimes #

Nakama supports three runtimes for custom game server logic: Go, TypeScript/JavaScript, and Lua. All three languages 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 #

When creating a builder, you provide a unique name (no spaces or special characters) and select the repository to connect.

Repository structure #

The required repository layout differs by runtime. Don’t include game client code or game asset files in your server repository—the builder only needs your server code.

Go:

  • main.go as your entry point at the repository root.
  • go.mod and go.sum for dependency management.
  • vendor/ directory with vendored dependencies.
  • local.yml for local development configuration (optional, not used by the cloud builder).

TypeScript / JavaScript:

  • Commit your pre-bundled JavaScript (.js) file to your repository. The builder doesn’t compile or bundle TypeScript—this must be done beforehand.
  • Update the JS entry point in your Nakama configuration to point to your bundled .js file.

Lua:

  • At least one Lua file must be present at the root of the repository.

For Nakama + Hiro projects, add a definitions/ directory for Hiro system definitions and a lib/ directory for the Hiro binaries.

For complete examples, see the sample repositories:

Git provider setup #

Heroic Cloud supports GitHub, GitLab, and Bitbucket. Self-hosted instances of any of these platforms are also supported—contact Heroic Labs to configure authentication for custom or self-hosted Git servers.

GitHub #

The Heroic Cloud application needs access to your GitHub organization’s repositories. If you can’t see your repositories, check that the Heroic Cloud application has organization access in your GitHub settings and have an organization admin approve the request if it’s pending.

Authentication is supported via OAuth, SSH keys, or personal access tokens.

GitLab #

Builders support GitLab repositories using OAuth, a Personal Access Token, or a Project Token for authentication.

Bitbucket #

Builders support Bitbucket repositories. Authentication is supported via OAuth, app passwords, or SSH keys.

Incomplete setup #

A builder can’t produce images until a repository is connected. If you create a builder but don’t finish connecting a repository, complete the setup before attempting to trigger builds.

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 CI/CD and deployment automation.

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 CI/CD and deployment automation 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 #