CI/CD on Hathora Cloud

Start by using the Hathora Console to manually set up your game server. The Deploying on Hathora Cloud guide is a great way to get started. Once you have your manual setup working, you're ready to set up CI/CD (Continuous Integration and Continuous Deployment)!

CI/CD is a development practice where developers frequently merge code changes into a central repository. By automating builds and deployments on our platform, you can run tests in a dev environment that simulates the production workspace to ensure that the code behaves as expected. The goal is to find and fix bugs earlier, speeding up game releases for your players.

Hathora CLI for CI/CD

Hathora CLI provides commands that integrate with your CI/CD systems to automate creating builds and deploymnets. Learn how to install and use the Hathora CLI.

Generate a developer token

All CLI commands require authentication with a Hathora developer token. Learn how to generate a developer token.

tip

To not have to pass in a token repeatedly, you can use environment variables or a config file. Learn more about alternative ways to pass in command line flags here.

Commands for CI/CD

Depending on how you want to set up your CI/CD pipelines, we offer commands to create builds, deployments, or both at the same time. A build represents a game server artifact while a deployment represents a process's configurations for the build at runtime.

tip

If you want to use the same configurations as the previous deployment, pass in the --from-latest command-line flag. Only --app-id and --file are required after the first deploy.

Create a build & deployment

hathora deploy \
        --file $FILE_OR_DIRECTORY \
        --build-tag $BUILD_TAG \
        --rooms-per-process $ROOMS_PER_PROCESS \
        --container-port $CONTAINER_PORT \
        --transport-type $TRANSPORT_TYPE \
        --requested-memory-mb $MEMORY_MB \
        --requested-cpu $CPU \
        --env ENV1=$ENV1_VALUE \
        --env ENV2=$ENV2_VALUE \
        --idle-timeout-enabled \
        --app-id $APP_ID \
        --token ${{ secrets.HATHORA_TOKEN }}

Create only a build

hathora build create \
        --file $FILE_PATH \
        --output $OUTPUT_VALUE \
        --token ${{ secrets.HATHORA_TOKEN }}

Create only a deployment

hathora deployment create -b "$buildId" \
        --app-id $APP_ID \
        --rooms-per-process $ROOMS_PER_PROCESS \
        --transport-type $TRANSPORT_TYPE \
        --container-port $CONTAINER_PORT \
        --env ENV1=$ENV1_VALUE \
        --env ENV2=$ENV2_VALUE \
        --token ${{ secrets.HATHORA_TOKEN }}

Integrating with CI systems

Jenkins

For a Jenkins pipeline, add a stage to your pipeline. Install the CLI to create a build and deployment.

stage('Build & Deploy') {
    steps {
        echo 'Installing the Hathora CLI for CI...'
        sh 'curl -s https://raw.githubusercontent.com/hathora/ci/main/install.sh | sh'

        echo 'Creating Hathora build & deployment...'
        sh '''
		      hathora deploy \
		        --file $FILE_OR_DIRECTORY \
		        --build-tag $BUILD_TAG \
		        --rooms-per-process $ROOMS_PER_PROCESS \
		        --container-port $CONTAINER_PORT \
		        --transport-type $TRANSPORT_TYPE \
		        --requested-memory-mb $MEMORY_MB \
		        --requested-cpu $CPU \
		        --env ENV1=$ENV1_VALUE \
		        --env ENV2=$ENV2_VALUE \
		        --idle-timeout-enabled \
		        --app-id $APP_ID \
		        --token $HATHORA_TOKEN
        '''
    }
}

Teamcity

1. Create a new step of type Command Line in your build configuration
2. Add a custom script with contents similar to:

echo 'Installing the Hathora CLI for CI...'
curl -s https://raw.githubusercontent.com/hathora/ci/main/install.sh | sh

echo 'Creating Hathora build and deployment...'
hathora deploy \
  --file $FILE_OR_DIRECTORY \
  --build-tag $BUILD_TAG \
  --rooms-per-process $ROOMS_PER_PROCESS \
  --container-port $CONTAINER_PORT \
  --transport-type $TRANSPORT_TYPE \
  --requested-memory-mb $MEMORY_MB \
  --requested-cpu $CPU \
  --env ENV1=$ENV1_VALUE \
  --env ENV2=$ENV2_VALUE \
  --idle-timeout-enabled \
  --app-id $APP_ID \
  --token $HATHORA_TOKEN

GitHub

Save your HATHORA_TOKEN

You can save your HATHORA_TOKEN in your github repository either through the GitHub web or GitHub CLI.

• GitHub web - Open your repository’s Settings tab, then add a secret named HATHORA_TOKEN under the Secrets section.

• GitHub CLI - run the command below and when prompted paste the HATHORA_TOKEN.

gh secret set HATHORA_TOKEN --repos <username>/<repository-name>

Create a GitHub workflow

Once you have your HATHORA_TOKEN safely stored as a secret in your GitHub repository, proceed with creating a GitHub workflow YAML file in .github/workflows/main.yml:

name: Hathora Deploy
on:
  push:
    branches:
      - main
jobs:
  server:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22.4'
      - run: go install github.com/hathora/ci/hathora@latest
      - run: |
		      hathora deploy \
		        --file $FILE_OR_DIRECTORY \
		        --build-tag $BUILD_TAG \
		        --rooms-per-process $ROOMS_PER_PROCESS \
		        --container-port $CONTAINER_PORT \
		        --transport-type $TRANSPORT_TYPE \
		        --requested-memory-mb $MEMORY_MB \
		        --requested-cpu $CPU \
		        --env ENV1=$ENV1_VALUE \
		        --env ENV2=$ENV2_VALUE \
		        --idle-timeout-enabled \
		        --app-id $APP_ID \
		        --token ${{ secrets.HATHORA_TOKEN }}

Save and push your changes

git add .
git commit -m "Configure auto-deploy through GitHub Actions"
git push