Trigger a workflow using an API

Use any API client, such as an external IDE, to trigger a CloudBees platform workflow run using a curl command. Users with the appropriate permissions can start a workflow without accessing the UI, as long as the workflow contains a workflow_dispatch trigger.

Prerequisites

You must first perform the following tasks in order to trigger a workflow remotely:

Create a workflow with a manual trigger in the platform.
Generate a personal access token in the platform.

Form the `curl` command

Configure a curl command to invoke the manually-triggered workflow.

To form the curl command:

Select an organization, and then select the component with the manually-triggered workflow that you want to run remotely.
Locate the component ID and copy it for use in the curl command.
In your component, select a workflow containing a workflow_dispatch trigger from Workflows, and then copy the following for use in the curl command:
- The workflow branch name.
- The workflow filename, for example, my-workflow.yaml.
  
  To be triggered using an API, a workflow must contain a workflow_dispatch trigger.
(Optional) Add input parameters to the trigger as key/value pairs, to customize workflow runtime behavior.

Using the copied information, configure the curl command in the format below:

curl --location 'https://api.cloudbees.io/v2/components/<COMPONENT_ID>/trigger' \ (1)
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer <PERSONAL_ACCESS_TOKEN>' \ (2)
 --data '{
  "branchName": "<REPOSITORY_BRANCH>", (3)
  "workflowFileName": "<WORKFLOW_FILE.YAML>", (4)
\\ (5)
 "inputs": {
    "<string_parameter_name>": "<string_value>",
    "<number_parameter_name>": "<number_value>",
    "<boolean_parameter_name>": "<boolean_value>",
    "<choice_parameter_name>": "<choice_option1>,<choice_option2>,<choice_option3>,<default_option>"
  }
}'▼

1	Replace `<COMPONENT_ID>` with the CloudBees platform component ID to form the endpoint URL.
2	Replace `<PERSONAL_ACCESS_TOKEN>` with your personal access token.
3	Replace `<REPOSITORY_BRANCH>` with the repository branch name.
4	Replace `<WORKFLOW_FILENAME.YAML>` with the workflow filename. For example, `my-filename.yaml`.
5	Include any applicable parameter names and valid values in the trigger `inputs`.

The curl command is configured to run your workflow remotely.

Usage example

The following is an example curl command and the workflow it invokes:

curl command

on:
  workflow_dispatch:
    inputs:
      str_param:
        type: string
      num_param:
        type: number
      boolean_param:
        type: boolean
        default: false
      choice_param:
        type: choice
        options:
          - option_one
          - option_two
          - option_three▼

Invoked workflow

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Remote workflow
on:
  push:
    branches:
      - "test-branch"
  workflow_dispatch:
    inputs:
      my_string:
        type: string
        default: my value
      my_boolean:
        type: boolean
        default: true
      my_choice:
        type: choice
        options:
          - https://example.com
          - https://example.net
          - https://example.io
        default: https://example.com
jobs:
  build:
    steps:
      - name: Say hello
        uses: docker://golang:1.20.3-alpine3.17
        shell: sh
        run: |
          echo "hello world"▼

Trigger the workflow run by executing the curl command in an external tool.

Trigger a workflow using an API

Prerequisites

Form the curl command

Usage example

Form the `curl` command