Starting Forge builds from a script

Everything the dashboard does with a build, a script can do over HTTP. For building on every push you do not need any of this — the GitHub App does it without a token. The API is for the rest: a release script, a build from another CI, a button in your own tools.

The base URL is https://balaurengine.org/api/v1. Every answer is JSON, with the result under data.

A token

Make a personal API token under account settings → API tokens: give it a name and a lifetime (30, 90 or 365 days, or never) and copy what it shows — it is shown once. It starts with gamend_pat_. Put it in your CI's secret store and send it as a header:

export TOKEN=gamend_pat_…
curl -s https://balaurengine.org/api/v1/forge/projects \
  -H "authorization: Bearer $TOKEN"

It acts as you on the API until it expires or you press Revoke. Changing your password or email revokes every token you made before, so a CI job needs a new one after either. A token cannot make another, and it works whether you signed up with a password or with GitHub.

For something interactive, a login works too: POST /api/v1/login with your email and password answers a data.access_token good for 15 minutes.

Projects

curl -s https://balaurengine.org/api/v1/forge/projects \
  -H "authorization: Bearer $TOKEN"

Each project has an id, name, repo_url, default_ref, targets, engine_version and build_options. To register a public repository without the dashboard:

curl -s https://balaurengine.org/api/v1/forge/projects \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"name": "My game", "repo_url": "https://github.com/you/my-game",
       "default_ref": "main", "targets": ["linux-x64", "windows-x64", "web"]}'

A private repository is registered from the dashboard, through the GitHub App.

To change what a project builds — the same fields as its Settings page:

curl -s -X PATCH https://balaurengine.org/api/v1/forge/projects/$PROJECT \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"engine_version": "0.4.1",
       "build_options": {"android_packages": ["apk", "aab"]}}'

Any of name, default_ref, targets, engine_version and build_options may be sent; the repository cannot change. engine_version is latest, nightly or a version. android_packages is apk, aab or both, and a build with both has two android entries, told apart by their variant: "" for the APK, aab for the bundle.

Start a build

curl -s https://balaurengine.org/api/v1/forge/projects/$PROJECT/builds \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"ref": "v1.2.0", "targets": ["windows-x64", "macos-universal"]}'

Every field is optional:

It answers 201 with the build, whose id you follow.

Wait for it

curl -s https://balaurengine.org/api/v1/forge/builds/$BUILD \
  -H "authorization: Bearer $TOKEN"

Poll until data.status is succeeded or failed. Each entry in data.targets has its own status, an error when it failed, and, once it succeeded, artifact_url — a download link — and artifact_bytes.

When it says no