Skip to main content

CI/CD on Hathora Cloud

Once you have manual deploys working, you should set up Continuous Integration to automate the deploy process. We will walk through an example for setting up CI/CD using Github Actions, but the general principles and commands apply to other CI systems as well.

tip

We recommend only setting up CI/CD once you already have a manual version working. If it's your first time deploying, use the Hathora Console.

Install the Hathora CLI​

You can either use npm or yarn to install the Hathora CLI.

npm i -g @hathora/cli
yarn global add @hathora/cli

Generate a Hathora developer token​

All CI/CD API calls require authentication with a Hathora developer token. Learn how to generate a developer token.

Save your HATHORA_TOKEN​

You an 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 YAML file​

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
      - run: npm install -g hathora
      - run: hathora-cloud deploy --appId $APP_ID --file $FILE_PATH --roomsPerProcess $ROOMS_PER_PROCESS --planName $PLAN_NAME --transportType $TRANSPORT_TYPE --containerPort $CONTAINER_PORT --env $ENV_VARIABLE --token ${{ secrets.HATHORA_TOKEN }}

Let's go through each line​

  • name: Hathora Deploy: this is the Workflow name
  • on: specifies when the Workflow will kickoff
    • push: when a changed is pushed it will kickoff the Workflow
    • branches: specifies which branches will kick off the Workflow
    • main: when a change is pushed to main it will kick off the Workflow
  • jobs: list of jobs to run for the workflow
    • uses: pre-made GitHub Action. It allows checking out of your repository into the virtual machine spun up for the job
    • run: npm install -g hathora: install the Hathora CLI to run the deploy command
    • hathora-cloud deploy --appId $APP_ID --file $FILE_PATH --roomsPerProcess $ROOMS_PER_PROCESS --planName "$PLAN_NAME" --transportType "$TRANSPORT_TYPE" --containerPort $CONTAINER_PORT --env "[{"name": "$ENV_NAME", "value": "$ENV_VALUE"}" --token ${{ secrets.HATHORA_TOKEN }}
      • appId: system generated unique identifier for an application
      • file: path to the tgz archive to deploy
      • roomsPerProcess: governs how many rooms can be scheduled in a process
      • planName: a plan defines how much CPU and memory is required to run an instance of your game server [choices: "tiny", "small", "medium", "large"]
      • transportType: specifies the underlying communication protocol to the exposed port [choices: "tcp", "udp", "tls"]
      • containerPort: port the container listens on
      • env: JSON stringified version of env variables array (name and value)
      • token: Hathora developer token (required only for CI environments)
tip

Only the appId and file are required after the first deploy. Everything else will automatically default to latest deployment configurations.

Save and push your changes​

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