Build Server Protocol

For the Build Server controller to work with a game project, two files are required: build_config.json (input) and build_result.json (output).

build_config.json

Defined in the Build/ folder of your game project repository before a build can be ordered. The Build Server controller fetches this file based on the selected game, branch, and revision, and uses it to render the “Order new” UI.

builds

A required list of supported build configurations.

Key	Required	Type	Description
id	Yes	string	Unique identifier for the build configuration
display_name	Yes	string	Human-readable name shown in the UI
builder	Yes	string	File that kickstarts the client builder
pipeline	No	string	Pipeline definition YAML to execute
platform	Yes	string	Target platform (ios, android, kindle)
kind	Yes	string	Build kind (build, bundle, cache, custom)
type	Yes	string	Build type (inhouse, store, beta, qa, upload)
configuration_file	No	string	Configuration file name (e.g. ios_inhouse)
requirements	No	object	Build-specific requirements that override root-level values
hidden	No	boolean	If true, hides this build from the UI

settings

UI elements for customising build parameters when ordering. Each setting is defined with a {setting_name} key (must be snake_case).

Key	Required	Type	Description
display_name	Yes	string	Label shown in the UI
type	Yes	string	Input type (see below)
group	No	string	Groups UI elements together (e.g. “Advanced”, “Settings”)
values	No*	string[]	Options for checkbox, radio, or select types
multi	No	boolean	Enable multi-select (for select/checkbox types)
default	No	any	Default value
required	No	boolean	Must have a value before ordering
hidden	No	boolean	Hidden from UI (useful for API-only settings)

Supported input types:

Type	Description
checkbox	Checkbox (single or multiple with values)
radio	Radio buttons (always requires values)
select	Dropdown (requires values)
number	Numeric input
text	Text input
switch	Toggle (true/false)

requirements

Tools and versions required on the build agent. Can be defined at root level or per-build (build-level overrides root).

"requirements": {
  "unity": "6000.0.23f1"
}

The {requirement} key must match the supported_tools attribute exposed by the build agent.

actions

Post-build actions that can be triggered automatically or manually. See the Actions section below.

build_pipeline

Instructs the agent to checkout a specific branch of the build pipeline.

"build_pipeline": {
  "branch": "v1"
}

Example

{
  "builds": [
    {
      "id": 0,
      "display_name": "iOS (store)",
      "builder": "some_path/ios_magic_build.sh",
      "platform": "ios",
      "kind": "build",
      "type": "store"
    },
    {
      "id": 1,
      "display_name": "Android (store)",
      "builder": "another_path/build.py",
      "pipeline": "Build/Pipeline/definitions/android/store.yml",
      "platform": "android",
      "kind": "build",
      "type": "store",
      "requirements": {
        "sdk": "1.2.3"
      }
    }
  ],
  "settings": {
    "skip_tests": {
      "display_name": "Skip Tests",
      "type": "switch",
      "group": "Settings"
    },
    "precompiler_directives": {
      "display_name": "Precompiler Directives",
      "type": "select",
      "group": "Advanced",
      "multi": true,
      "values": ["enable_cheat", "enable_debug_logs", "disable_skip"]
    }
  },
  "requirements": {
    "unity": "6000.0.23f1"
  },
  "version": 1,
  "build_pipeline": {
    "branch": "v1"
  }
}

build_result.json

Generated by the build process to communicate status back to the controller. It should be updated progressively as the build runs, not just at the end.

Top-level fields

Key	Required	Type	Description
version	Yes	number	Schema version
main_artifact	No	artifact	Downloadable build (used for the download/install button)
steps	Yes	step[]	List of build steps with status
version_name	Yes	string	Resolved marketing version
product_name	No*	string	App title as installed (*required for iOS)
package_name	No*	string	Bundle identifier (*required for iOS)
version_code	No*	string	Bundle version, usually SVN revision (*required for iOS)
commits	No	artifact	Artifact containing the commit file
changelog	No	artifact	Artifact containing the changelog
release_candidate	No	boolean	Whether this build can be uploaded to stores

step

Key	Required	Type	Description
name	Yes	string	Step name
state	Yes	string	pending, running, skipped, failed, or done
start	No	string	Timestamp when the step started
end	No	string	Timestamp when the step ended
log_file	No	artifact	Log file for this step
artifacts	No	artifact[]	Artifacts produced by this step
warnings	No	warning[]	Warnings generated by this step

artifact

Key	Required	Type	Description
file	Yes	string	Path under artifacts/ with extension
group	No	string	Grouping label
size	No	string	File size in bytes
type	No	string	MIME type

warning

Key	Required	Type	Description
message	Yes	string	Description of the warning
level	Yes	string	info, warning, or error

Actions

Actions are defined in the actions array of build_config.json. They trigger HTTP requests either automatically after a successful build or manually from the build detail page.

Action properties

Key	Required	Type	Description
name	Yes	string	Unique identifier
display_name	Yes	string	Button label in the UI
trigger	Yes	enum	automatic (after build succeeds) or manual
hidden	No	boolean	Hide from the UI actions list
available_states	No	string[]	States where the action is available (finished, cancelled, running, queued, failed). Defaults to after success only.
prerequisites	No	object	Key-value filters to match builds (e.g. "releaseCandidate": true)
request	Yes	object	HTTP request with template variables
settings	No	object	Input fields shown in a dialog before triggering

Template variables

Actions support template variables that are replaced at runtime:

• <<build.projectName>>, <<build.buildNumber>>, <<build.branch>>, <<build.revision>>
• <<user.authorization>>
• <<buildAgent._id>>
• <<settings.{setting_name}>>