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

Name	Type	Description
domain `Required`	String	The workspace domain.
project_name `Required`	String	The name ID of the project.

POST Parameters

Name	Type	Description
name `Required`	String	The name of the pipeline.
on `Required`	String	The trigger mode of the pipeline. Can be one of `CLICK`, `EVENT`, `SCHEDULE`.
refs	String[]	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.
events	Event[]	The list of events for which the pipeline will be triggered. Set it if `on` is set to `EVENT`.
trigger_conditions	TriggerCondition[]	The list of trigger conditions to meet so that the pipeline can be triggered.
always_from_scratch	Boolean	Defines whether or not to upload everything from scratch on every execution.
auto_clear_cache	Boolean	Defines whether or not to automatically clear cache before running the pipeline .
no_skip_to_most_recent	Boolean	Defines whether or not to skip execution to the most recent execution.
do_not_create_commit_status	Boolean	Defines whether or not to omit sending commit statuses to Github or Gitlab upon execution.
start_date	iso 8601 utc date	Required 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
delay	Integer	Required 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).
cron	String	Required if the pipeline is set to `on: SCHEDULE` and neither `start_date` nor `delay` is specified. The standard CRON expression defining the execution schedule.
paused	Boolean	Defines if the recurrent pipeline executions are paused or not. Restricted to `on: SCHEDULE`.
ignore_fail_on_project_status	Boolean	If set to `true` the status of a given pipeline will not impact the project status on the dashboard.
execution_message_template	String	The title of every execution in this pipeline. By default it is set to `$BUDDY_EXECUTION_REVISION_SUBJECT`.
worker_assignment	String	Defines the worker assignment method. Can be one of `FIXED` or `TAGS`. Only for Buddy On-Premises. Read here for more details.
worker	String	Defines the worker on which the pipeline runs when `worker_assignment` is set to `FIXED`. Only for Buddy On-Premises.
target_site_url	String	The URL of the target website.
disabled	Boolean	Set it, if you want the pipeline to be disabled
disabled_reason	String	Specify the reason for disabling the pipeline

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
}

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,
  "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": []
}

Event schema

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

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

Properties

Name	Type	Description
type `Required`	String	The type of the event. Available values: `PUSH`, `CREATE_REF`, `DELETE_REF`.
refs `Required`	String[]	The list of refs for which the pipeline will be triggered in the given event.

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

Name	Type	Description
trigger_condition	String	Defines when the build action should be run. Can be one of `ALWAYS`, `ON_CHANGE`, `ON_CHANGE_AT_PATH`, `VAR_IS`, `VAR_IS_NOT`, `VAR_CONTAINS`, `VAR_NOT_CONTAINS`, `DATETIME` or `SUCCESS_PIPELINE`. Can't be used in deployment actions.
trigger_condition_paths	String[]	Required when `trigger_condition` is set to `ON_CHANGE_AT_PATH`.
trigger_variable_key	String	Required when `trigger_condition` is set to `VAR_IS`, `VAR_IS_NOT` or `VAR_CONTAINS` or `VAR_NOT_CONTAINS`. Defines the name of the desired variable.
trigger_variable_value	String	Required when `trigger_condition` is set to `VAR_IS`, `VAR_IS_NOT` or `VAR_CONTAINS` or `VAR_NOT_CONTAINS`. Defines the value of the desired variable which will be compared with its current value.
trigger_hours	Integer[]	Available when `trigger_condition` is set to `DATETIME`. Defines the time – by default running from 1 to 24.
trigger_days	Integer[]	Available when `trigger_condition` is set to `DATETIME`. Defines the days running from 1 to 7 where 1 is for Monday.
zone_id	String	Available when `trigger_condition` is set to `DATETIME`. Defines the timezone (by default it is UTC) and takes values from here.
trigger_project_name	String	Required when `trigger_condition` is set to `SUCCESS_PIPELINE`. Defines the name of the project in which the `trigger_pipeline_name` is.
trigger_pipeline_name	String	Required when `trigger_condition` is set to `SUCCESS_PIPELINE`. Defines the name of the pipeline.

Worker assignment schema

Assigning pipelines to workers is a Buddy On-Premises only feature. Read this blog post to learn more.

This is how you define pipeline-worker assignment criteria:

  "tags": [
    "t1",
    "t2"
  ],
  "worker_assignment": "TAGS",
  "worker": "worker-4"

Properties

Name	Type	Description
worker_assignment	String	Defines the worker assignment method. Can be one of `FIXED` or `TAGS`. When set to `FIXED`, the worker is assigned in the `worker` property.
tags	String[]	Required when `worker_assignment` is set to `TAGS`. Runs the pipeline on the worker with tags that match those specified in the array.
worker	String	Defines the worker on which the pipeline runs when `worker_assignment` is set to `FIXED`. If you don't specify the worker, Buddy automatically runs the pipeline on the main worker of the On-Premises instance.