# Builders **URL:** https://heroiclabs.com/docs/heroic-cloud/titles/builders/ **Summary:** Builders are the bridge between your source code and your Nakama deployments, connecting to your Git repository and compiling server code into container images. **Keywords:** builders and repository setup, heroic cloud **Categories:** heroic-cloud, builders, titles --- # 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](https://heroiclabs.com/docs/nakama/) 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](./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](../cicd/). * **Automatically** on every push to your connected repository, via auto-deploy. See [Auto-deploy](../cicd/#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](../cicd/). ## 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](../cicd/) 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](../../access-control/). ## See also * [Repository setup](./repository-setup/) for connecting your Git repository to a builder. * [Set up CI/CD for Nakama](../cicd/) for automating builds and deploys. * [Nakama deployments](../nakama-deployments/) for deploying images to instances.