BuildCommand Protocol

Data Structures

Notice: Type of unstructured data is always string, even a boolean like field. Hence data type is not mentioned in this document for most of fields. Some fields may have it at start of description when it is not a string type.

Build:

A Build contains everything need for running a job defined on Go server. It has 2 parts:

1. A BuildCommand need to be executed
2. BuildCommand execution context and where to to post back data during processing.

Fields:

Name	Description
BuildId	An unique identifier for this Build, server generated
BuildLocator	used in constructing AgentRuntimeInfo, when agent pings or reports status to server
BuildLocatorForDisplay	same with BuildLocator
ConsoleUrl	build console log (output of echo command) should be cached and flushed periodically to this url.
ArtifactUploadBaseUrl	when uploading artifacts, this is base url, the rest part of uploading url is defined in uploadArtifact command
PropertyBaseUrl	similar with ArtifactUploadBaseUrl, used in generateProperty command
BuildCommand	the build command need to be executed.

BuildCommand

Fields:

Name	Description
Name	a string represents command name, should be lowercase characters. (see Constants)
Args	a string to string map, when value is a complex data structure (e.g. array), encode it as JSON string
RunIfConfig	GoCD's runIf configuration, see Constants for all valid values and GoCD document for how it works.
SubCommands	some commands may have sub commands, e.g. compose.
WorkingDirectory	all commands have working directory specified, it is a relative path to agent's working directory
Test	is a BuildCommand, most of time it is "test" command; Test command is a pre-test for running build command it belongs to. If Test command executed and failed, the build command it belongs to should not be executed. However, Test command execution result should not be propagated into existing build command execution context (e.g. should not fail build). Console output of Test command should not be merged into main build console log.
OnCancel	is a BuildCommand. User can define it on server side. When Build is canceled, OnCancel of current executing BuildCommand will be executed. When current BuildCommand is a sub command of another BuildCommand, then OnCancel of that BuildCommand will also be executed. Similar to Test command, OnCancel execution result will be ignored. Notice, console log of OnCancel BuildCommand should be merged into build console log. So that user can observe the OnCancel task execution.

AgentIdentifier

Name	Description
HostName	Agent host name, for display on Go server agent list page
IpAddress	Agent ip address, for display on Go server agent list page
Uuid	identifier of agent

AgentBuildingInfo

Name	Description
BuildingInfo	buildLocatorForDisplay defined in Build
BuildLocator	buildLocator defined in Build

AgentRuntimeInfo

Name	Description
Identifier	AgentIdentifier defined above
BuildingInfo	AgentBuildingInfo defined above
RuntimeStatus	Agent runtime status: Idle or Building. Server side has more status, but Agent only reports these 2
Location	Agent working directory
UsableSpace	total available disk space
OperatingSystemName	OS name
Cookie	When Agent registered on server, server will send a cookie string to agent, this is it
AgentLauncherVersion	Agent launcher version if it had one
ElasticPluginId	Elastic plugin id, when agent is launched by elastic-agents plugin on Go server
ElasticAgentId	Elastic agent id, when agent is launched by elastic-agents plugin on Go server
SupportsBuildCommandProtocol	Always "true", tell server to use BuildCommand protocol in communication

Report

Name	Description
BuildId	Come from Build
Result	Build status
JobState	it is the value of reportCurrentStatus "status" argument, defined by Go server
AgentRuntimeInfo	an AgentRuntimeInfo

Constants

Build Status: "Passed", "Failed" and "Cancelled"

Agent Runtime Status: "Idle", "Building"

RunIfConfig: "any", "passed", and "failed"

BuildCommand Name:

• "compose"
• "cond"
• "and"
• "or"
• "export"
• "test"
• "exec"
• "echo"
• "uploadArtifact"
• "reportCurrentStatus"
• "reportCompleting"
• "mkdirs"
• "cleandir"
• "fail"
• "secret"
• "downloadFile"
• "downloadDir"
• "generateTestReport"
• "generateProperty"

Build Commands

To execute a build command, there are 3 phases:

• Pre-test command execution:
  • 3 pre-tests:
    • If build is canceled, do not execute command, return without error
    • RunIfConfig: if current build status is mismatch with BuildCommand#RunIfConfig, then don't execute and return without error.
    • Test: if a Test command exists, execute the test command in a new context (or session), if test command execution failed, don't execute command and return without error.
• Execute command: the execution details various depending on command, see commands detail in the following section
• Handle OnCancel and Failure
  • If build is canceled, make sure build status is "Canceled" status and trigger OnCancel command if it existed.
  • If build is failed, log error info to console log (so that user can see details), and mark build status to "Failed". The following build commands will continue to be executed depending on RunIfConfig.

Command list:

Name	Args/SubCommands	Execution description
compose	list of BuildCommand	Loop through sub commands and execute them one by one. When sub command report build failure, should continue to execute the rest sub commands.
cond	list of BuildCommand	Like "if {action1} else {action2}" control statement, first command is a test command, then following a command for the case test command is success, you can add multiple pairs, then following with a command to cover last "else" case
or	list of BuildCommand	Execute all commands as test command, pass if any command succeed
and	list of BuildCommand	Execute all commands as test command, pass if all commands succeed
export	Args: name, value and secure	This command sets up environment variables for executing "exec" command. When secure == "true", should mask value with "*******"
test	Args: flag and left; one sub command when flag == "-eq" or "-neq"	Depending on flag, execution is different. Supported flags: -f, -nf, -d, -nd, -eq, -neq. "f" means file; "d" is directory; "eq" is content equal; "n" is not; for example: -f is success when a relative file path given by "left" argument exists. Similarly, -d is success when a relative directory path given by "left" argument exists. "eq" is special, we need execute a command in SubCommands list and comparing the execution result with "left" field value.
exec	Args: command and args	Execute command with given args in a sub process. The args value is a JSON encoded string, after decoded from JSON, the data should be an array of string.
echo	Args: line	output the line value to build console
uploadArtifact	Args: src, dest and ignoreUnmatchError	"ignoreUnmatchError" is designed for the case we don't want to fail the build if we couldn't find any artifacts to upload by "src" argument. "src" and "dest" are user input in Go server, when they defines artifacts for a job. We also need generate checksum for files uploaded to server. If "src" was a directory, then zip the directory and upload the zip file, but checksum should be files in the directory (please checkout Go job checksum file for details of checksum file format). The post url is composed from ArtifactUploadBaseUrl defined in Build with "dest"
reportCurrentStatus	Args: status	send a report message back to server through websocket channel with Report data structure
reportCompleting	None	same with reportCurrentStatus, the Report must include current build status (jobResult)
mkdirs	Args: path	make directory given by "path" argument, the "path" is a relative path
cleandir	Args: path and allowed	Remove all files and directories inside working directory and not in "allowed" list. "allowed" value is a string list (relative file/directory path) and encoded by JSON.
fail	Args: message	fail build with given "message"
secret	Args: value and substitution	Replace "value" in console output from echo command or sub process output of exec command with "substitution", if no "substitution" value, use "*******" instead
downloadFile	Args: src, url, dest, checksumUrl, checksumFile	"src" is source file relative path, "url" is source file url, "dest" is location to store downloaded file; "checksumUrl" and "checksumFile" are generated by uploadArtifact command, you can download it and use it verify downloaded source file. Notice: source file maybe already downloaded, use checksum to verify existing "dest" file
downloadDir	Args: src, url, dest, checksumUrl, checksumFile	similar to downloadFile, except, the "url" is a zip file that zipped src directory, you need unzip them into "dest" directory.
generateTestReport	Args: srcs, uploadPath	"srcs" is what user input when defining test artifacts. Go server will merge all user's test artifacts' source into "srcs". "srcs" is a string list encoded by JSON. To execute this command, we need search in working directory to find all files matching "srcs", then merge all of test reports found into one and generate a HTML report and upload HTML report to "uploadPath" by uploadArtifact command (use "uploadPath" as "dest" argument)
generateProperty	Args: name, src and xpath	"src" is an XML file path related to working directory, use "xpath" to match XML file content and extract value or text content, then post to a url composed PropertyBaseUrl and "name" argument