feat(stage): add environment field

pipeline/stage.go

@@ -5,6 +5,8 @@
 package pipeline
 
 import (
+	"fmt"
+
 	"github.com/go-vela/types/constants"
 )
 
@@ -20,10 +22,11 @@ type (
 	//
 	// swagger:model PipelineStage
 	Stage struct {
-		Done  chan error     `json:"-"               yaml:"-"`
-		Name  string         `json:"name,omitempty"  yaml:"name,omitempty"`
-		Needs []string       `json:"needs,omitempty" yaml:"needs,omitempty"`
-		Steps ContainerSlice `json:"steps,omitempty" yaml:"steps,omitempty"`
+		Done        chan error        `json:"-"                     yaml:"-"`
+		Environment map[string]string `json:"environment,omitempty" yaml:"environment,omitempty"`
+		Name        string            `json:"name,omitempty"        yaml:"name,omitempty"`
+		Needs       []string          `json:"needs,omitempty"       yaml:"needs,omitempty"`
+		Steps       ContainerSlice    `json:"steps,omitempty"       yaml:"steps,omitempty"`
 	}
 )
 
@@ -105,3 +108,51 @@ func (s *StageSlice) Sanitize(driver string) *StageSlice {
 		return nil
 	}
 }
+
+// Empty returns true if the provided stage is empty.
+func (s *Stage) Empty() bool {
+	// return true if the stage is nil
+	if s == nil {
+		return true
+	}
+
+	// return true if every stage field is empty
+	if len(s.Name) == 0 &&
+		len(s.Needs) == 0 &&
+		len(s.Steps) == 0 &&
+		len(s.Environment) == 0 {
+		return true
+	}
+
+	// return false if any of the stage fields are not empty
+	return false
+}
+
+// MergeEnv takes a list of environment variables and attempts
+// to set them in the stage environment. If the environment
+// variable already exists in the stage, then this will
+// overwrite the existing environment variable.
+func (s *Stage) MergeEnv(environment map[string]string) error {
+	// check if the stage is empty
+	if s.Empty() {
+		// TODO: evaluate if we should error here
+		//
+		// immediately return and do nothing
+		//
+		// treated as a no-op
+		return nil
+	}
+
+	// check if the environment provided is empty
+	if environment == nil {
+		return fmt.Errorf("empty environment provided for stage %s", s.Name)
+	}
+
+	// iterate through all environment variables provided
+	for key, value := range environment {
+		// set or update the stage environment variable
+		s.Environment[key] = value
+	}
+
+	return nil
+}

pipeline/stage_test.go

@@ -104,10 +104,64 @@ func TestPipeline_StageSlice_Sanitize(t *testing.T) {
 	}
 }
 
+func TestPipeline_Stage_MergeEnv(t *testing.T) {
+	// setup tests
+	tests := []struct {
+		stage       *Stage
+		environment map[string]string
+		failure     bool
+	}{
+		{
+			stage: &Stage{
+				Name:        "testStage",
+				Environment: map[string]string{"FOO": "bar"},
+			},
+			environment: map[string]string{"BAR": "baz"},
+			failure:     false,
+		},
+		{
+			stage:       &Stage{},
+			environment: map[string]string{"BAR": "baz"},
+			failure:     false,
+		},
+		{
+			stage:       nil,
+			environment: map[string]string{"BAR": "baz"},
+			failure:     false,
+		},
+		{
+			stage: &Stage{
+				Environment: map[string]string{"FOO": "bar"},
+				Name:        "testStage",
+			},
+			environment: nil,
+			failure:     true,
+		},
+	}
+
+	// run tests
+	for _, test := range tests {
+		err := test.stage.MergeEnv(test.environment)
+
+		if test.failure {
+			if err == nil {
+				t.Errorf("MergeEnv should have returned err")
+			}
+
+			continue
+		}
+
+		if err != nil {
+			t.Errorf("MergeEnv returned err: %v", err)
+		}
+	}
+}
+
 func testStages() *StageSlice {
 	return &StageSlice{
 		{
-			Name: "init",
+			Name:        "init",
+			Environment: map[string]string{"FOO": "bar"},
 			Steps: ContainerSlice{
 				{
 					ID:          "github octocat._1_init_init",
@@ -121,8 +175,9 @@ func testStages() *StageSlice {
 			},
 		},
 		{
-			Name:  "clone",
-			Needs: []string{"init"},
+			Name:        "clone",
+			Needs:       []string{"init"},
+			Environment: map[string]string{"FOO": "bar"},
 			Steps: ContainerSlice{
 				{
 					ID:          "github octocat._1_clone_clone",
@@ -136,8 +191,9 @@ func testStages() *StageSlice {
 			},
 		},
 		{
-			Name:  "echo",
-			Needs: []string{"clone"},
+			Name:        "echo",
+			Needs:       []string{"clone"},
+			Environment: map[string]string{"FOO": "bar"},
 			Steps: ContainerSlice{
 				{
 					ID:          "github octocat._1_echo_echo",

yaml/stage.go

@@ -22,9 +22,10 @@ type (
 	// of a stage in a pipeline.
 	// nolint:lll // jsonschema will cause long lines
 	Stage struct {
-		Name  string          `yaml:"name,omitempty"  json:"name,omitempty"  jsonschema:"minLength=1,description=Unique identifier for the stage in the pipeline.\nReference: https://go-vela.github.io/docs/reference/yaml/stages/#the-name-tag"`
-		Needs raw.StringSlice `yaml:"needs,omitempty,flow" json:"needs,omitempty" jsonschema:"description=Stages that must complete before starting the current one.\nReference: https://go-vela.github.io/docs/reference/yaml/stages/#the-needs-tag"`
-		Steps StepSlice       `yaml:"steps,omitempty" json:"steps,omitempty" jsonschema:"required,description=Sequential execution instructions for the stage.\nReference: https://go-vela.github.io/docs/reference/yaml/stages/#the-steps-tag"`
+		Environment raw.StringSliceMap `yaml:"environment,omitempty" json:"environment,omitempty" jsonschema:"description=Provide environment variables injected into the container environment.\nReference: https://go-vela.github.io/docs/reference/yaml/stages/#the-environment-tag"`
+		Name        string             `yaml:"name,omitempty"        json:"name,omitempty"        jsonschema:"minLength=1,description=Unique identifier for the stage in the pipeline.\nReference: https://go-vela.github.io/docs/reference/yaml/stages/#the-name-tag"`
+		Needs       raw.StringSlice    `yaml:"needs,omitempty,flow"  json:"needs,omitempty"       jsonschema:"description=Stages that must complete before starting the current one.\nReference: https://go-vela.github.io/docs/reference/yaml/stages/#the-needs-tag"`
+		Steps       StepSlice          `yaml:"steps,omitempty"       json:"steps,omitempty"       jsonschema:"required,description=Sequential execution instructions for the stage.\nReference: https://go-vela.github.io/docs/reference/yaml/stages/#the-steps-tag"`
 	}
 )
 
@@ -38,10 +39,11 @@ func (s *StageSlice) ToPipeline() *pipeline.StageSlice {
 	for _, stage := range *s {
 		// append the element to the pipeline stage slice
 		*stageSlice = append(*stageSlice, &pipeline.Stage{
-			Done:  make(chan error, 1),
-			Name:  stage.Name,
-			Needs: stage.Needs,
-			Steps: *stage.Steps.ToPipeline(),
+			Done:        make(chan error, 1),
+			Environment: stage.Environment,
+			Name:        stage.Name,
+			Needs:       stage.Needs,
+			Steps:       *stage.Steps.ToPipeline(),
 		})
 	}
 
@@ -120,3 +122,32 @@ func (s StageSlice) MarshalYAML() (interface{}, error) {
 
 	return output, nil
 }
+
+// MergeEnv takes a list of environment variables and attempts
+// to set them in the stage environment. If the environment
+// variable already exists in the stage, than this will
+// overwrite the existing environment variable.
+func (s *Stage) MergeEnv(environment map[string]string) error {
+	// check if the stage is empty
+	if s == nil || s.Environment == nil {
+		// TODO: evaluate if we should error here
+		//
+		// immediately return and do nothing
+		//
+		// treated as a no-op
+		return nil
+	}
+
+	// check if the environment provided is empty
+	if environment == nil {
+		return fmt.Errorf("empty environment provided for stage %s", s.Name)
+	}
+
+	// iterate through all environment variables provided
+	for key, value := range environment {
+		// set or update the stage environment variable
+		s.Environment[key] = value
+	}
+
+	return nil
+}

yaml/stage_test.go

@@ -190,6 +190,9 @@ func TestYaml_StageSlice_UnmarshalYAML(t *testing.T) {
 				{
 					Name:  "dependencies",
 					Needs: []string{"clone"},
+					Environment: map[string]string{
+						"STAGE_ENV_VAR": "stage",
+					},
 					Steps: StepSlice{
 						{
 							Commands: []string{"./gradlew downloadDependencies"},
@@ -206,6 +209,10 @@ func TestYaml_StageSlice_UnmarshalYAML(t *testing.T) {
 				{
 					Name:  "test",
 					Needs: []string{"dependencies", "clone"},
+					Environment: map[string]string{
+						"STAGE_ENV_VAR":    "stage",
+						"SECOND_STAGE_ENV": "stage2",
+					},
 					Steps: StepSlice{
 						{
 							Commands: []string{"./gradlew check"},
@@ -222,6 +229,9 @@ func TestYaml_StageSlice_UnmarshalYAML(t *testing.T) {
 				{
 					Name:  "build",
 					Needs: []string{"dependencies", "clone"},
+					Environment: map[string]string{
+						"STAGE_ENV_VAR": "stage",
+					},
 					Steps: StepSlice{
 						{
 							Commands: []string{"./gradlew build"},
@@ -403,3 +413,56 @@ func TestYaml_StageSlice_MarshalYAML(t *testing.T) {
 		}
 	}
 }
+
+func TestYaml_Stage_MergeEnv(t *testing.T) {
+	// setup tests
+	tests := []struct {
+		stage       *Stage
+		environment map[string]string
+		failure     bool
+	}{
+		{
+			stage: &Stage{
+				Environment: map[string]string{"FOO": "bar"},
+				Name:        "testStage",
+			},
+			environment: map[string]string{"BAR": "baz"},
+			failure:     false,
+		},
+		{
+			stage:       &Stage{},
+			environment: map[string]string{"BAR": "baz"},
+			failure:     false,
+		},
+		{
+			stage:       nil,
+			environment: map[string]string{"BAR": "baz"},
+			failure:     false,
+		},
+		{
+			stage: &Stage{
+				Environment: map[string]string{"FOO": "bar"},
+				Name:        "testStage",
+			},
+			environment: nil,
+			failure:     true,
+		},
+	}
+
+	// run tests
+	for _, test := range tests {
+		err := test.stage.MergeEnv(test.environment)
+
+		if test.failure {
+			if err == nil {
+				t.Errorf("MergeEnv should have returned err")
+			}
+
+			continue
+		}
+
+		if err != nil {
+			t.Errorf("MergeEnv returned err: %v", err)
+		}
+	}
+}

yaml/testdata/stage.yml

@@ -1,5 +1,7 @@
 ---
 dependencies:
+  environment:
+      STAGE_ENV_VAR: stage
   steps:
     - name: install
       commands:
@@ -12,6 +14,9 @@ dependencies:
 
 test:
   needs: [ dependencies ]
+  environment:
+      STAGE_ENV_VAR: stage
+      SECOND_STAGE_ENV: stage2
   steps:
     - name: test
       commands:
@@ -24,6 +29,8 @@ test:
 
 build:
   needs: [ dependencies ]
+  environment:
+      STAGE_ENV_VAR: stage
   steps:
     - name: build
       commands: