Tribe of the Accord Game CI - GitHub Actions Workflow

This document provides an overview of the GitHub Actions workflow for the "Tribe of the Accord" game, explaining the purpose and steps of each job within the workflow. This workflow automates the process of testing, tagging, and publishing the game to Itch.io.

Workflow Overview

The workflow is triggered on:

  • Merges to the main branch.
  • Pull requests targeting the main branch (But only runs tests)

The workflow includes three main jobs:

  1. test - Using GUT tests to ensure our project has stability (This is run in PR branches)
  2. tag - To get a snapshot of the game, increment the game version and push a tag (Only done for merges to main)
  3. publish - We publish our game for each supported platform (windows, mac, linux) (Only done for merges to main)

Permissions

The workflow has write permissions for repository contents.

Environment Variables

The workflow sets several environment variables:

  • GODOT_VERSION: The version of Godot to use.
  • EXPORT_NAME: The name of the exported game.
  • SOUNDBANK_REPO_ASSET_URL: URL to fetch assets for Wwise-related assets
  • SOUNDBANK_ASSET: Soundbanks for all platforms
  • WWISE_BINARIES_ASSET: Binaries for all platforms
  • GAME_RELEASE_VERSION: Template version - 'latest'

Jobs

1. Test Job

Purpose: Run tests to ensure code quality before proceeding with tagging and publishing.

Runs on: ubuntu-latest

Container: Uses barichello/smks-ci:3.6 Docker image.

Steps:

  1. Checkout Repository: Checks out the repository using actions/checkout@v2.
  2. Print Directory Structure: Prints the directory structure for debugging purposes.
  3. Check Test Files: Runs a script to check for missing test files (tools/bin/check-missing-tests.sh). (For visibility and not blocking)
  4. Run Tests: Executes the tests using the Godot command line.

2. Tag Job

Purpose: Update the game version and tag the new version.

Dependencies: Requires the test job to succeed.

Runs on: ubuntu-latest

Conditions: Runs only on the main branch (github.ref == 'refs/heads/main').

Steps:

  1. Checkout Repository: Checks out the repository at the main branch with a personal access token for authentication.
  2. Update Version: Increments the patch version number in the project.godot file.
  3. Commit and Tag: Commits the updated project.godot file and tags the new version. Pushes the changes and the new tag to the repository.

3. Publish Job

Purpose: Build the game for different platforms and publish the builds to itch.io.

Dependencies: Requires the tag job to succeed.

Runs on: ubuntu-latest

Container: Uses barichello/smks-ci:6 Docker image.

Steps:

  1. Checkout Repository: Checks out the repository using actions/checkout@v2.
  2. Install curl: Installs curl for downloading dependencies.
  3. Install Butler: Installs butler, a tool for uploading builds to itch.io. (Moved up because if itch goes down, we don't build all the platform games or download big files).
  4. Download Wwise Binaries: Downloads and unzips Wwise binaries.
  5. Download Soundbanks: Downloads and unzips soundbanks for each platform (debug and release versions).
  6. Setup Godot Templates: Sets up Godot export templates. (These are used to generate the games)
  7. Mac Build: Builds the game for macOS.
  8. Windows Build: Builds the game for Windows.
  9. Linux Build: Builds the game for Linux.
  10. Deploy Mac to itch.io: Deploys the macOS build to itch.io using the butler tool.
  11. Deploy Windows to itch.io: Deploys the Windows build to itch.io using the butler tool.
  12. Deploy Linux to itch.io: Deploys the Linux build to itch.io using the butler tool.
  13. Get Release Commit: Grab the latest commit message (excluding the last commit that upgrades the project.godot version)
  14. Post Discord Game Release: We want to notify the teams that a new game version has been released

Secrets

The workflow uses the following secrets for authentication:

  • PAT_TOKEN: Personal Access Token for pushing commits and tags.
  • BUTLER_API_KEY: API key for uploading builds to itch.io.
  • ITCHIO_USERNAME: itch.io username.
  • ITCHIO_GAME: itch.io game identifier.
  • ITCHIO_PASSWORD: itch.io game password. Needed to access restricted itch page and enter password.

Conclusion

This GitHub Actions workflow automates the process of testing, tagging, and publishing the "Tribe of the Accord" game. By following the steps outlined in each job, the workflow ensures that the game is thoroughly tested, versioned correctly, and published to itch.io with minimal manual intervention.