How to set up your repository for Heroic Cloud

By the end of this guide, you’ll have a Git repository structured correctly for your chosen runtime and connected to a Heroic Cloud builder.

Prerequisites #

  • A Heroic Cloud organization with at least one title.
  • A repository on GitHub, GitLab, or Bitbucket containing your Nakama server code.

Step 1: Structure your repository #

The required 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 — do this beforehand using a bundler such as esbuild or webpack.
  • 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:

Step 2: Create a builder #

In the Heroic Cloud dashboard, navigate to your title and create a new builder. Provide a unique name (no spaces or special characters). You’ll connect the repository in the next step.

Step 3: Connect your repository #

Heroic Cloud supports GitHub, GitLab, and Bitbucket. Self-hosted instances are also supported — contact Heroic Labs (support@heroiclabs.com) to configure authentication for custom or self-hosted Git servers.

Connect your repository using one of two methods:

  • OAuth — Authenticate with your provider account, then select a repository. Works with GitHub, GitLab, and Bitbucket.
  • Personal Access Token (PAT) — Enter your provider, host name, username, and a PAT manually. Works with GitHub and GitLab only.

Connect via OAuth #

Select your provider and complete the standard OAuth flow. Heroic Cloud gets access to your personal repositories and any organization repositories the Heroic Labs GitHub App has been granted access to.

If the app isn’t installed in your organization yet, the OAuth flow includes a button to request access — an organization admin will need to approve it. Once approved, the app handles all repository access for the builder.

If your organization’s repositories don’t appear in the dropdown after authenticating, grant the Heroic Labs OAuth app access to your organization:

  1. Go to GitHub > Settings > Applications > Authorized OAuth Apps.
  2. Select Heroic Cloud.
  3. Under Organization access, grant access to your organization.

The repository dropdown will update once access is granted.

Connect via PAT #

Select the PAT option and fill in:

  • Provider: GitHub
  • Host: github.com (or your GitHub Enterprise host)
  • Username: your GitHub username
  • Token: a classic or fine-grained PAT with repo scope

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.

Next steps #