Harbormaster build objects work somewhat differently from objects in many other applications. Most application objects can be edited directly using synchronous APIs (like maniphest.edit, differential.revision.edit, and so on).

However, builds require long-running background processing and Habormaster objects have a more complex lifecycle than most other application objects and may spend significant periods of time locked by daemon processes during build execition. A synchronous edit might need to wait an arbitrarily long amount of time for this lock to become available so the edit could be applied.

Additionally, some edits may also require an arbitrarily long amount of time to complete. For example, aborting a build may execute cleanup steps which take minutes (or even hours) to complete.

Since a synchronous API could not guarantee it could return results to the caller in a reasonable amount of time, the edit API for Harbormaster build objects is asynchronous: to update a Harbormaster build or build target, use this API (harbormaster.sendmessage) to send it a message describing an edit you would like to effect or additional information you want to provide. The message will be processed by the daemons once the build or target reaches a suitable state to receive messages.

Select an object to send a message to using the receiver parameter. This API method can send messages to multiple types of objects:

See below for specifics on sending messages to different object types.

You can use this method (harbormaster.sendmessage) to send control commands to Buildables and Builds.

Specify the Build or Buildable to receive the control command by providing its PHID in the receiver parameter.

Sending a control command to a Buildable has the same effect as sending it to each Build for the Buildable. For example, sending a "Pause" message to a Buildable will pause all builds for the Buildable (or at least attempt to).

When sending control commands, the unit and lint parameters of this API method must be omitted. You can not report lint or unit results directly to a Build or Buildable, and can not report them alongside a control command.

More broadly, you can not report build results directly to a Build or Buildable. Instead, report results to a Build Target.

See below for a list of control commands.

You can use this method to send control commands to Buildables and Builds.

This table summarizes which object types may receive control commands:

You can send these commands:

To send a command message, specify the PHID of the object you would like to receive the message using the receiver parameter, and specify the message type using the type parameter.

If you run external builds, you can use this method to publish build results back into Harbormaster after the external system finishes work (or as it makes progress).

To report build status or results, you must send a message to the appropriate Build Target. This table summarizes which object types may receive build status and result messages:

The simplest way to use this method to report build results is to call it once after the build finishes with a pass or fail message. This will record the build result, and continue the next step in the build if the build was waiting for a result.

When you send a status message about a build target, you can optionally include detailed lint or unit results alongside the message. See below for details.

If you want to report intermediate results but a build hasn't completed yet, you can use the work message. This message doesn't have any direct effects, but allows you to send additional data to update the progress of the build target. The target will continue waiting for a completion message, but the UI will update to show the progress which has been made.

When sending a message to a build target to report the status or results of a build, your message must include a type which describes the overall state of the build. For example, use pass to tell Harbormaster that a build target completed successfully.

Supported message types are:

You can report test results when updating the state of a build target. The simplest way to do this is to report all the results alongside a pass or fail message, but you can also send a work message to report intermediate results.

To provide unit test results, pass a list of results in the unit parameter. Each result should be a dictionary with these keys:

The result parameter recognizes these test results:

This is a simple, valid value for the unit parameter. It reports one passing test and one failing test:

[
  {
    "name": "PassingTest",
    "result": "pass"
  },
  {
    "name": "FailingTest",
    "result": "fail"
  }
]

Like unit test results, you can report lint results when updating the state of a build target. The lint parameter should contain results as a list of dictionaries with these keys:

The severity parameter recognizes these severity levels:

This is a simple, valid value for the lint parameter. It reports one error and one warning:

[
  {
    "name": "Syntax Error",
    "code": "EXAMPLE1",
    "severity": "error",
    "path": "path/to/example.c",
    "line": 17,
    "char": 3
  },
  {
    "name": "Not A Haiku",
    "code": "EXAMPLE2",
    "severity": "error",
    "path": "path/to/source.cpp",
    "line": 23,
    "char": 1,
    "description": "This function definition is not a haiku."
  }
]