feat: add actor metadata to Promotion context

docs/docs/50-user-guide/60-reference-docs/40-expressions.md

@@ -143,12 +143,26 @@ Expect other useful variables to be added in the future.
 
 | Name | Type | Description |
 |------|------|-------------|
-| `ctx` | `object` | `string` fields `project`, `stage`, and `promotion` provide convenient access to details of a `Promotion`. |
+| `ctx` | `object` | Contains contextual information about the promotion. See detailed structure below. |
 | `outputs` | `object` | A map of output from previous promotion steps indexed by step aliases. |
 | `secrets` | `object` | A map of maps indexed by the names of all Kubernetes `Secret`s in the `Promotion`'s `Project` and the keys within the `Data` block of each. |
 | `vars` | `object` | A user-defined map of variable names to static values of any type. The map is derived from a `Promotion`'s `spec.promotionTemplate.spec.vars` field. Variable names must observe standard Go variable-naming rules. Variables values may, themselves, be defined using an expression. `vars` (contains previously defined variables) and `ctx` are available to expressions defining the values of variables, however, `outputs` and `secrets` are not. |
 | `task` | `object` | A map containing output from previous steps within the same PromotionTask under the `outputs` field, indexed by step aliases. Only available within `(Cluster)PromotionTask` steps. |
 
+#### Context (`ctx`) Object Structure
+
+The `ctx` object has the following structure:
+
+```
+ctx
+├── project: string       # The name of the Project
+├── stage: string         # The name of the Stage
+├── promotion: string     # The name of the Promotion
+└── meta
+    └── promotion
+        └── actor: string # The creator of the Promotion
+```
+
 The following example promotion process clones a repository and checks out
 two branches to different directories, uses Kustomize with source from one
 branch to render some Kubernetes manifests that it commits to the other branch,
@@ -220,7 +234,17 @@ definition of the static variables).
 
 | Name | Type | Description |
 |------|------|-------------|
-| `ctx` | `object` | `string` fields `project` and `stage` provide convenient access to details of a `Stage`. |
+| `ctx` | `object` | Contains contextual information about the stage. See structure below. |
+
+#### Context (`ctx`) Object Structure for Verification
+
+The `ctx` object for verification has the following structure:
+
+```
+ctx
+├── project: string  # The name of the Project
+└── stage: string    # The name of the Stage
+```
 
 ## Functions
 

internal/controller/promotions/promotions.go

@@ -6,6 +6,7 @@
 	"os"
 	"path/filepath"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/kelseyhightower/envconfig"
@@ -491,6 +492,7 @@
 		StepExecutionMetadata: promo.Status.StepExecutionMetadata,
 		State:                 pkgPromotion.State(workingPromo.Status.GetState()),
 		Vars:                  workingPromo.Spec.Vars,
+		Actor:                 parseCreateActorAnnotation(&promo),
 	}
 	if err := os.Mkdir(promoCtx.WorkDir, 0o700); err == nil {
 		// If we're working with a fresh directory, we should start the promotion
@@ -646,3 +648,20 @@
 
 	return nil
 }
+
+// parseCreateActorAnnotation extracts the v1alpha1.AnnotationKeyCreateActor
+// value from the Promotion's annotations and returns it. If the value contains
+// a colon, it is split and the second part is returned. Otherwise, the entire
+// value or an empty string is returned.
+func parseCreateActorAnnotation(promo *kargoapi.Promotion) string {
+	var creator string
+	if v, ok := promo.Annotations[kargoapi.AnnotationKeyCreateActor]; ok {
+		if v != kargoapi.EventActorUnknown {
+			creator = v
+		}
+		if parts := strings.Split(v, ":"); len(parts) == 2 {
+			creator = parts[1]
+		}
+	}
+	return creator
+}

internal/controller/promotions/promotions_test.go

@@ -3,6 +3,7 @@ package promotions
 import (
 	"context"
 	"errors"
+	"fmt"
 	"testing"
 	"time"
 
@@ -462,6 +463,74 @@ func Test_reconciler_terminatePromotion(t *testing.T) {
 	}
 }
 
+func Test_parseCreateActorAnnotation(t *testing.T) {
+	tests := []struct {
+		name  string
+		promo *kargoapi.Promotion
+		want  string
+	}{
+		{
+			name: "basic case",
+			promo: &kargoapi.Promotion{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "fake-promo",
+					Namespace: "fake-namespace",
+					Annotations: map[string]string{
+						kargoapi.AnnotationKeyCreateActor: fmt.Sprintf(
+							"%s%s", kargoapi.EventActorEmailPrefix, "fake-actor",
+						),
+					},
+				},
+			},
+			want: "fake-actor",
+		},
+		{
+			name: "single element",
+			promo: &kargoapi.Promotion{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "fake-promo",
+					Namespace: "fake-namespace",
+					Annotations: map[string]string{
+						kargoapi.AnnotationKeyCreateActor: kargoapi.EventActorAdmin,
+					},
+				},
+			},
+			want: kargoapi.EventActorAdmin,
+		},
+		{
+			name: "unknown actor",
+			promo: &kargoapi.Promotion{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "fake-promo",
+					Namespace: "fake-namespace",
+					Annotations: map[string]string{
+						kargoapi.AnnotationKeyCreateActor: kargoapi.EventActorUnknown,
+					},
+				},
+			},
+			want: "",
+		},
+		{
+
+			name: "no annotation",
+			promo: &kargoapi.Promotion{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "fake-promo",
+					Namespace: "fake-namespace",
+				},
+			},
+			want: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := parseCreateActorAnnotation(tt.promo)
+			require.Equal(t, tt.want, result)
+		})
+	}
+}
+
 // nolint: unparam
 func newPromo(namespace, name, stage string,
 	phase kargoapi.PromotionPhase,

internal/promotion/promotion.go

@@ -57,6 +57,8 @@ type Context struct {
 	Vars []kargoapi.PromotionVariable
 	// Secrets is a map of secrets that can be used by the Steps.
 	Secrets map[string]map[string]string
+	// Actor is the name of the actor triggering the Promotion.
+	Actor string
 }
 
 // Step describes a single step in a user-defined promotion process. Steps are
@@ -166,6 +168,11 @@ func (s *Step) BuildEnv(promoCtx Context, opts ...StepEnvOption) map[string]any
 			"project":   promoCtx.Project,
 			"promotion": promoCtx.Promotion,
 			"stage":     promoCtx.Stage,
+			"meta": map[string]any{
+				"promotion": map[string]any{
+					"actor": promoCtx.Actor,
+				},
+			},
 		},
 	}
 

internal/promotion/promotion_test.go

@@ -147,16 +147,19 @@ func TestStep_GetConfig(t *testing.T) {
 				Project:   "fake-project",
 				Stage:     "fake-stage",
 				Promotion: "fake-promotion",
+				Actor:     "fake-creator",
 			},
 			rawCfg: []byte(`{
 				"project": "${{ ctx.project }}",
 				"stage": "${{ ctx.stage }}",
-				"promotion": "${{ ctx.promotion }}"
+				"promotion": "${{ ctx.promotion }}",
+				"actor": "${{ ctx.meta.promotion.actor }}"
 			}`),
 			expectedCfg: promotion.Config{
 				"project":   "fake-project",
 				"stage":     "fake-stage",
 				"promotion": "fake-promotion",
+				"actor":     "fake-creator",
 			},
 		},
 		{