Uploaded image for project: 'OpenShift Pipelines'
  1. OpenShift Pipelines
  2. SRVKP-8026

Add CEL expression evaluator command

XMLWordPrintable

    • 3
    • False
    • Hide

      None

      Show
      None
    • False
    • Hide
      A new command, `tkn pac cel`, has been added to the `tkn` CLI. This command allows you to interactively evaluate Common Expression Language (CEL) expressions against webhook payloads and headers.

      Important Note:

      This command is admin only since it needs access to the payload and the headers to works (to be fecthed from the github/gitlab/etc.. web interface).

      This feature is a Technological Preview feature.

      1. Provider Auto-detection: The command automatically detects the source of the webhook payload (GitHub, GitLab, Bitbucket, Gitea) from the incoming data.
      2. File Input: You can provide webhook payloads and headers via JSON or plain text files using the `-b` and `-H` flags, respectively. It also supports parsing headers from shell scripts generated by tools like `gosmee`.
      3. Interactive Mode: When run in a terminal, `tkn pac cel` provides an interactive prompt where you can type CEL expressions. Tab completion is available for variables and payload fields.
      4. Variable Access: CEL expressions can access data through several sources:
           Direct variables (e.g., `event`, `target_branch`).
           Webhook payload fields (e.g., `body.action`).
           HTTP headers (e.g., `headers['X-GitHub-Event']`).
           Pipelines as Code specific parameters (e.g., `pac.revision`).
      5. Debugging: This command is useful for debugging CEL expressions used in `PipelineRun` configurations, allowing you to quickly test logic against real-world webhook data.
      Show
      A new command, `tkn pac cel`, has been added to the `tkn` CLI. This command allows you to interactively evaluate Common Expression Language (CEL) expressions against webhook payloads and headers. Important Note: This command is admin only since it needs access to the payload and the headers to works (to be fecthed from the github/gitlab/etc.. web interface). This feature is a Technological Preview feature. 1. Provider Auto-detection: The command automatically detects the source of the webhook payload (GitHub, GitLab, Bitbucket, Gitea) from the incoming data. 2. File Input: You can provide webhook payloads and headers via JSON or plain text files using the `-b` and `-H` flags, respectively. It also supports parsing headers from shell scripts generated by tools like `gosmee`. 3. Interactive Mode: When run in a terminal, `tkn pac cel` provides an interactive prompt where you can type CEL expressions. Tab completion is available for variables and payload fields. 4. Variable Access: CEL expressions can access data through several sources:      Direct variables (e.g., `event`, `target_branch`).      Webhook payload fields (e.g., `body.action`).      HTTP headers (e.g., `headers['X-GitHub-Event']`).      Pipelines as Code specific parameters (e.g., `pac.revision`). 5. Debugging: This command is useful for debugging CEL expressions used in `PipelineRun` configurations, allowing you to quickly test logic against real-world webhook data.
    • Feature
    • Done

      Story (Required)

      As a Pipelines-as-Code user trying to test and debug CEL expressions I want a command-line tool to interactively evaluate CEL expressions so that I can quickly verify the logic of my pipelines.

      This story addresses the need for a convenient way to test and debug CEL expressions used within Pipelines-as-Code. It improves the user experience by providing an interactive tool, reducing the time and effort required for testing and debugging.

      Background (Required)

      CEL (Common Expression Language) expressions are frequently used in Pipelines-as-Code for conditional logic and data manipulation. Currently, there's no dedicated tool to easily test and debug these expressions. This limits developer productivity and increases the time needed to resolve issues.

      Out of scope

      This story does not include the development of new CEL functions or extensions. It focuses solely on providing a tool for evaluating existing CEL expressions. Error handling beyond basic syntax errors is within scope, but detailed error analysis and reporting for complex CEL issues are out of scope for this initial release. Integration with other pipeline debugging tools is also out of scope for this initial release.

      Approach (Required)

      The approach involves creating a new command-line tool, `tkn pac cel`, built to parse and evaluate CEL expressions. The tool will support interactive and non-interactive modes, handle various webhook payloads and headers, auto-detect providers (GitHub, GitLab, Bitbucket Cloud, Bitbucket Data Center, Gitea), and allow direct access to variables as defined in the PAC documentation. The tool's design will utilize readline for a cross-platform consistent user experience. Comprehensive help and example expressions will also be provided. The implementation will leverage existing CEL libraries and adhere to established coding standards and testing practices.

      Dependencies

      None identified at this time.

      Acceptance Criteria (Mandatory)

      • The `tkn pac cel` command should successfully parse and evaluate valid CEL expressions.
      • The command should handle various input formats, including JSON payloads and headers.
      • The command should correctly identify and handle common CEL syntax errors.
      • The command should correctly auto-detect the provider (GitHub, GitLab, Bitbucket Cloud, Bitbucket Data Center, Gitea) based on context.
      • The interactive mode should provide a user-friendly experience with input history and helpful prompts.
      • The non-interactive mode should allow for efficient batch evaluation of expressions.
      • The command should correctly access variables available within the Pipelines-as-Code context.
      • The command should provide clear and informative error messages.
      • Comprehensive help documentation should be included. Example expressions should be provided in the help documentation and cover the common use cases for the tool.
      • Unit and integration tests verifying all of the above points should be implemented.

      INVEST Checklist

      Dependencies identified: Verified
      Blockers noted and expected delivery timelines set: Verified
      Design is implementable: Verified
      Acceptance criteria agreed upon: Unsatisfied
      Story estimated: Unknown

      Legend

      Unknown
      Verified
      Unsatisfied

      Done Checklist

      • Code is completed, reviewed, documented and checked in: Unsatisfied
      • Unit and integration test automation have been delivered and running cleanly in continuous integration/staging/canary environment: Unsatisfied
      • Continuous Delivery pipeline(s) is able to proceed with new code included: Unsatisfied
      • Customer facing documentation, API docs etc. are produced/updated, reviewed and published: Unsatisfied
      • Acceptance criteria are met: Unsatisfied

      Originial Pull Request number

      https://github.com/openshift-pipelines/pipelines-as-code/pull/2151(https://github.com/openshift-pipelines/pipelines-as-code/pull/2151)

      Original Pull Request Description

      1. Changes

      This commit introduces a new command `tkn pac cel` that allows users to interactively evaluate CEL (Common Expression Language) expressions. The command is designed to help users test and debug CEL expressions, which are commonly used in Pipelines-as-Code.

      https://github.com/user-attachments/assets/c0287b86-4656-43c3-ab52-9c6fa1a36889

      Key features include:

      • Interactive and non-interactive modes.
      • Support for webhook payloads and headers.
      • Provider auto-detection (GitHub, GitLab, Bitbucket Cloud, Bitbucket Data Center, Gitea).
      • Direct access to variables as per PAC documentation.
      • Cross-platform history with readline experience.
      • Comprehensive help and example expressions.

      <Unable to render embedded object: File (-- Describe your changes here- ideally you can get that description straight from your descriptive commit message(s)) not found. -->

      1. Submitter Checklist
      • [ ] 📝 Ensure your commit message is clear and informative. Refer to the How to write a git commit message guide. Include the commit message in the PR body rather than linking to an external site (e.g., Jira ticket).
      • [ ] ♽ Run make test lint before submitting a PR to avoid unnecessary CI processing. Consider installing [pre-commit](https://pre-commit.com/) and running pre-commit install in the repository root for an efficient workflow.
      • [ ] 📖 Document any user-facing features or changes in behavior.
      • [ ] 🧪 While 100% coverage isn't required, we encourage unit tests for code changes where possible.
      • [ ] 🔎 Address any CI test flakiness before merging, or provide a valid reason to bypass it (e.g., token rate limitations).
      • If adding a provider feature, fill in the following details:
      • [ ] GitHub App
      • [ ] GitHub Webhook
      • [ ] Gitea/Forgejo
      • [ ] GitLab
      • [ ] Bitbucket Cloud
      • [ ] Bitbucket Data Center

      (update the provider documentation accordingly)

      Files Changed: 41
      Additions: +7912
      Deletions: -1

              cboudjna@redhat.com Chmouel Boudjnah
              cboudjna@redhat.com Chmouel Boudjnah
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Created:
                Updated:

                  Estimated:
                  Original Estimate - 3 minutes
                  3m
                  Remaining:
                  Remaining Estimate - 3 minutes
                  3m
                  Logged:
                  Time Spent - Not Specified
                  Not Specified