View as Markdown

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 GitHub, GitLab, or Bitbucket 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 the provider, host, username, and token. The scopes the token needs differ by provider.

GitHub #

  • Provider: GitHub
  • Host: github.com (or your GitHub Enterprise host)
  • Username: your GitHub username
  • Token: a classic PAT with the repo scope, or a fine-grained token with Contents: Read-only permission on the repositories you want to build

Fine-grained tokens have no repo scope. They use per-repository permissions instead, and they also carry read-only access to every public repository, so the repository picker lists far more repositories than you selected. Only repositories the token can actually read will build.

GitLab #

  • Provider: GitLab
  • Host: gitlab.com (or your GitLab Self-Managed host)
  • Username: your GitLab username
  • Token: a PAT with both the read_api and read_repository scopes

Create the token under User Settings > Personal access tokens, selecting the legacy token option. GitLab’s fine-grained tokens use a different permission model that doesn’t offer these scopes.

For what each scope grants, see GitLab’s access token scopes reference.

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 #