feat!: protect against stale queue items

item.go

@@ -9,20 +9,29 @@ import (
 	"github.com/go-vela/types/pipeline"
 )
 
+// ItemVersion allows the worker to detect items that were queued before an Vela server
+// upgrade or downgrade, so it can handle such stale data gracefully.
+// For example, the worker could fail a stale build or ask the server to recompile it.
+// This is not a public API and is unrelated to the version key in pipeline yaml.
+const ItemVersion uint64 = 1
+
 // Item is the queue representation of an item to publish to the queue.
 type Item struct {
 	Build    *library.Build  `json:"build"`
 	Pipeline *pipeline.Build `json:"pipeline"`
 	Repo     *library.Repo   `json:"repo"`
 	User     *library.User   `json:"user"`
+	// The 0-value is the implicit ItemVersion for queued Items that pre-date adding the field.
+	ItemVersion uint64 `json:"item_version"`
 }
 
 // ToItem creates a queue item from a pipeline, build, repo and user.
 func ToItem(p *pipeline.Build, b *library.Build, r *library.Repo, u *library.User) *Item {
 	return &Item{
-		Pipeline: p,
-		Build:    b,
-		Repo:     r,
-		User:     u,
+		Pipeline:    p,
+		Build:       b,
+		Repo:        r,
+		User:        u,
+		ItemVersion: ItemVersion,
 	}
 }

item_test.go

@@ -159,6 +159,7 @@ func TestTypes_ToItem(t *testing.T) {
 			Active: &booL,
 			Admin:  &booL,
 		},
+		ItemVersion: ItemVersion,
 	}
 
 	// run test