godot-project-template

(support: Godot 4.2.2 stable)

Features:

• GitHub pages auto-deploy
• itch.io auto-delivery
• best practices dir stucture
• Optional
  • git-LFS
  • GUT (Godot Unit Testing)

itch.io and GitHub pages auto deploy step by step

• Sign in to GitHub and Itch.io:

  0. Make sure you are signed in to both github and itch.io
     • https://github.com/login
     • https://itch.io/login

• Create a GitHub Personal Access Token for the project:

  1. Create a Personal Access Token, in your GitHub user account settings, with the following permissions:
     • Contents - Read and Write
     • Metadata - Read-only
     • Pages - Read and Write

• Add personal access token to repo secrets:

  2. add Personal Acess Token as a repository secret with name GH_CREDENTIALS
     • 👉 https://github.com/<your-github-username>/<your-repository-name>/settings/secrets/actions

• Set the read and write permissions for the workflow:

  3. Make sure read and write permissions are set on workflows:
     • 👉 https://github.com/<your-github-username>/<your-repository-name>/settings/actions

• Setup GitHub Pages:

  4. Setup pages for the repository:
     • 👉 https://github.com/<your-github-username>/<your-repository-name>/settings/pages

• Customize the workflow yaml to your project:

  5. Edit the .github/workflows/godot-ci.yml file:
     • 👉 https://github.com/<your-github-username>/<your-repository-name>/blob/main/.github/workflows/godot-ci.yml

     name: "godot-ci export"
     on: 
       push:
         tags:
           - "v*"
     
     env:
     👉  GODOT_VERSION: X.x    #your-godot-version probably "3.5"
     👉  EXPORT_NAME: string   #the-name-of-your-project

     • After the godot-ci workflow completes you will find your game at .github.io/

• Create a butler API token:

  • Generate an API token in itch.io settings

• Add Token to repo Secrets:

  • add the token to yout repository secrets with name BUTLER_CREDENTIALS
    • 👉 https://github.com/<your-github-username>/<your-repository-name>/settings/secrets/actions

• Customize the deploy yaml to your project:

  • Edit .github/workflows/publish-to-itchio.yml
    • 👉 https://github.com/<your-github-username>/<your-repository-name>/blob/main/.github/workflows/publish-to-itchio.yml

    name: "publish to itch.io"
    on:
      release:
      types: [published]
    
    env:
    👉  ITCH_USER: your_itchio_username       #<your-user-name>.itch.io
    👉  ITCH_GAME: the_url_stub_of_your_game  #<your-user-name>.itch.io/<the-url-stub>
    

Triggering the auto-deploy pipeline

GitHub actions will trigger an autodeploy process when it detects a tag starting with "v", For Example: v1.0.1

Commit as normal, push it, tag your commit, then push the tag:###

• Commit your changes as normal, then tag the commit: git tag -a v1.0 -m "summary of release changes"
• Push your changes with the tag: git push origin --tags
• Github Actions will detect the new tag and trigger a new automated build of the game.
• When it is done building it will auto-deploy an HTML5 Version to Github Pages.
• It will release all versions you have configured to build to Itch.io.

GUT and git-LFS

Optionally configure Godot Unit Testing (GUT) and/or git-LFS

git-LFS(optional):

Before you push your first changes make sure you have git-lfs installed on your system: https://git-lfs.github.com/ this template comes with a preconfigured .gitattributes file but feel free to add your own rules. you must change the filename from gitattributes-template to .gitattributes

GUT(optional):

Godot Unit Tests (GUT) is configured by default to run on pull requests to main. Tests are to be placed in res://test in either the res://test/unit or res://test/integration dirs. If you don't want to use tests just don't place tests there. For more information on GUT: https://github.com/bitwes/Gut/wiki/Quick-Start

Directory structure and best practices

• the project/asset directory is where you keep all your game art, sound, etc... It can be tracked by git-lfs
• the project/src directory is where you keep the source-code. It should not be tracked by git-lfs.