Run Pipelines with ScheduledTrigger
For the architecture, motivations, and design background of ScheduledTrigger, see the ScheduledTrigger Concepts page.
TOC
OverviewTypical Use CasesSupported Resource TypesTypical WorkflowBasic Manifest StructureStep-by-Step Configuration1. Choose the cadence and time zone2. Point to the TriggerTemplate3. Pass parameters4. Apply the manifest5. Validate the resourceTime Zone Resolution for Context ParametersSet the controller default time zone cluster-wideManaging ScheduledTrigger Over TimeInline Template ExampleTime-Zone-Aware Weekly ExampleRecommended SettingsReference LinksOverview
ScheduledTrigger lets you execute a TriggerTemplate on a cron-style cadence without relying on inbound webhooks. Each tick of the schedule renders the template, injects any static or time-based parameters, and creates the Tekton resources (for example PipelineRuns) you defined. This how-to walks you through preparing the prerequisites, writing the manifest, and validating the automation end to end.
Typical Use Cases
- Nightly regression tests or security scans that must run even when no Git activity occurs.
- Scheduled reports, such as the weekly report in Time-Zone-Aware Weekly Example.
Supported Resource Types
ScheduledTrigger currently supports the following Tekton Pipelines resources in TriggerTemplate:
Recommendation: use
tekton.dev/v1forPipelineRunandTaskRun;tekton.dev/v1beta1is still accepted for them but is deprecated and will be removed in a future release.CustomRunexists only astekton.dev/v1beta1.
Typical Workflow
- Confirm the TriggerTemplate you want to run periodically (reusable reference or inline spec).
- Decide on the cadence, time zone, and any contextual parameters the automation needs.
- Create a
ScheduledTriggermanifest that binds the template to the schedule. - Apply the manifest and monitor the resource status/events to ensure executions occur.
Basic Manifest Structure
Step-by-Step Configuration
1. Choose the cadence and time zone
- Use standard cron syntax (minute hour day-of-month month day-of-week). Example:
15 1 * * 1-5runs at 01:15 Monday through Friday. - Set
spec.timeZoneto an Olson time zone string (for exampleEurope/Paris). If omitted, the controller renders in its own time zone (UTC by default — see Time Zone Resolution for Context Parameters). - Prefer explicit time zones when business hours differ from the cluster default or when daylight-saving changes matter.
2. Point to the TriggerTemplate
You can reference a reusable template via spec.triggerTemplate.ref, or embed a full template inline under spec.triggerTemplate.spec. References keep multiple ScheduledTriggers in sync, while inline specs make each manifest self-contained.
3. Pass parameters
- Use
spec.paramsto feed static values into the template ($(tt.params.<name>)). Context placeholders (for example$(context.date)and$(context.datetime)) are replaced only in this section; anywhere else they stay as literal text. - Combine those placeholders with your own params to generate deterministic run names, tags, or report partitions, then reference them inside the template as
$(tt.params.<name>). - Because Tekton Trigger parameters are strings, serialize complex objects (for example JSON) before passing them.
4. Apply the manifest
Target the namespace where the TriggerTemplate lives. Kubernetes RBAC must allow the controller to resolve and execute that template.
5. Validate the resource
Check the .status.lastScheduleTime field (shown as Last Schedule Time by kubectl describe) to confirm the controller is firing. The Scheduled event message names the TriggerTemplate of spec.triggerTemplate.ref; with an inline template (spec.triggerTemplate.spec) the name is empty, so the message reads Scheduled for <time>, with two spaces. The time in the Scheduled event message is in the time zone of the controller, not in the spec.timeZone of the ScheduledTrigger: UTC by default, as in the sample, or the zone of the controller TZ variable described in Set the controller default time zone cluster-wide, for example 2025-11-26T02:00:00+08:00 with Asia/Shanghai. Kubernetes events surfaced by kubectl describe indicate successful runs and scheduling errors such as a missing template. Events are kept only for a limited time, so the Scheduled event of an older run can be gone; Last Schedule Time stays. An invalid cron expression is rejected when the ScheduledTrigger is created or updated, so it does not appear as an event.
If executions still do not start as expected, review the ScheduledTrigger troubleshooting guide for detailed investigation steps.
Time Zone Resolution for Context Parameters
The $(context.date) and $(context.datetime) placeholders are rendered using the schedule's effective time zone. The same effective zone is used both to evaluate the cron schedule and to render the placeholders, so a trigger's firing time and its injected timestamps always agree. The zone is resolved in this order:
spec.timeZoneon the ScheduledTrigger, when set. This takes precedence over everything else and is the recommended way to control an individual trigger.- The controller's process time zone, when
spec.timeZoneis omitted. - UTC, which is the controller's default out of the box.
For example, with no spec.timeZone and the default controller zone, $(context.datetime) resolves to a UTC timestamp such as 2025-11-25T07:42:00Z.
Set the controller default time zone cluster-wide
Out of the box the ScheduledTrigger controller runs in UTC. To change the default for every ScheduledTrigger that does not set its own spec.timeZone, inject a TZ environment variable into the controller through TektonConfig options. The operator applies this additively and does not revert it on reconcile:
Save the sample as tektonconfig-tz.yaml and merge it into the existing TektonConfig:
A merge patch replaces lists as a whole: if TektonConfig already sets containers for this Deployment, copy those entries into the file. Do not use kubectl apply -f for a file that holds only part of TektonConfig: kubectl apply stores the file in the kubectl.kubernetes.io/last-applied-configuration annotation, and a later kubectl apply -f of another partial file deletes the fields that the earlier file set and the later file leaves out, such as this TZ setting or the trigger export rules.
After the change, the operator rolls out the controller. Subsequent runs render the context placeholders in the configured zone — for example $(context.datetime) becomes 2025-11-25T15:42:00+08:00 for Asia/Shanghai.
- Editing the controller Deployment directly (for example with
kubectl set env) is reverted by the operator within minutes. Always configureTZthroughTektonConfigso the change is persistent. - A per-trigger
spec.timeZonealways overrides this cluster-wide default. Preferspec.timeZonefor individual schedules and reserve the controllerTZfor setting an organization-wide default. TZaccepts IANA/Olson time zone names (for exampleUTC,Asia/Shanghai,Asia/Kolkata). With an invalid name, the controller process falls back to UTC (Gotime.Localis UTC whenTZcannot be loaded), so every ScheduledTrigger withoutspec.timeZonefires and renders its placeholders in UTC.
Managing ScheduledTrigger Over Time
- Update cadence: Edit the resource (
kubectl editor apply a new manifest) to changespec.scheduleorspec.timeZone. The controller computes the next time fromstatus.lastScheduleTime(the creation time if the ScheduledTrigger has not run yet) with the new schedule and time zone. If one or more times of the new schedule lie between the last run and the edit, it can create one run at once for the most recent of those times; it then follows the new schedule. For example, a ScheduledTrigger with0 2 * * *that last ran at 02:00 and is changed to0 9 * * *at 10:00 starts one run at once for the missed 09:00 time. - Rotate parameters: Modify
spec.paramsto update static values such as environment names, feature flags, or recipients. - Switch templates: Point
spec.triggerTemplate.refto a new template, or update the inline spec. Subsequent executions use the new logic immediately. - Pause or remove: Delete the ScheduledTrigger to stop future runs. Recreate it later with the same name if you need to resume the cadence.
Inline Template Example
Time-Zone-Aware Weekly Example
Recommended Settings
When to enable. Use ScheduledTrigger when work must run on a calendar rather than in response to an event, such as scans and reports. Set the time zone once at the cluster level so that every ScheduledTrigger without its own spec.timeZone fires on the same clock.
Recommended values. Set the organization-wide default time zone once through the controller TZ variable in TektonConfig, as described in Set the controller default time zone cluster-wide, and set spec.timeZone only on schedules that must follow a different zone. To undo the default, remove the TZ entry from the env list of the manager container in TektonConfig, for example with kubectl edit tektonconfig config, and keep the other options of tektoncd-enhancement-controller; the operator then removes TZ from the controller and rolls it back. Create one ScheduledTrigger per job in the namespace where its TriggerTemplate lives, with a cadence chosen for that job. Pass every value the template needs explicitly in spec.params, including a $(context.date) or $(context.datetime) placeholder so each run can be identified:
After applying, confirm that Last Schedule Time (.status.lastScheduleTime) advances at each tick and that the Scheduled events appear, as shown in step 5, "Validate the resource", under Step-by-Step Configuration.
Prerequisites. Setting the controller TZ changes TektonConfig and needs cluster administrator rights. The ScheduledTrigger controller (tektoncd-enhancement-controller) must be running, and the referenced TriggerTemplate must exist in the namespace of the ScheduledTrigger. The Pipeline or Task it runs must exist in the namespace where the run is created: the namespace of the ScheduledTrigger, unless the resource template sets its own metadata.namespace. Kubernetes RBAC must allow the controller to resolve and execute that template. If an admission policy in the namespace where the run is created denies TaskRun create requests that do not come from the Tekton Pipelines controller, such as the deny-standalone-taskrun rule in Constrain Tekton Pipeline Execution with Kyverno, a template that creates a TaskRun is denied unless the policy excludes the ServiceAccount of the ScheduledTrigger controller (tektoncd-enhancement-controller in the namespace set by TektonConfig spec.targetNamespace, tekton-pipelines by default). Time zone names must be valid IANA time zone names; the controller binary carries its own copy of the IANA time zone database. Cron expressions must use the standard five-field form; see ScheduledTrigger Concepts.