Repository: akuity/kargo

Issue:
make promoter info (username and email, at least) available in expressions
# Checklist

* [ X] I've searched the issue queue to verify this is not a duplicate feature request.
* [ X] I've pasted the output of `kargo version`, if applicable.
* [ X] I've pasted logs, if applicable.

# Proposed Feature

When currently using the `git-commit` promotion step, the commits are done with the default user `kargo` (if no explicit `author.name` is set). If a promotion is done manually, it would be useful that this becomes `kargo-$logged-in-user` (such as kargo-admin, in case you log in with the admin account). In the promotion history you can already see who initiated the promotion, but in the git commit log itself there is no trace of it.

# Motivation

This would enable to easily see who initiated a git commit from within kargo.




Discussion:
@krancour: I think the most sensible thing here might be to make promoter information available within expressions, so you can dynamically populate the existing author info fields.@creeram: @Sebast1aan Do you have any updates on when this feature might be implemented?@krancour: @creeram I believe @Sebast1aan was making a feature request and not _necessarily_ volunteering to implement the feature. This is assigned to myself, but isn't currently regarded as a priority.@creeram: @krancour  I'm waiting for this feature to be implemented so I can use it in my configuration. This will allow us to get details in Slack about who performed the release and in which environment. I would appreciate it if you could start working on this.@krancour: @creeram our priorities aren't _dictated_ by your needs. If you need this so urgently, you can take a crack at implementing it. Would you like me to assign it to you?@creeram: @krancour Thank you for your response. I completely understand that open-source projects have their own priorities. However, I’d like to mention that not all users are developers or have the skills to contribute code. I appreciate the work you do and just wanted to share that a little understanding in responses can go a long way.@keithfz: @krancour I can take a look into this if no one else is looking at it. I have a similar desire for this functionality.

For implementation, I see that there is already the annotation for `kargo.akuity.io/create-actor` -- would it suffice / be acceptable to simply propagate that to the well-known expression ctx? I'm a bit of a beginner to this codebase :)@krancour: This approach won't yield a lot of detail, but sounds like it is probably a good starting point. cc @hiddeco for some further validation.@krancour: I believe this was resolved by #3592 

Solution patch:
diff --git a/docs/docs/50-user-guide/60-reference-docs/40-expressions.md b/docs/docs/50-user-guide/60-reference-docs/40-expressions.md
index 3c52c4bc..622db3bd 100644
--- a/docs/docs/50-user-guide/60-reference-docs/40-expressions.md
+++ b/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
 
diff --git a/internal/controller/promotions/promotions.go b/internal/controller/promotions/promotions.go
index 4b1119e7..d6540e50 100644
--- a/internal/controller/promotions/promotions.go
+++ b/internal/controller/promotions/promotions.go
@@ -6,6 +6,7 @@ import (
 	"os"
 	"path/filepath"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/kelseyhightower/envconfig"
@@ -491,6 +492,7 @@ func (r *reconciler) promote(
 		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 @@ func (r *reconciler) terminatePromotion(
 
 	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
+}
diff --git a/internal/promotion/promotion.go b/internal/promotion/promotion.go
index 214bc443..fe4f34f8 100644
--- a/internal/promotion/promotion.go
+++ b/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,
+				},
+			},
 		},
 	}
 



Test patch:
diff --git a/internal/controller/promotions/promotions_test.go b/internal/controller/promotions/promotions_test.go
index f2ef96cb..09aded66 100644
--- a/internal/controller/promotions/promotions_test.go
+++ b/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,
diff --git a/internal/promotion/promotion_test.go b/internal/promotion/promotion_test.go
index c721d5ce..fbf669a0 100644
--- a/internal/promotion/promotion_test.go
+++ b/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",
 			},
 		},
 		{