cel

Use tkn pac cel to evaluate CEL (Common Expression Language) expressions interactively against webhook payloads. This command helps you test and refine the CEL expressions you use in your PipelineRun annotations before committing them.

Usage

tkn pac cel -b <body.json> -H <headers.txt>

Flags

• -b / --body: Path to the JSON body file (webhook payload). Required.
• -H / --headers: Path to the headers file (plain text, JSON, or gosmee script). Required.
• -p / --provider: Provider type (auto, github, gitlab, bitbucket-cloud, bitbucket-datacenter, gitea, forgejo). Defaults to auto-detection.

How It Works

This command evaluates CEL expressions exactly as Pipelines-as-Code would, using real webhook payloads and headers. It supports interactive and non-interactive modes, provider auto-detection, and persistent history.

The CEL evaluator requires the payload and headers as files. You can get these from the webhook configuration page on your Git provider by copying the payload and headers to separate files.

The payload is the JSON content of the webhook request. The headers file supports multiple formats:

1. Plain HTTP headers format

2. JSON format:

   {
     "X-GitHub-Event": "pull_request",
     "Content-Type": "application/json",
     "User-Agent": "GitHub-Hookshot/2d5e4d4"
   }

3. Gosmee-generated shell scripts: The command automatically detects and parses shell scripts generated by gosmee when using the --save feature, extracting headers from curl commands with -H flags:

   #!/usr/bin/env bash
   curl -X POST "http://localhost:8080/" -H "X-GitHub-Event: pull_request" -H "Content-Type: application/json" -H "User-Agent: GitHub-Hookshot/2d5e4d4" -d @payload.json

Interactive Mode

When you run the command in a terminal, it displays a prompt:

CEL expression>

• Use the up/down arrows to navigate history.
• History is saved and loaded automatically.
• Press Enter on an empty line to exit.

Non-Interactive Mode

You can pipe expressions via stdin:

echo 'event == "pull_request"' | tkn pac cel -b body.json -H headers.txt

Available Variables

• Direct variables (top-level, as documented in the CEL expressions guide):

  • event – event type (push, pull_request)
  • target_branch – target branch name
  • source_branch – source branch name
  • target_url – target repository URL
  • source_url – source repository URL
  • event_title – pull request title or commit message

• Webhook payload (body.*): All fields from the webhook JSON.

• HTTP headers (headers.*): All HTTP headers.

• Files (files.*): Always empty in CLI mode.

• Pipelines-as-Code parameters (pac.*): All variables for backward compatibility.

Examples

event == "pull_request" && target_branch == "main"
event == "pull_request" && source_branch.matches(".*feat/.*")
body.action == "synchronize"
!body.pull_request.draft
headers['x-github-event'] == "pull_request"
event == "pull_request" && target_branch != "experimental"

Limitations

• files.* variables are always empty in CLI mode.
• Functions like fileChanged, fileDeleted, and fileModified are not yet implemented in the CLI.

Cross-Platform History

• History is saved in a cache directory:
  • Linux/macOS: ~/.cache/tkn-pac/cel-history
  • Windows: %USERPROFILE%\.cache\tkn-pac\cel-history
• The directory is created automatically if it does not exist.