feat(controlplane): accept a workflow template reference on workflow create (#3386)

Author: migmartri

app/cli/pkg/action/workflow_create.go

@@ -32,18 +32,27 @@ func NewWorkflowCreate(cfg *ActionsOpts) *WorkflowCreate {
 type NewWorkflowCreateOpts struct {
 	Name, Description, Project, Team, ContractName string
 	ContractBytes                                  []byte
+	// WorkflowTemplateID optionally binds the workflow to a platform workflow template.
+	// The open-source CLI does not set it, it exists so template-aware clients can.
+	WorkflowTemplateID string
 }
 
 func (action *WorkflowCreate) Run(opts *NewWorkflowCreateOpts) (*WorkflowItem, error) {
 	client := pb.NewWorkflowServiceClient(action.cfg.CPConnection)
-	resp, err := client.Create(context.Background(), &pb.WorkflowServiceCreateRequest{
-		Name: opts.Name, ProjectName: opts.Project, Team: opts.Team, ContractName: opts.ContractName,
-		Description:   opts.Description,
-		ContractBytes: opts.ContractBytes,
-	})
+	resp, err := client.Create(context.Background(), newWorkflowCreateRequest(opts))
 	if err != nil {
 		return nil, err
 	}
 
 	return pbWorkflowItemToAction(resp.Result), nil
 }
+
+// newWorkflowCreateRequest maps the create options to the API request
+func newWorkflowCreateRequest(opts *NewWorkflowCreateOpts) *pb.WorkflowServiceCreateRequest {
+	return &pb.WorkflowServiceCreateRequest{
+		Name: opts.Name, ProjectName: opts.Project, Team: opts.Team, ContractName: opts.ContractName,
+		Description:        opts.Description,
+		ContractBytes:      opts.ContractBytes,
+		WorkflowTemplateId: opts.WorkflowTemplateID,
+	}
+}

app/cli/pkg/action/workflow_create_test.go

@@ -0,0 +1,103 @@
+//
+// 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 action
+
+import (
+	"testing"
+
+	pb "github.com/chainloop-dev/chainloop/app/controlplane/api/controlplane/v1"
+	"github.com/stretchr/testify/assert"
+	"google.golang.org/protobuf/types/known/timestamppb"
+)
+
+// TestNewWorkflowCreateOptsToRequest pins that the create options, including the optional
+// workflow template reference, are forwarded verbatim to the API request.
+func TestNewWorkflowCreateOptsToRequest(t *testing.T) {
+	testCases := []struct {
+		desc string
+		opts *NewWorkflowCreateOpts
+	}{
+		{
+			desc: "without a template reference",
+			opts: &NewWorkflowCreateOpts{
+				Name:    "my-workflow",
+				Project: "my-project",
+			},
+		},
+		{
+			desc: "with a template reference",
+			opts: &NewWorkflowCreateOpts{
+				Name:               "my-workflow",
+				Project:            "my-project",
+				Team:               "my-team",
+				Description:        "a description",
+				ContractName:       "my-contract",
+				ContractBytes:      []byte("schemaVersion: v1"),
+				WorkflowTemplateID: "1b4c6f8a-2d3e-4f5a-8b9c-0d1e2f3a4b5c",
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.desc, func(t *testing.T) {
+			got := newWorkflowCreateRequest(tc.opts)
+
+			assert.Equal(t, tc.opts.Name, got.GetName())
+			assert.Equal(t, tc.opts.Project, got.GetProjectName())
+			assert.Equal(t, tc.opts.Team, got.GetTeam())
+			assert.Equal(t, tc.opts.Description, got.GetDescription())
+			assert.Equal(t, tc.opts.ContractName, got.GetContractName())
+			assert.Equal(t, tc.opts.ContractBytes, got.GetContractBytes())
+			assert.Equal(t, tc.opts.WorkflowTemplateID, got.GetWorkflowTemplateId())
+		})
+	}
+}
+
+func TestPbWorkflowItemToActionWorkflowTemplateID(t *testing.T) {
+	testCases := []struct {
+		desc string
+		item *pb.WorkflowItem
+		want string
+	}{
+		{
+			desc: "unbound workflow leaves the template reference empty",
+			item: &pb.WorkflowItem{
+				Id:        "wf-id",
+				Name:      "my-workflow",
+				CreatedAt: timestamppb.Now(),
+			},
+			want: "",
+		},
+		{
+			desc: "template-backed workflow carries the template reference",
+			item: &pb.WorkflowItem{
+				Id:                 "wf-id",
+				Name:               "my-workflow",
+				CreatedAt:          timestamppb.Now(),
+				WorkflowTemplateId: "1b4c6f8a-2d3e-4f5a-8b9c-0d1e2f3a4b5c",
+			},
+			want: "1b4c6f8a-2d3e-4f5a-8b9c-0d1e2f3a4b5c",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.desc, func(t *testing.T) {
+			got := pbWorkflowItemToAction(tc.item)
+
+			assert.Equal(t, tc.want, got.WorkflowTemplateID)
+		})
+	}
+}

app/cli/pkg/action/workflow_list.go

@@ -38,6 +38,9 @@ type WorkflowItem struct {
 	ContractName           string           `json:"contractName,omitempty"`
 	ContractRevisionLatest int32            `json:"contractRevisionLatest,omitempty"`
 	LastRun                *WorkflowRunItem `json:"lastRun,omitempty"`
+	// WorkflowTemplateID is the platform workflow template this workflow is bound to,
+	// empty when it is not bound to any
+	WorkflowTemplateID string `json:"workflowTemplateId,omitempty"`
 }
 
 // WorkflowListResult holds the output of the workflow list action
@@ -106,6 +109,7 @@ func pbWorkflowItemToAction(wf *pb.WorkflowItem) *WorkflowItem {
 		ContractRevisionLatest: wf.ContractRevisionLatest,
 		LastRun:                pbWorkflowRunItemToAction(wf.LastRun),
 		Description:            wf.Description,
+		WorkflowTemplateID:     wf.WorkflowTemplateId,
 	}
 }
 

app/controlplane/api/controlplane/v1/response_messages.pb.go

@@ -42,6 +42,9 @@ message WorkflowItem {
   // is retained only for wire compatibility; it will be removed in a future release.
   bool public = 9 [deprecated = true];
   string description = 10;
+  // Optional reference to the platform workflow template this workflow was created from.
+  // Empty when the workflow is not bound to any template.
+  string workflow_template_id = 13;
 }
 
 message WorkflowRunItem {

app/controlplane/api/controlplane/v1/response_messages.proto

@@ -60,6 +60,14 @@ message WorkflowServiceCreateRequest {
   string description = 6;
   reserved 7;
   reserved "public";
+
+  // Optional reference to the platform workflow template this workflow is created from.
+  // Not dereferenced nor validated for existence in the control plane, it's an opaque
+  // reference to a platform-owned entity.
+  string workflow_template_id = 8 [
+    (buf.validate.field).ignore = IGNORE_IF_ZERO_VALUE,
+    (buf.validate.field).string.uuid = true
+  ];
 }
 
 message WorkflowServiceUpdateRequest {

app/controlplane/api/controlplane/v1/workflow.pb.go

@@ -0,0 +1,74 @@
+//
+// 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 v1_test
+
+import (
+	"testing"
+
+	"buf.build/go/protovalidate"
+	v1 "github.com/chainloop-dev/chainloop/app/controlplane/api/controlplane/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestWorkflowServiceCreateRequestWorkflowTemplateID(t *testing.T) {
+	testCases := []struct {
+		desc       string
+		templateID string
+		wantErr    bool
+	}{
+		{
+			desc:       "empty is allowed, the template reference is optional",
+			templateID: "",
+		},
+		{
+			desc:       "a valid UUID is accepted",
+			templateID: "1b4c6f8a-2d3e-4f5a-8b9c-0d1e2f3a4b5c",
+		},
+		{
+			desc:       "a non-UUID string is rejected",
+			templateID: "sast-scan",
+			wantErr:    true,
+		},
+		{
+			desc:       "a malformed UUID is rejected",
+			templateID: "1b4c6f8a-2d3e-4f5a-8b9c",
+			wantErr:    true,
+		},
+	}
+
+	validator, err := protovalidate.New()
+	require.NoError(t, err)
+
+	for _, tc := range testCases {
+		t.Run(tc.desc, func(t *testing.T) {
+			req := &v1.WorkflowServiceCreateRequest{
+				Name:               "my-workflow",
+				ProjectName:        "my-project",
+				WorkflowTemplateId: tc.templateID,
+			}
+
+			err := validator.Validate(req)
+			if tc.wantErr {
+				assert.Error(t, err)
+				assert.Contains(t, err.Error(), "workflow_template_id")
+				return
+			}
+
+			assert.NoError(t, err)
+		})
+	}
+}