BuildMaster Documentation

Pipeline JSON Model

  • Last Modified: 2020-01-30

Pipelines are stored as JSON-formatted files. You can edit pipelines in the web interface using the visual or text mode.

Pipeline

A pipeline consists of a sequence of stages, variables, and several other properties and options. The following are the contents of a pipeline's JSON file.

PropertyDescription
Colora string in the format #RRGGBB used to represent the color used in the UI
Descriptiona string to document the pipelines intended usage
EnforceStageSequencea boolean to indicate whether the stage sequence should be enforced (requiring a Force to override), or if any stage can be deployed to at any time
PostDeploymentOptionsan object with the following property/value pairs. Each value is a boolean.
  • CancelReleases: cancel earlier (lower-sequenced) releases that are still active and have not yet been deployed.
  • CreateRelease: creates a new release by incrementing the final part after a release has been deployed.
  • DeployRelease: mark the release and build as deployed once it reaches the final stage.
Variablesan object with property/values representing variable names and values
  • a variable name is a string of no more than fifty characters: numbers (0-9), upper- and lower-case letters (a-Z), dashes (-), spaces ( ), and underscores (_) and must start with a letter, and may not start or end with a dash, underscore, or space; a variable
  • a variable value is a string of any number of characters
Stagesan array of Stage objects

Stage

A stage consists of a gate, variables, pre-deployment steps, targets, post-deployment steps, and several properties and options.

This object is used to describe the Stage property of a Pipeline object.

PropertyDescription
Namea string representing the name of the stage
Descriptiona string to document the stage's intended usage
AutoPromotea boolean indicating whether a deployment to the next stage will automatically occur if the target is next stage's gate is met
TargetExecutionModea string with either Parallel or Sequential
Gatea Gate object
Variablesan object with property/values representing variable names and values
  • a variable name is a string of no more than fifty characters: numbers (0-9), upper- and lower-case letters (a-Z), dashes (-), spaces ( ), and underscores (_) and must start with a letter, and may not start or end with a dash, underscore, or space; a variable
  • a variable value is a string of any number of characters
Targetsan array of Target objects
PreDeploymentStepsan array of strings containing OtterScript strings that are run prior to target evaluation
PostDeploymentStepsan array of objects or strings, representing steps that are run after target execution

Each object has two properties:
  • Script: a string containing an OtterScript string
  • RunOnFail: a boolean indicating if the step should run even if one of the targets failed
Using strings directly in this array is equivalent to an object whose Script is the string itself and RunOnFail: false

Gate

A gate is a mix of manual and automated approval requirements that a build must have before being deployed to a stage, and are used to ensure the quality and acceptability of a build as it passes through the pipeline.

This object is used to describe the Gate property of a Stage object.

PropertyDescription
UserApprovalsan array of objects representing people that must approve deployment into the stage; each object has two properties:
  • Name: a string of the username of the approver
  • Description: a string of what will be displayed on the approvals required and received
GroupApprovalsan array of objects representing people in groups that must approve deployment into the stage; each object has 3 properties:
  • Name: a string of the group name that an approver belongs to
  • Description: a string of what will be displayed on the approvals required and received
  • Count: an integer of how many approvers in that group must approve the build before it's met
AutomatedChecksan AutomatedCheck object
DeploymentWindowsan array of objects representing times in which a deployment may occur
  • Days: an array of strings representing the names of the days of the week (in the current culture) that a deployment StartTime occurs
  • StartTime: a string in a ISO 8601 24-hour time format with an optional time zone offset: hh:mm[:ss.sss±hh:mm]
  • EndTime: a string in a ISO 8601 24-hour time format with an optional time zone offset: hh:mm[:ss.sss±hh:mm]

Target

A target is comprised of a deployment plan, an environment name and a list of servers or roles to be deployed.

This object is expected in the Targets array property on the Stage object.

PropertyDescription
PlanNamea string of the plan name that will be executed at the target
EnvironmentNamea string of the name of the environment that is targeted
RoleNamesan array of strings representing the roles that are targeted
ServerNamesan array of strings representing the names of the servers targeted

Automated Check

An automated check object describes the automated checks that occur in a pipeline stage gate.

This object is expected in the AutomatedChecks property of the Gate object.

PropertyDescription
Issuesan object that represents issue statuses required to allow promotion to this stage; each object has two properties:
  • Closed: a boolean that indicates "all issues must be closed" prior to promotion, default is false
  • Statuses: an array of issue statuses (e.g. "Ready for QA") an issue must be in prior to promotion, omit the property to represent "any status"
Testsa string of the name of the environment that is targeted
Variablesan array of strings representing the roles that are targeted

OtterScript Strings

OtterScript strings are JSON-encoded strings with optional additional header directives that are used by the UI to determine which pre- or post-deployment step types are displayed.

Here are some examples of valid OtterScript strings in JSON:

Send an email...

"##AH:Email\\r\\n\\r\\nSend-Email\\r\\n(\\r\\n    To: user@example.com,\\r\\n    Subject: Hello,\\r\\n    Body: Body text\\r\\n);\\r\\n",

Set stage variable...

"##AH:SetVariable\\r\\n\\r\\nset $TestVariable = TestValue;\\r\\n",

Execute PowerShell...

"##AH:PowerShell\\r\\n\\r\\nPsExec\\r\\n(\\r\\n    Text: write-host \\"Hello from PowerShell\\";\\r\\n);\\r\\n",

Execute custom OtterScript...

"Exec D:\\\\Tools\\\\tool.exe;"

Is this documentation incorrect or incomplete? Help us by contributing!

This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.

Generated from commit ced119d5 on master