Triggers and inputs

Description and operation

General

A trigger is a way to start a run. You can always start a run with the SDK, the CLI or the API. The triggers key of a definition adds three more ways. A run from a trigger uses the newest version at the time that it starts.

To turn a trigger off, remove its key and save the definition as a new version.

To do these tasks with an AI agent, see Agentic workflows – General.

Inputs

inputs declares the values that a run takes. Every value is text. A job reads an input as ${{ inputs.NAME }}.

An input name starts with a letter or an underscore, and has at most 40 letters, digits, underscores or hyphens. An input with options needs a default or required, because an empty value is not one of the options.

A start can give only declared inputs. A trigger gives no values, so every trigger run uses the defaults. For that reason, a definition with a trigger cannot have a required input with no default.

Schedule

triggers.schedule is a list of cron lines in UTC, with five fields: minute hour day-of-month month weekday. Each line that matches a minute starts one run in that minute. A minute in which the platform does not run is skipped, not run later.

When a line restricts both day-of-month and weekday, a minute matches if either field matches. Month names, weekday names and @daily are not accepted. Weekday 0 and 7 are Sunday. The full syntax is in Cron.

Webhook

"webhook": true gives the pipeline a secret URL. A POST to the URL starts a run, with no token. The answer of the save that turns the webhook on shows the URL once. No later answer shows it, so store it as a secret of the calling system. A rotate makes a new URL and stops the old one at once. "webhook": false deletes the secret.

Read webhook data safely

The caller of a webhook controls the text of webhook.body. A job can read it only in env and in if. It cannot read it in run, cwd, image or packages. Put a value in a variable, then use the variable in quotes in the command.

A field that is not in the body reads as the empty text. A field that is a number, an object or a list reads as its JSON text. Use dots for nested fields, for example webhook.body.repo.name.

After another pipeline

triggers.after starts a run when a run of another pipeline of the same owner ends. With result (success, failure or cancelled), only that end state starts a run. Without result, any end starts a run.

A pipeline cannot follow itself, and the pipeline that it follows must exist when you save. A chain of after triggers stops at a depth of 5. The finished run lists in triggered each run that it started, and the error of each start that was refused.

Tasks

Give a run its inputs

Reason for the task: Make one pipeline do different work for each run, for example on another data set.

Job set-up

• Access: you. For a team, an admin to change the definition, and an active member to start the run.
• References: Inputs, SDK pipelines.run.

Procedure

1. Add the inputs to the definition, and read them in env.

   jsonCopy

   {  "name": "refresh",  "inputs": {    "dataset": { "options": ["orders", "customers"], "default": "orders" },    "day": { "required": true }  },  "jobs": {    "load": {      "steps": [        {          "name": "load",          "run": "echo \"loading $DATASET for $DAY\"",          "env": { "DATASET": "${{ inputs.dataset }}", "DAY": "${{ inputs.day }}" }        }      ]    }  }}

2. Create the pipeline from the file. See Create a pipeline.

3. Start a run with a value for each input.

   PythonCopy

   run = kl.pipelines.run(owner="acme", pipeline="refresh", inputs={"dataset": "customers", "day": "2026-10-21"})print(run.inputs)

   TypeScriptCopy

   const run = await kl.pipelines.run({ owner: "acme", pipeline: "refresh", inputs: { dataset: "customers", day: "2026-10-21" } });console.log(run.doc.inputs);

   GoCopy

   run, err := kl.Pipelines.Run(kloudlite.RunPipeline{    Owner: "acme", Pipeline: "refresh",    Inputs: map[string]string{"dataset": "customers", "day": "2026-10-21"},})if err != nil {    log.Fatal(err)}fmt.Println(run.Inputs)

   RubyCopy

   run = kl.pipelines.run(owner: "acme", pipeline: "refresh", inputs: { "dataset" => "customers", "day" => "2026-10-21" })p run.inputs

   JavaCopy

   var run = kl.pipelines().run(new Kloudlite.RunPipeline().owner("acme").pipeline("refresh")    .input("dataset", "customers").input("day", "2026-10-21"));System.out.println(run.json());

   CLICopy

   kloudlite pipelines run acme/refresh --input dataset=customers --input day=2026-10-21

Close-out

1. Make sure that inputs of the run shows both values.

Run a pipeline on a schedule

Reason for the task: Do recurring work, such as a nightly data refresh, with no person to start it.

Job set-up

• Access: you. For a team, an admin.
• Conditions: every input of the pipeline has a default, or is not required.
• References: Schedule, Cron.

Procedure

1. Add triggers.schedule to the definition. This line starts a run at 02:00 UTC every day.

   jsonCopy

   {  "name": "nightly-report",  "triggers": { "schedule": ["0 2 * * *"] },  "jobs": {    "fetch": {      "packages": ["curl"],      "steps": [{ "name": "download", "run": "curl -fsSL https://api.github.com/repos/nixos/nixpkgs -o data.json" }]    }  }}

2. Send the definition as the next version. See Save a new version.

Close-out

1. Read the pipeline. Make sure that triggers.schedule lists the line.
2. Wait until after 02:00 UTC, then show the runs of the pipeline. Make sure that the newest run has event schedule.

Start a run from a webhook

Reason for the task: Let another system start a run with one HTTP call, for example when its content changes.

Job set-up

• Access: you. For a team, an admin.
• Conditions: every input of the pipeline has a default, or is not required.
• References: Webhook, POST /v1/webhooks/pipelines/{owner}/{name}/{secret}.

Procedure

1. Set triggers.webhook to true, and read the data of the call in env.

   jsonCopy

   {  "name": "reindex",  "triggers": { "webhook": true },  "jobs": {    "index": {      "if": "webhook.body.page != ''",      "steps": [        { "name": "reindex", "run": "echo \"reindexing page $PAGE\"", "env": { "PAGE": "${{ webhook.body.page }}" } }      ]    }  }}

2. Create the pipeline, or send the definition as a new version. Read webhookUrl in the answer.

   PythonCopy

   with open("reindex.json") as f:    doc = kl.pipelines.create(owner="acme", definition=json.load(f))print(doc["webhookUrl"])

   TypeScriptCopy

   const doc = await kl.pipelines.create({ owner: "acme", definition: JSON.parse(readFileSync("reindex.json", "utf8")) });console.log(doc.webhookUrl);

   GoCopy

   raw, err := os.ReadFile("reindex.json")if err != nil {    log.Fatal(err)}var d kloudlite.PipelineDefinitionif err := json.Unmarshal(raw, &d); err != nil {    log.Fatal(err)}doc, err := kl.Pipelines.Create("acme", d)if err != nil {    log.Fatal(err)}fmt.Println(doc.WebhookURL)

   RubyCopy

   doc = kl.pipelines.create(owner: "acme", definition: JSON.parse(File.read("reindex.json")))puts doc["webhookUrl"]

   JavaCopy

   System.out.println(kl.request(new Kloudlite.RawRequest().method("POST").path("/v1/pipelines/acme")    .body(Files.readString(Path.of("reindex.json")))));

   CLICopy

   kloudlite pipelines create --owner acme --file reindex.json

3. Keep the URL as a secret of the calling system.

4. Send a call to the URL from that system.

   CLICopy

   curl -fsS -X POST -H 'Content-Type: application/json' -d '{"page": "pricing"}' "$WEBHOOK_URL"

Close-out

1. Make sure that the call answered 202 with the id of a run.
2. Read the log of the job index. Make sure that it shows reindexing page pricing.

Make a new webhook URL

Reason for the task: Stop an old webhook URL that is lost or shared, and get a new one.

Job set-up

• Access: you. For a team, an admin.
• Conditions: the newest version sets triggers.webhook to true.
• References: POST /v1/pipelines/{owner}/{name}/webhook/rotate, SDK pipelines.rotate_webhook.

Procedure

1. Make a new webhook URL. The answer shows the new URL once.

   PythonCopy

   print(kl.pipelines.rotate_webhook(owner="acme", name="reindex")["webhookUrl"])

   TypeScriptCopy

   console.log((await kl.pipelines.rotateWebhook({ owner: "acme", name: "reindex" })).webhookUrl);

   GoCopy

   url, err := kl.Pipelines.RotateWebhook("acme", "reindex")if err != nil {    log.Fatal(err)}fmt.Println(url)

   RubyCopy

   puts kl.pipelines.rotate_webhook(owner: "acme", name: "reindex")["webhookUrl"]

   JavaCopy

   System.out.println(kl.pipelines().rotateWebhook("acme", "reindex"));

   CLICopy

   kloudlite pipelines rotate-webhook acme/reindex

2. Replace the URL in each system that calls it.

Close-out

1. Send a call to the new URL. Make sure that it answers 202.

Start a pipeline after another pipeline

Reason for the task: Run follow-up work when earlier work succeeds, for example a release after tests.

Job set-up

• Access: you. For a team, an admin.
• Conditions: the pipeline site-check exists for the same owner. See Run jobs in parallel.
• References: After another pipeline.

Procedure

1. Add triggers.after to the definition of the follow-up pipeline.

   jsonCopy

   {  "name": "publish-status",  "triggers": { "after": { "pipeline": "site-check", "result": "success" } },  "jobs": {    "publish": {      "steps": [{ "name": "publish", "run": "echo \"all sites are up\"" }]    }  }}

2. Create the pipeline from the file. See Create a pipeline.

3. Start a run of site-check and wait for it to end. See Start a run and follow it.

Close-out

1. Read the finished run of site-check. Make sure that triggered names publish-status and a run.
2. Show the runs of publish-status. Make sure that the newest run has event pipeline.

Troubleshooting