Skip to main content

CI/CD on Hathora Cloud

Start by using the Hathora Console to manually set up your 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 releases.

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​

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