GDSuite Docs

Run it in CI

Check every change automatically on GitHub, before it is merged.

CI (continuous integration) is a server that runs your checks on every change you push. When several people work on a game, or when you work from several computers, it makes sure nothing broken reaches the main branch: a pull request shows a red cross until the check and the tests pass.

GDSuite runs the same way in CI as on your computer. If gdsuite check and gdsuite test pass for you, they pass there.

GitHub Actions

Save this as .github/workflows/gdsuite.yml in your project and push it:

name: GDSuite

on:
  push:
    branches: [main]
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Install Godot
        run: |
          curl -fsSL -o godot.zip https://github.com/godotengine/godot-builds/releases/download/4.7-stable/Godot_v4.7-stable_linux.x86_64.zip
          unzip -q godot.zip -d "$RUNNER_TEMP/godot"
          echo "GODOT_EXE=$RUNNER_TEMP/godot/Godot_v4.7-stable_linux.x86_64" >> "$GITHUB_ENV"

      - name: Install GDSuite
        env:
          GH_TOKEN: ${{ github.token }}
        # Add a version after `download`, such as v0.5.0, to stay on it.
        run: |
          gh release download --repo q-rault/gdsuite --pattern '*-x86_64-unknown-linux-musl.tar.gz' --output gdsuite.tar.gz
          mkdir -p "$RUNNER_TEMP/bin"
          tar -xzf gdsuite.tar.gz -C "$RUNNER_TEMP/bin" gdsuite
          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"

      - run: gdsuite check
      - run: gdsuite test

Use the same Godot version as your project: change both 4.7-stable and the file name.

Make code health a gate

In gdsuite check, code health reports but never fails. To fail the build when a critical finding appears, add a step:

      - run: gdsuite health -- health --fail-on critical

On an existing project, fix or accept the current critical findings first (raise the limits in [health.thresholds]), so the build starts green and only new problems turn it red.

Keep the reports

Every command accepts --report json, which saves its result in reports/gdsuite/. gdsuite report ci then combines them into one ci.json, with one entry per step:

      - run: gdsuite check --report json
      - run: gdsuite test --report json
      - run: gdsuite health --report json
      - run: gdsuite report ci
        if: always()
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: gdsuite-reports
          path: reports/

reports/code-health/ holds code health's own report, with the interactive map. The JSON fields are in Reports.

Other CI services

Any Linux, Windows or macOS machine works. The steps are always the same:

  1. install Godot and set GODOT_EXE to its path,
  2. put the gdsuite program on the PATH (a release archive, or cargo install gdsuite),
  3. run gdsuite check and gdsuite test.

If gdsuite.toml gives a tool a source in [tools], run gdsuite setup --output plain first, to install it.