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.

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,
  "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,
  "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 worker 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 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', 'VAR_LESS_THAN', 'VAR_LESS_THAN_OR_EQUAL', 'VAR_GREATER_THAN', 'VAR_GREATER_THAN_OR_EQUAL', 'DAY', 'HOUR' or 'SUCCESS_PIPELINE'. Can't be used in deployment actions.
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.

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'.

Last modified on January 9, 2023

Get Started

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