Get branches and parameters and run a build

You can use the Build Management API to get information about available branches and parameters that you can use to run a build.

All sample requests in this guide include the following path parameters:

Parameter name	Description
`tenantId`	Tenant ID.
`starId`	ID of a star.
`applicationName`	Name of an application.
`buildType`	Type of builds that are available for a given application. You can use the following values for respective applications: - Extension Layer (EA): `Alpine_Build`, `Alpine_Install`, `Alpine_ServerTests` - InsuranceSuite: `IS_Test`, `IS_StaticAnalysis`, `IS_UpdatabilityCheck`, `IS_SmokeTests`, `IS_BehaviorTests`, `IS_Build`, `IS_ApiTests`, `IS_Dockerize`, `IS_Sentinel`, `IS_VerifyBlueGreen`, `IS_BuildSolr`, `IS_DockerizeSolr`, `IS_SecureTokenVerification` - Guidewire Testing Framework: `GT_LoadTests`, `GT_FrameworkUiTests`, `GT_ApiTests`, `GT_FrameworkTests` - Jutro Digital Platform: `Jutro_Test`, `Jutro_BuildAndDockerize`, `Jutro_UpgradeJutroCore`, `Jutro_WebVitals`, `Jutro_E2ETests` - EnterpriseEngage: `Portals_Test`, `Portals_Build`, `Portals_Deploy`, `Portals_Undeploy` - Shared Packages: `Shared_CodeStandardsVerifier`, `Shared_Publish`, `Shared_Test`, `Shared_UpgradeJutro`

To run a build, you need the following information:

What branches you can use for a given build type.
What parameters you can use for a given build type.

Get all the available branches

To get a list of all the available branches for a given build type, send the following GET request:

curl -X 'GET' \
  '{baseURL}/api/v1/tenants/{tenantId}/stars/{starId}/applications/{applicationName}/build-types/{buildType}/branches' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

You can use the status parameter to choose which branches you want to check. The status parameter can take the following values:

ACTIVE
ANY

If you don't provide any value for the status parameter, only active branches are returned by default.

curl -X 'GET' \
  '{baseURL}/api/v1/tenants/{tenantId}/stars/{starId}/applications{applicationName}/build-types/{buildType}/branches?status=ACTIVE' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

A response contains a JSON object with a list of active branches available for a given build type.

Example response
{
  "branches": [
    {
      "name": "main",
      "default": true
    },
    {
      "name": "develop",
      "default": false
    }
  ]
}

Get all the available parameters

To get a list of all the available parameters for a given build type, send the following GET request:

curl -X 'GET' \
  '{baseURL}/api/v1/tenants/{tenantId}/stars/{starId}/applications/{applicationName}/build-types/{buildType}/parameters' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

A response contains a JSON object with a list of parameters available for a given build type.

Example response
{
  "parameters": [
    {
      "type": "TEXT",
      "name": "api_test_suite",
      "displayName": "API test suite name",
      "readOnly": false,
      "defaultValue": "TestSuite",
      "validation": {
        "mode": "REGEX",
        "regex": "[a-zA-Z0-9-_/]*",
        "message": "The name must consist of lowercase and uppercase letters, digits, and special characters: /, -, _"
      }
    },
    {
      "type": "PASSWORD",
      "name": "user_password",
      "displayName": "Password",
      "description": "User password parameter.",
      "readOnly": false
    },
    {
      "type": "SELECT",
      "name": "selection_parameter",
      "displayName": "Selection parameter",
      "description": null,
      "readOnly": false,
      "defaultValue": [],
      "allowMultipleOptions": true,
      "options": [
        {
          "value": "selected_value",
          "displayName": "Selected value"
        }
      ]
    }
  ]
}

Parameter types

There are three types of parameters:

TEXT
PASSWORD
SELECT

Text

The TEXT parameter type displays the defaultValue parameter in the response. If you don't specify a parameter value during the build execution, the default value will be used in a build.

Note:

The default value is used only when it meets the validation requirements. Otherwise, you need to provide a valid parameter value.

Each TEXT parameter type has its own validation that is required to pass the build. Check a validation requirement before running a build with a given parameter. Types of validation include:

NONE which means that no validation is required.
NOT_EMPTY which means that the parameter value can't be an empty string.
REGEX which means that the parameter value needs to match regex defined in the parameter definition.

The test_suites parameter of a TEXT type has a default value:

Example response
{
  "type": "TEXT",
  "name": "test_suites",
  "displayName": "test_suites",
  "description": "Used test suites. If not set, suites will be selected automatically based on the configuration.",
  "readOnly": false,
  "defaultValue": "",
  "validation": {
    "mode": "REGEX",
    "regex": "(?:[a-zA-Z0-9_]+(?:[.][a-zA-Z0-9_]+)*(?:,[a-zA-Z0-9_]+(?:[.][a-zA-Z0-9_]+)*)*)?",
    "message": null
  }
}

In the POST endpoint for executing a build, you can use your chosen value for the test_suites parameter to run a build for IS_Test:

curl -X 'POST' \
  '{baseURL}/api/v1/tenants/{tenantId}/stars/{starId}/applications/{applicationName}/build-types/{IS_Test}/builds' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'
  -d '{
    "branch": "develop",
    "parameters": [
      {
        "type": "TEXT",
        "name": "test_suites",
        "value": "com.guidewire.test.ExampleSuite"
      }
    ]
  }'

As a result, a build for IS_Test will be executed with the test_suites parameter set to the com.guidewire.test.ExampleSuite value.

Password

The value of the PASSWORD parameter type is similar to values provided for the TEXT parameter type.

When using the PASSWORD parameter type in the POST endpoint for executing a build, you need to provide the parameter type, name, and value.

curl -X 'POST' \
  '{baseURL}/api/v1/tenants/{tenantId}/stars/{starId}/applications/{applicationName}/build-types/{buildType}/builds' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'
  -d '{
    "branch": "develop",
    "parameters": [
      {
        "type": "PASSWORD",
        "name": "password",
        "value": "PasswordExample"
      }
    ]
  }'

Select

The SELECT parameter type displays the following parameters:

defaultValue

The defaultValue parameter displays the default selected values. These default values will be used in a build if you don't specify a parameter value during the build execution.

Note:
The default value is used only when it meets the validation requirements. Otherwise, you need to provide a valid parameter value.
allowMultipleOptions

The allowMultipleOptions parameter describes whether multiple options should be allowed. If set to true, an empty list of selected values is accepted. If set to false, only one option must be selected.
options

The options parameter contains a list of available options with their details, such as value and displayName. When you use options, all the selected values must be from among the allowed options defined in the parameter definition.

The SELECT paramerer type can have multiple default values. You can select which values should be included when running a build. For example, you can select a few values for include_apps:

Example response
{
  "parameters": [
    {
      "type": "SELECT",
      "name": "include_apps",
      "displayName": "Include Digital applications",
      "description": "Digital Applications Names (names of the folder inside 'applications')",
      "readOnly": false,
      "defaultValue": [
        "account-management",
        "account-management-claims",
        "producer-engage",
        "producer-engage-claims",
        "quote-and-buy",
        "service-rep-engage",
        "vendor-engage"
      ],
      "allowMultipleOptions": true,
      "options": [
        {
          "value": "account-management",
          "displayName": "account-management"
        },
        {
          "value": "account-management-claims",
          "displayName": "account-management-claims"
        },
        {
          "value": "producer-engage",
          "displayName": "producer-engage"
        },
        {
          "value": "producer-engage-claims",
          "displayName": "producer-engage-claims"
        },
        {
          "value": "quote-and-buy",
          "displayName": "quote-and-buy"
        },
        {
          "value": "service-rep-engage",
          "displayName": "service-rep-engage"
        },
        {
          "value": "vendor-engage",
          "displayName": "vendor-engage"
        }
      ]
    }
  ]
}

When running a build, you can choose for which applications you want this build to run. For example, you can select producer-engage and quote-and-buy. Then in the POST endpoint for executing a build, you can run Portals_Test for only the two selected applications:

curl -X 'POST' \
  '{baseURL}/api/v1/tenants/{tenantId}/stars/{starId}/applications/{applicationName}/build-types/{buildType}/builds' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'
  -d '{
    "branch": "develop",
    "parameters": [
      {
        "type": "SELECT",
        "name": "include_apps",
        "selectedValues": ["producer-engage", "quote-and-buy"]
      }
    ]
  }'

As a result, the build for Portals_Test will be executed for the following two applications: "producer-engage" and "quote-and-buy".

Run a build

You can run a build for a specific branch and selected parameters. Before running a build, check what rules apply when you fill in a build configuration.

To run a build, send the following POST request:

curl -X 'POST' \
  '{baseURL}/api/v1/tenants/{tenantId}/stars/{starId}/applications{applicationName}/build-types/{buildType}/builds' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'
  -d '{body}'

Where in {body}, you can provide a branch, comment, tags, and parameters. You don't need to provide all the information as some of them are optional.

For example, you can send the POST request only with a specific branch and parameter:

curl -X 'POST' \
  '{baseURL}/api/v1/tenants/{tenantId}/stars/{starId}/applications/{applicationName}/build-types/{buildType}/builds' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'
  -d '{
    "branch": "develop",
    "parameters": [
      {
        "type": "TEXT",
        "name": "test_suites",
        "value": "com.guidewire.test.ExampleSuite"
      }
    ]
  }'

A response contains a JSON object with a list of the build details:

Example response
{
  "id": 1,
  "application": {
    "name": "ContactManager",
    "type": "ContactManager"
  },
  "buildType": "IS_Test",
  "number": null,
  "status": "QUEUED",
  "statusMessage": null,
  "branch": "develop",
  "queuedDate": "2024-12-02T13:39:41Z",
  "startDate": "2024-12-02T13:43:41Z",
  "finishDate": "2024-12-02T13:48:35Z",
  "triggered": {
    "type": "user",
    "username": "jdoe",
    "date": "2024-12-02T13:39:41Z"
  },
  "comment": "Build started from build-management-service",
  "revisions": [
    {
      "vcsBranchName": "develop",
      "version": "b136fe9c9e4a5242c59cb2ea846e4ba28c94759e"
    }
  ],
  "statistics": {
    "queuedDurationMillis": 185,
    "buildDurationMillis": 3250
  },
  "tags": ["e2e-test"],
  "cancellationInfo": null
}

You can use the build ID to check the status of the build or to cancel the build.

Rules for build execution

The following rules apply when you fill in information for build execution:

A branch is optional.

If you don't specify a branch while executing a build, the default branch will be used.
A comment and tags are optional.

After running a build, the following comment is automatically added to the response: Build started from build-management-service. If you provided your comment in the request body, it will be added after the automatic comment from Build Management.
For parameters:
- The allowed parameter names and types are from the list of parameter definitions for the used build type.
- You can't set parameters defined as read-only.
- If you don't provide a parameter value, the default value from its definition is used.
  
  The default value is used only when it meets the validation requirements. Otherwise, you need to provide a valid parameter value.
- The provided parameter value must meet the required validation rules and its behavior depends on the parameter type. For details, see Parameter types.

Get all the available branches​

Get all the available parameters​

Parameter types​

Text​

Password​

Select​

Run a build​

Rules for build execution​

Get all the available branches

Get all the available parameters

Parameter types

Text

Password

Select

Run a build

Rules for build execution