Create

The documentation applies to models in the new version buddy.v1.1.0 For the REST API to work correctly, you should send the header X-Buddy-Media-Type: buddy.v1.1.0 You can read more about changes here.

Creates a new pipeline in the project.

Required scopes: WORKSPACE, EXECUTION_MANAGE

Resource URL

POST /workspaces/:domain/projects/:project_name/pipelines

URL Parameters

NameTypeDescription
domain
Required		StringThe workspace domain.
project_name
Required		StringThe name ID of the project.

POST Parameters

NameTypeDescription
name
Required		StringThe name of the pipeline.
on
Required		StringThe trigger mode of the pipeline. Can be one of 'CLICK', 'EVENT', 'SCHEDULE'.
refsString[]Set it if 'on' is set to 'CLICK' or 'SCHEDULE'. The list of refs for which the pipeline will be triggered. Automatically set to 'NONE' if not provided.
eventsEvent[]The list of events for which the pipeline will be triggered. Set it if 'on' is set to 'EVENT'.
trigger_conditionsTriggerCondition[]The list of trigger conditions to meet so that the pipeline can be triggered.
always_from_scratchBooleanDefines whether or not to upload everything from scratch on every execution.
auto_clear_cacheBooleanDefines whether or not to automatically clear cache before running the pipeline.
no_skip_to_most_recentBooleanDefines whether or not to skip execution to the most recent execution.
do_not_create_commit_statusBooleanDefines whether or not to omit sending commit statuses to Github or Gitlab upon execution.
start_dateiso 8601 utc dateRequired if the pipeline is set to 'on: SCHEDULE' and no 'cron' is specified. Defines when the pipeline execution should start. Format: 2016-11-18T12:38:16.000Z
delayIntegerRequired if the pipeline is set to 'on: SCHEDULE' and no 'cron' is specified. Defines the intervals in which the pipeline should be executed (in minutes).
cronStringRequired if the pipeline is set to 'on: SCHEDULE' and neither 'start_date' nor 'delay' is specified. The standard CRON expression defining the execution schedule.
pausedBooleanDefines if the recurrent pipeline executions are paused or not. Restricted to 'on: SCHEDULE'.
ignore_fail_on_project_statusBooleanIf set to 'true' the status of a given pipeline will not impact the project status on the dashboard.
execution_message_templateStringThe title of every execution in this pipeline. By default, it is set to '$BUDDY_EXECUTION_REVISION_SUBJECT'.
target_site_urlStringThe URL of the target website.
disabledBooleanSet it, if you want the pipeline to be disabled.
disabled_reasonStringSpecifies the reason for disabling the pipeline.
concurrent_pipeline_runsBooleanDefines whether or not the pipeline can be run concurrently.
fetch_all_refsBooleanWhen the pipeline is run, Buddy fetches only one Git reference to the pipeline filesystem (branch, tag, or pull request). If the option is set to 'true', Buddy will be forced to fetch all Git references.
permissionsPipelinePermissionsDefine to set permissions for the pipeline.
change_set_baseStringDefines the way the changeset for deployments and trigger conditions between subsequent executions in the pipeline will be calculated. Available values: 'LATEST_RUN', 'LATEST_RUN_MATCHING_REF', 'PULL_REQUEST'. By default, it is set to 'LATEST_RUN'.
cache_scope BETAStringDocker cache scope. Available values: 'WORKSPACE', 'PROJECT', PIPELINE'. By default, it is set to 'PIPELINE'.
description_requiredBooleanThe default value is false. If set to true and the user does not provide a description when starting a pipeline, the pipeline won't run.
pause_on_repeated_failuresIntegerPauses the pipeline after n failed pipeline runs. Restricted to pipelines set to 'on: SCHEDULE'. Possible values: 1-100 (the default value is 100).
git_config_refStringInformation where the pipeline configuration should be stores. Available values: NONE, DYNAMIC, FIXED. By default, it's NONE.
git_configPipelineGitConfigSet if git_config_ref = FIXED. Contains information about where the pipeline configuration is stored.

Example

Request

POST https://api.buddy.works/workspaces/buddy/projects/company-website/pipelines

JSON

{
  "name": "Tests",
  "on": "EVENT",
  "events": [
    {
      "type": "PUSH",
      "refs": [
        "refs/heads/master"
      ]
    }
  ],
  "execution_message_template": "test",
  "always_from_scratch": true,
  "auto_clear_cache": true,
  "no_skip_to_most_recent": true,
  "do_not_create_commit_status": true,
  "ignore_fail_on_project_status": true,
  "concurrent_pipeline_runs": true,
  "description_required": true,
  "change_set_base": "LATEST_RUN_MATCHING_REF",
  "permissions": {
    "others": "DENIED",
    "users": [
      {
        "id": 1,
        "access_level": "READ_WRITE"
      }
    ],
    "groups": [
      {
        "id": 1,
        "access_level": "READ_ONLY"
      }
    ]
  }
}

Sample Response

HTTP

Status: 201 Created
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999

JSON

{
  "url": "https://api.buddy.works/workspaces/buddy/projects/company-website/pipelines/2",
  "html_url": "https://app.buddy.works/buddy/company-website/pipelines/pipeline/2",
  "id": 2,
  "name": "Tests",
  "on": "EVENT",
  "events": [
    {
      "type": "PUSH",
      "refs": [
        "refs/heads/master"
      ]
    }
  ],
  "execution_message_template": "test",
  "last_execution_status": "INITIAL",
  "last_execution_revision": null,
  "create_date": "2016-03-29T07:12:30.675Z",
  "always_from_scratch": true,
  "auto_clear_cache": true,
  "no_skip_to_most_recent": true,
  "do_not_create_commit_status": true,
  "ignore_fail_on_project_status": true,
  "concurrent_pipeline_runs": true,
  "description_required": true,
  "change_set_base": "LATEST_RUN_MATCHING_REF",
  "project": {
    "url": "https://api.buddy.works/workspaces/buddy/projects/company-website",
    "html_url": "https://app.buddy.works/buddy/company-website",
    "name": "company-website",
    "display_name": "Company Website",
    "status": "ACTIVE"
  },
  "creator": {
    "url": "https://api.buddy.works/workspaces/buddy/member/1",
    "html_url": "https://app.buddy.works/buddy/profile/1",
    "id": 1,
    "name": "Mike Benson",
    "avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png"
  },
  "actions": [

  ],
  "permissions": {
    "others": "DENIED",
    "users": [
      {
        "id": 2,
        "access_level": "READ_ONLY"
      }
    ],
    "groups": [
      {
        "id": 1,
        "access_level": "READ_ONLY"
      }
    ]
  }
}

Event schema

Here's how to define the event triggering the pipeline:

"on": "EVENT",
"events": [
  {
    "type": "PUSH",
    "refs": [
      "refs/heads/master"
    ]
  }
]

Properties

NameTypeDescription
type
Required		StringThe type of the event. Available values: 'PUSH', 'CREATE_REF', 'DELETE_REF'.
refs
Required		StringThe list of refs for which the pipeline will be triggered in the given event.
tagsStringRuns the pipeline on the runner with a tag that matches at least one of those specified in the array.

Trigger condition schema

You can define trigger conditions in the following way:

{
  "trigger_conditions": [
    {
      "trigger_condition": "VAR_IS",
      "trigger_variable_key": "myVar",
      "trigger_variable_value": "expectedValue"
    },
    {
      "trigger_condition": "ON_CHANGE"
    }
  ]
}

Properties

NameTypeDescription
trigger_conditionStringDefines when the action should be run. Can be one of 'ON_CHANGE', 'ON_CHANGE_AT_PATH', 'VAR_IS', 'VAR_IS_NOT', 'VAR_CONTAINS', 'VAR_NOT_CONTAINS', 'VAR_LESS_THAN', 'VAR_LESS_THAN_OR_EQUAL', 'VAR_GREATER_THAN', 'VAR_GREATER_THAN_OR_EQUAL', 'DAY', 'HOUR', 'TRIGGERING_USER_IS', 'TRIGGERING_USER_IS_NOT', 'TRIGGERING_USER_IS_IN_GROUP', 'TRIGGERING_USER_IS_NOT_IN_GROUP', 'SUCCESS_PIPELINE', 'ACTION_STATUS_IS' or 'ACTION_STATUS_IS_NOT' (last two can only be set in an action).
trigger_condition_pathsString[]Required when 'trigger_condition; is set to 'ON_CHANGE_AT_PATH'.
trigger_variable_keyStringRequired when 'trigger_condition' is set to 'VAR_IS', 'VAR_IS_NOT' or 'VAR_CONTAINS' or 'VAR_NOT_CONTAINS', 'VAR_LESS_THAN', 'VAR_LESS_THAN_OR_EQUAL', 'VAR_GREATER_THAN', 'VAR_GREATER_THAN_OR_EQUAL'. Defines the name of the desired variable.
trigger_variable_valueStringRequired when 'trigger_condition' is set to 'VAR_IS', 'VAR_IS_NOT' or 'VAR_CONTAINS' or 'VAR_NOT_CONTAINS', 'VAR_LESS_THAN', 'VAR_LESS_THAN_OR_EQUAL', 'VAR_GREATER_THAN', 'VAR_GREATER_THAN_OR_EQUAL'. Defines the value of the desired variable which will be compared with its current value.
trigger_hoursInteger[]Available when 'trigger_condition' is set to 'HOUR'. Defines the time – by default running from 1 to 24.
trigger_daysInteger[]Available when 'trigger_condition' is set to 'DAY'. Defines the days running from 1 to 7 where 1 is for Monday.
zone_idStringAvailable when 'trigger_condition' is set to 'DAY' or 'HOUR'. Defines the timezone (by default it is UTC) and takes values from here.
trigger_project_nameStringRequired when 'trigger_condition' is set to 'SUCCESS_PIPELINE'. Defines the name of the project in which the 'trigger_pipeline_name' is.
trigger_pipeline_nameStringRequired when 'trigger_condition' is set to 'SUCCESS_PIPELINE'. Defines the name of the pipeline.
trigger_action_nameStringRequired when 'trigger_condition' is set to 'ACTION_STATUS_IS' or 'ACTION_STATUS_IS_NOT'. Defines the name of the action.
trigger_statusStringRequired when 'trigger_condition' is set to 'ACTION_STATUS_IS' or 'ACTION_STATUS_IS_NOT'. Defines the status that the action should or shouldn't have. Can be one of 'SUCCESSFUL', 'SKIPPED', 'SUPRESSED' or 'FAILED'.
trigger_userStringRequired when 'trigger_condition' is set to 'TRIGGERING_USER_IS' or 'TRIGGERING_USER_IS_NOT'. Defines the email address of the user.
trigger_groupStringRequired when 'trigger_condition' is set to 'TRIGGERING_USER_IS_IN_GROUP' or 'TRIGGERING_USER_IS_NOT_IN_GROUP'. Defines the name of the group.

PipelinePermissions schema

NameTypeDescription
othersStringAccessLevel for the group Others. Can be one of 'DENIED', 'DEFAULT', 'READ_ONLY', 'RUN_ONLY', or 'READ_WRITE'. Default setting is 'DEFAULT' (Project role).
usersUserPermission[]The list of users who will be granted a permission other than the Others group.
groupsGroupPermission[]The group who will be granted a permission other than the Others group.

UserPermission schema

NameTypeDescription
id
Required		IntegerThe user ID.
access_level
Required		StringAccessLevel for a user. Can be one of 'DENIED', 'DEFAULT', 'READ_ONLY', 'RUN_ONLY', or 'READ_WRITE'.

GroupPermission schema

NameTypeDescription
id
Required		IntegerThe group ID.
access_level
Required		StringAccessLevel for a group. Can be one of 'DENIED', 'DEFAULT', 'READ_ONLY', 'RUN_ONLY', or 'READ_WRITE'.

PipelineGitConfig schema

NameTypeDescription
projectStringThe name of the project where the definition will be stored.
branchStringThe branch where the definition will be stored.
pathStringThe path to the file where the definition will be stored.

Last modified on August 23, 2024

Questions?

Not sure how to configure a pipeline for your process? Reach out on the live-chat or contact support

Get Started

Sign up for free and deploy your project in less than 10 minutes.

GitHubEmail