Install Self-Hosted
Get Started on Cloud
BasicsPipelinesActions & ServicesEnvironmentsIntegrationsTargetsTestsDomainsSandboxesSelf-HostedAgents & TunnelsYAML

Custom Build

View as Markdown
  • POST
  • /workspaces
  • /:workspace
  • /projects
  • /:project_name
  • /pipelines
  • /:pipeline_id
  • /actions

Creates a new Custom Build action in the pipeline

Request

REQUIRED SCOPES
EXECUTION_MANAGE
URL PARAMETERS
workspacerequiredstring
The human-readable ID of the workspace

Example: "my-company"

project_namerequiredstring
The human-readable ID of the project

Example: "my-project"

pipeline_idrequiredinteger
The ID of the pipeline

Example: 123

POST PARAMETERS
typerequiredstring enum
The type of the action
Allowed enum:
BUILD
urlread-onlystring
API endpoint to GET this object
html_urlread-onlystring
Web URL to view this object in Buddy.works
after_action_idinteger
The numerical ID of the action, after which this action should be added
namerequiredstring
The name of the action
trigger_timestring enum
Specifies when the action should be executed
Allowed enum:
ON_EVERY_EXECUTION,
ON_SUCCESS,
ON_FAILURE,
ON_BACK_TO_SUCCESS,
ON_WARNING,
ON_WAIT_FOR_APPROVE,
ON_TERMINATE
trigger_conditionsTriggerConditionView[]
The list of trigger conditions to meet so that the action can be triggered
run_nextstring enum
Defines whether the action should run in parallel with the next one
Allowed enum:
WAIT_ON_SUCCESS,
IN_SOFT_PARALLEL,
IN_HARD_PARALLEL
run_only_on_first_failureboolean
Defines whether the action should be executed on each failure. Restricted to and required if the trigger_time is ON_FAILURE
variablesEnvironmentVariableView[]
The list of variables you can use the action
disabledboolean
When set to true the action is disabled. By default it is set to false
timeoutinteger
The timeout in seconds
ignore_errorsboolean
If set to true the execution will proceed, mark action as a warning and jump to the next action. Doesn't apply to deployment actions
retry_countinteger
Number of retries if the action fails
retry_intervalinteger
Delay time between auto retries in seconds
loopstring[]
The list of commands that will be executed in a loop
current_revisionstring
The git revision of the last successful run of the action
permissionsPermissionsView
Access permissions configuration
working_directorystring
The directory in which the pipeline filesystem will be mounted
main_service_namestring
The hostname of the container in which the action is run. The container will be available under this name in the docker network for services
run_as_userstring
All build commands are run as the default user defined in the selected Docker image. Can be set to another username (on the condition that this user exists in the selected image)
versionstring
The version of the package from package registry
docker_image_namerequiredstring
The name of the Docker image
docker_image_tagrequiredstring
The tag of the Docker image
execute_commandsrequiredstring[]
The commands that will be executed
mount_filesystem_disableboolean
If set to true, the filesystem will not be mounted in the container
volume_mappingsstring[]
The path preceding the colon is the filesystem path (the folder from the filesystem to be mounted in the container). The path after the colon is the container path (the path in the container, where this filesystem will be located)
cached_dirsstring[]
The dependencies & directories to be cached and available to every execution in this pipeline
setup_commandsstring[]
The command that will be executed only on the first run
servicesServiceView[]
The list of services attached to the build environment
shellstring enum
The name of the shell that will be used to execute commands
Allowed enum:
SH,
BASH,
POWERSHELL
registrystring
The URL of the Docker registry
insecure_registryboolean
If set to true, the registry will be accessed over HTTP instead of HTTPS
loginstring
The username for the Docker registry
target_stagestring
The target stage of the Dockerfile
passwordstring
The password for the Docker registry
regionstring
The region for the Docker registry (for AWS ECR)
image_locationstring enum
The location of the image used by the action
Allowed enum:
PUBLIC_REGISTRY,
PRIVATE_REGISTRY,
ACTION,
PACKAGE_REGISTRY
use_image_from_actionboolean
If set to true, the image from another action will be used
docker_registrystring enum
The type of registry from which the image is retrieved
Allowed enum:
NONE,
DOCKER_HUB,
AMAZON_ECR,
GOOGLE_GCR,
GOOGLE_ARTIFACT_REGISTRY,
OTHER,
GIT_HUB_CONTAINER_REGISTRY,
PACKAGE_REGISTRY,
DIGITAL_OCEAN_CONTAINER_REGISTRY
docker_build_action_idinteger
The ID of the action from which the Docker image will be used
docker_build_action_namestring
The name of the action from which the Docker image will be used
export_container_pathstring
The path in the container to export
execute_every_commandboolean
If set to true all commands will be executed regardless of the result of the previous command
ignore_image_pull_failuresboolean
If set to true, use cached image on timeouts (only for official images)
reset_entrypointboolean
If set to true, resets the default entrypoint set by the image. Default value: false
usernamestring
The username for authentication
cache_base_imageboolean
If set to true, the cached version of the image is used, instead of being pulled each time
do_not_prune_imagesboolean
If set to true, images will not be pruned after the build
vt_suitestring
The visual tests suite identifier
unit_tests_suitestring
The unit tests suite identifier
unit_tests_pathstring
The path to the unit tests results
integrationDockerIntegrationRef
Docker registry integration (DOCKER_HUB|GOOGLE_SERVICE_ACCOUNT|AMAZON|GIT_HUB|GIT_HUB_ENTERPRISE)
packagestring
The identifier of the package from package registry

Response

RESPONSE BODY
typestring enum
The type of the action
Allowed enum:
BUILD
urlread-onlystring
API endpoint to GET this object
html_urlread-onlystring
Web URL to view this object in Buddy.works
idinteger
The ID of the action
namestring
The name of the action
current_revisionstring
The git revision of the last successful run of the action
trigger_timestring enum
Specifies when the action should be executed
Allowed enum:
ON_EVERY_EXECUTION,
ON_SUCCESS,
ON_FAILURE,
ON_BACK_TO_SUCCESS,
ON_WARNING,
ON_WAIT_FOR_APPROVE,
ON_TERMINATE
trigger_conditionsTriggerConditionView[]
The list of trigger conditions to meet so that the action can be triggered
run_nextstring enum
Defines whether the action should run in parallel with the next one
Allowed enum:
WAIT_ON_SUCCESS,
IN_SOFT_PARALLEL,
IN_HARD_PARALLEL
run_only_on_first_failureboolean
Defines whether the action should be executed on each failure. Restricted to and required if the trigger_time is ON_FAILURE
variablesEnvironmentVariableView[]
The list of variables you can use the action
disabledboolean
When set to true the action is disabled. By default it is set to false
timeoutinteger
The timeout in seconds
ignore_errorsboolean
If set to true the execution will proceed, mark action as a warning and jump to the next action. Doesn't apply to deployment actions
retry_countinteger
Number of retries if the action fails
retry_intervalinteger
Delay time between auto retries in seconds
last_execution_statusstring enum
The status of the last run of the action
Allowed enum:
INPROGRESS,
ENQUEUED,
TERMINATED,
SUCCESSFUL,
FAILED,
INITIAL,
NOT_EXECUTED,
SKIPPED,
TERMINATING,
WAITING_FOR_APPLY,
WAITING_FOR_VARIABLES,
WAITING_FOR_SETTABLE_VARIABLES,
WAITING_FOR_VT_SESSION
pipelineShortPipelineView
Short representation of a pipeline
permissionsPermissionsView
Access permissions configuration
loopstring[]
The list of commands that will be executed in a loop
working_directorystring
The directory in which the pipeline filesystem will be mounted
main_service_namestring
The hostname of the container in which the action is run. The container will be available under this name in the docker network for services
run_as_userstring
All build commands are run as the default user defined in the selected Docker image. Can be set to another username (on the condition that this user exists in the selected image)
versionstring
The version of the package from package registry
docker_image_namestring
The name of the Docker image
docker_image_tagstring
The tag of the Docker image
execute_commandsstring[]
The commands that will be executed
mount_filesystem_disableboolean
If set to true, the filesystem will not be mounted in the container
volume_mappingsstring[]
The path preceding the colon is the filesystem path (the folder from the filesystem to be mounted in the container). The path after the colon is the container path (the path in the container, where this filesystem will be located)
cached_dirsstring[]
The dependencies & directories to be cached and available to every execution in this pipeline
setup_commandsstring[]
The command that will be executed only on the first run
servicesServiceView[]
The list of services attached to the build environment
shellstring enum
The name of the shell that will be used to execute commands
Allowed enum:
SH,
BASH,
POWERSHELL
registrystring
The URL of the Docker registry
insecure_registryboolean
If set to true, the registry will be accessed over HTTP instead of HTTPS
loginstring
The username for the Docker registry
target_stagestring
The target stage of the Dockerfile
passwordstring
The password for the Docker registry
regionstring
The region for the Docker registry (for AWS ECR)
image_locationstring enum
The location of the image used by the action
Allowed enum:
PUBLIC_REGISTRY,
PRIVATE_REGISTRY,
ACTION,
PACKAGE_REGISTRY
docker_registrystring enum
The type of registry from which the image is retrieved
Allowed enum:
NONE,
DOCKER_HUB,
AMAZON_ECR,
GOOGLE_GCR,
GOOGLE_ARTIFACT_REGISTRY,
OTHER,
GIT_HUB_CONTAINER_REGISTRY,
PACKAGE_REGISTRY,
DIGITAL_OCEAN_CONTAINER_REGISTRY
docker_build_action_idinteger
The ID of the action from which the Docker image will be used
docker_build_action_namestring
The name of the action from which the Docker image will be used
export_container_pathstring
The path in the container to export
execute_every_commandboolean
If set to true all commands will be executed regardless of the result of the previous command
ignore_image_pull_failuresboolean
If set to true, use cached image on timeouts (only for official images)
cache_base_imageboolean
If set to true, the cached version of the image is used, instead of being pulled each time
reset_entrypointboolean
If set to true, resets the default entrypoint set by the image. Default value: false
vt_suitestring
The visual tests suite identifier
unit_tests_suitestring
The unit tests suite identifier
unit_tests_pathstring
The path to the unit tests results
integrationIntegrationIdentifierView
The integration used by the action
packagestring
The identifier of the package from package registry

Last modified on Mar 18, 2026

Previous pageEdit actionNext pageGet action

Request example

curl -X POST "https://api.buddy.works/workspaces/:workspace/projects/:project_name/pipelines/:pipeline_id/actions" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Build Android app",
  "type": "BUILD",
  "trigger_time": "ON_EVERY_EXECUTION",
  "docker_image_name": "library/openjdk",
  "docker_image_tag": "8",
  "volume_mappings": [
    "/:/buddy/mount/directory"
  ],
  "execute_commands": [
    "export ANDROID_HOME=/opt/android/sdk",
    "chmod +x gradlew",
    "./gradlew assembleRelease"
  ],
  "setup_commands": [
    "mkdir -p /opt/android/sdk && mkdir .android",
    "cd /opt/android/sdk && curl -o sdk.zip https://dl.google.com/android/repository/sdk-tools-linux-3859397.zip && unzip sdk.zip && rm sdk.zip",
    "yes | /opt/android/sdk/tools/bin/sdkmanager --licenses",
    "/opt/android/sdk/tools/bin/sdkmanager --update",
    "/opt/android/sdk/tools/bin/sdkmanager platform-tools",
    "/opt/android/sdk/tools/bin/sdkmanager tools",
    "/opt/android/sdk/tools/bin/sdkmanager emulator",
    "/opt/android/sdk/tools/bin/sdkmanager \"extras;android;m2repository\"",
    "/opt/android/sdk/tools/bin/sdkmanager \"extras;google;m2repository\"",
    "/opt/android/sdk/tools/bin/sdkmanager \"extras;google;google_play_services\"",
    "/opt/android/sdk/tools/bin/sdkmanager \"build-tools;27.0.3\"",
    "/opt/android/sdk/tools/bin/sdkmanager \"platforms;android-27\""
  ],
  "working_directory": "/buddy/my-repo-dir"
}'
EXAMPLE RESPONSE
{
  "url": "https://api.buddy.works/workspaces/my-workspace/projects/my-project/pipelines/791/actions/1233",
  "html_url": "https://app.buddy.works/my-workspace/my-project/pipelines/pipeline/791/action/1233/edit",
  "id": 1233,
  "name": "mvn package",
  "type": "BUILD",
  "current_revision": "58e239079a2161fec0ba96ed166557157ad3dd79",
  "trigger_time": "ON_EVERY_EXECUTION",
  "run_next": "WAIT_ON_SUCCESS",
  "disabled": false,
  "ignore_errors": false,
  "pipeline": {
    "url": "https://api.buddy.works/workspaces/my-workspace/projects/my-project/pipelines/791",
    "html_url": "https://app.buddy.works/my-workspace/my-project/pipelines/pipeline/791",
    "id": 791,
    "identifier": "build",
    "name": "build",
    "definition_source": "LOCAL",
    "git_config_ref": "NONE",
    "refs": [
      "refs/heads/master"
    ],
    "events": [
      {
        "type": "WEBHOOK"
      }
    ],
    "priority": "NORMAL",
    "disabled": false,
    "last_execution_status": "SUCCESSFUL",
    "last_execution_revision": "58e239079a2161fec0ba96ed166557157ad3dd79",
    "always_from_scratch": false,
    "ignore_fail_on_project_status": false,
    "strict_context": false,
    "no_skip_to_most_recent": false,
    "terminate_stale_runs": false,
    "auto_clear_cache": false,
    "fetch_all_refs": false,
    "fail_on_prepare_env_warning": true,
    "concurrent_pipeline_runs": false,
    "do_not_create_commit_status": false,
    "stale": false,
    "waiting_for_push": false,
    "resources": "DEFAULT",
    "git_changeset_base": "LATEST_RUN",
    "filesystem_changeset_base": "DATE_MODIFIED",
    "cpu": "X64",
    "description_required": false
  },
  "loop": [],
  "docker_image_name": "library/maven",
  "docker_image_tag": "3.9.9",
  "execute_commands": [
    "mvn package"
  ],
  "mount_filesystem_disable": false,
  "volume_mappings": [
    "/:/buddy/my-project"
  ],
  "cached_dirs": [
    "/root/.m2/repository"
  ],
  "shell": "BASH",
  "region": "",
  "image_location": "PUBLIC_REGISTRY",
  "docker_registry": "DOCKER_HUB",
  "execute_every_command": false,
  "ignore_image_pull_failures": false,
  "cache_base_image": true,
  "reset_entrypoint": false,
  "vt_suite": ""
}
STATUS
200 OK