feat(controlplane): allow filtering workflow runs by workflow and version

app/cli/cmd/workflow_workflow_run_list.go

@@ -33,7 +33,7 @@ func newWorkflowWorkflowRunListCmd() *cobra.Command {
 		DefaultLimit: 50,
 	}
 
-	var workflowName, projectName, status, policyStatus string
+	var workflowName, projectName, projectVersion, status, policyStatus string
 
 	cmd := &cobra.Command{
 		Use:     "list",
@@ -48,13 +48,20 @@ func newWorkflowWorkflowRunListCmd() *cobra.Command {
 				return fmt.Errorf("invalid policy-status %q, please chose one of: all, failed, passed", policyStatus)
 			}
 
+			// A version name is unique only within a project, so filtering by
+			// version requires the project to be set.
+			if projectVersion != "" && projectName == "" {
+				return fmt.Errorf("--project is required when --version is set")
+			}
+
 			return nil
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			res, err := action.NewWorkflowRunList(ActionOpts).Run(
 				&action.WorkflowRunListOpts{
-					WorkflowName: workflowName,
-					ProjectName:  projectName,
+					WorkflowName:       workflowName,
+					ProjectName:        projectName,
+					ProjectVersionName: projectVersion,
 					Pagination: &action.PaginationOpts{
 						Limit:      paginationOpts.Limit,
 						NextCursor: paginationOpts.NextCursor,
@@ -88,6 +95,7 @@ func newWorkflowWorkflowRunListCmd() *cobra.Command {
 
 	cmd.Flags().StringVar(&workflowName, "workflow", "", "workflow name")
 	cmd.Flags().StringVar(&projectName, "project", "", "project name")
+	cmd.Flags().StringVar(&projectVersion, "version", "", "project version name, e.g. v1.2.0 (requires --project)")
 	cmd.Flags().BoolVar(&full, "full", false, "full report")
 	cmd.Flags().StringVar(&status, "status", "", fmt.Sprintf("filter by workflow run status: %v", listAvailableWorkflowStatusFlag()))
 	cmd.Flags().StringVar(&policyStatus, "policy-status", "", "filter by policy violations status: all, failed, passed")

app/cli/cmd/workflow_workflow_run_list_test.go

@@ -0,0 +1,65 @@
+//
+// Copyright 2026 The Chainloop Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmd
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestWorkflowRunListPreRunValidation(t *testing.T) {
+	testCases := []struct {
+		name    string
+		version string
+		project string
+		wantErr string
+	}{
+		{
+			name:    "version without project is rejected",
+			version: "v1.0.0",
+			project: "",
+			wantErr: "--project is required when --version is set",
+		},
+		{
+			name:    "version with project is allowed",
+			version: "v1.0.0",
+			project: "my-project",
+		},
+		{
+			name:    "no version is allowed without project",
+			version: "",
+			project: "",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := newWorkflowWorkflowRunListCmd()
+			require.NoError(t, cmd.Flags().Set("version", tc.version))
+			require.NoError(t, cmd.Flags().Set("project", tc.project))
+
+			err := cmd.PreRunE(cmd, nil)
+			if tc.wantErr != "" {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tc.wantErr)
+				return
+			}
+			assert.NoError(t, err)
+		})
+	}
+}

app/cli/documentation/cli-reference.mdx

@@ -4033,6 +4033,7 @@ Options
 --policy-status string   filter by policy violations status: all, failed, passed
 --project string         project name
 --status string          filter by workflow run status: [CANCELLED EXPIRED FAILED INITIALIZED SUCCEEDED]
+--version string         project version name, e.g. v1.2.0 (requires --project)
 --workflow string        workflow name
 ```
 

app/cli/pkg/action/workflow_run_list.go

@@ -73,9 +73,12 @@ func NewWorkflowRunList(cfg *ActionsOpts) *WorkflowRunList {
 
 type WorkflowRunListOpts struct {
 	WorkflowName, ProjectName string
-	Pagination                *PaginationOpts
-	Status                    string
-	PolicyStatus              string
+	// ProjectVersionName filters by project version name (e.g. v1.2.0). It requires
+	// ProjectName, since a version name is unique only within a project.
+	ProjectVersionName string
+	Pagination         *PaginationOpts
+	Status             string
+	PolicyStatus       string
 }
 type PaginationOpts struct {
 	Limit      int
@@ -85,8 +88,9 @@ type PaginationOpts struct {
 func (action *WorkflowRunList) Run(opts *WorkflowRunListOpts) (*PaginatedWorkflowRunItem, error) {
 	client := pb.NewWorkflowRunServiceClient(action.cfg.CPConnection)
 	req := &pb.WorkflowRunServiceListRequest{
-		WorkflowName: opts.WorkflowName,
-		ProjectName:  opts.ProjectName,
+		WorkflowName:       opts.WorkflowName,
+		ProjectName:        opts.ProjectName,
+		ProjectVersionName: opts.ProjectVersionName,
 		Pagination: &pb.CursorPaginationRequest{
 			Limit:  int32(opts.Pagination.Limit),
 			Cursor: opts.Pagination.NextCursor,

app/controlplane/api/controlplane/v1/workflow_run.proto

@@ -215,11 +215,20 @@ message WorkflowRunServiceListRequest {
   string project_name = 4;
   // by run status
   RunStatus status = 3;
-  // by project version
-  string project_version = 5 [(buf.validate.field) = {
-    string: {uuid: true}
-    ignore: IGNORE_IF_ZERO_VALUE
-  }];
+  // by project version (UUID).
+  // Deprecated: use project_version_name together with project_name. A version
+  // name is unique only within a project, so filtering by name is the canonical
+  // and discoverable path; the UUID is kept for backward compatibility.
+  string project_version = 5 [
+    deprecated = true,
+    (buf.validate.field) = {
+      string: {uuid: true}
+      ignore: IGNORE_IF_ZERO_VALUE
+    }
+  ];
+  // by project version name (e.g. v1.2.0). Requires project_name, since a
+  // version name is unique only within a project.
+  string project_version_name = 9;
   // by policy violations status
   // Deprecated: use policy_status (PolicyStatusFilter), which aligns 1:1 with
   // the canonical PolicyStatus enum. When both are set, policy_status wins.
@@ -238,6 +247,14 @@ message WorkflowRunServiceListRequest {
     expression: "!(this.workflow_name != '' && this.project_name == '')"
     message: "project_name must be set if workflow_name is set"
   };
+
+  // project_version_name requires project_name (a version name is unique only
+  // within a project).
+  option (buf.validate.message).cel = {
+    id: "list_project_version_name_requires_project_name"
+    expression: "!(this.project_version_name != '' && this.project_name == '')"
+    message: "project_name must be set when project_version_name is set"
+  };
 }
 
 message WorkflowRunServiceListResponse {