Export changed files via builtin environment variables (#2935)

add **`CI_PIPELINE_FILES`** to builtin env vars

close  #853

---
*Sponsored by Kithara Software GmbH*

docs/docs/20-usage/50-environment.md

@@ -47,7 +47,7 @@ steps:
 This is the reference list of all environment variables available to your pipeline containers. These are injected into your pipeline step and plugins containers, at runtime.
 
 | NAME                             | Description                                                                                                        |
-| -------------------------------- | -------------------------------------------------------------------------------------------- |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | `CI`                             | CI environment name (value: `woodpecker`)                                                                          |
 |                                  | **Repository**                                                                                                     |
 | `CI_REPO`                        | repository full name `<owner>/<name>`                                                                              |
@@ -78,7 +78,7 @@ This is the reference list of all environment variables available to your pipeli
 |                                  | **Current pipeline**                                                                                               |
 | `CI_PIPELINE_NUMBER`             | pipeline number                                                                                                    |
 | `CI_PIPELINE_PARENT`             | number of parent pipeline                                                                                          |
-| `CI_PIPELINE_EVENT`              | pipeline event (push, pull_request, tag, deployment)                                         |
+| `CI_PIPELINE_EVENT`              | pipeline event (push, pull_request, tag, deployment, cron, manual)                                                 |
 | `CI_PIPELINE_URL`                | link to the web UI for the pipeline                                                                                |
 | `CI_PIPELINE_FORGE_URL`          | link to the forge's web UI for the commit(s) or tag that triggered the pipeline                                    |
 | `CI_PIPELINE_DEPLOY_TARGET`      | pipeline deploy target for `deployment` events (ie production)                                                     |
@@ -86,6 +86,7 @@ This is the reference list of all environment variables available to your pipeli
 | `CI_PIPELINE_CREATED`            | pipeline created UNIX timestamp                                                                                    |
 | `CI_PIPELINE_STARTED`            | pipeline started UNIX timestamp                                                                                    |
 | `CI_PIPELINE_FINISHED`           | pipeline finished UNIX timestamp                                                                                   |
+| `CI_PIPELINE_FILES`              | changed files (empty if event is not `push` or `pull_request`), it is undefined if more than 500 files are touched |
 |                                  | **Current workflow**                                                                                               |
 | `CI_WORKFLOW_NAME`               | workflow name                                                                                                      |
 |                                  | **Current step**                                                                                                   |

docs/versioned_docs/version-2.0/20-usage/50-environment.md

@@ -78,7 +78,7 @@ This is the reference list of all environment variables available to your pipeli
 |                                  | **Current pipeline**                                                                         |
 | `CI_PIPELINE_NUMBER`             | pipeline number                                                                              |
 | `CI_PIPELINE_PARENT`             | number of parent pipeline                                                                    |
-| `CI_PIPELINE_EVENT`              | pipeline event (push, pull_request, tag, deployment)                                         |
+| `CI_PIPELINE_EVENT`              | pipeline event (push, pull_request, tag, deployment, cron, manual)                           |
 | `CI_PIPELINE_URL`                | link to the web UI for the pipeline                                                          |
 | `CI_PIPELINE_FORGE_URL`          | link to the forge's web UI for the commit(s) or tag that triggered the pipeline              |
 | `CI_PIPELINE_DEPLOY_TARGET`      | pipeline deploy target for `deployment` events (ie production)                               |

pipeline/frontend/metadata/environment.go

@@ -15,6 +15,7 @@
 package metadata
 
 import (
+	"encoding/json"
 	"fmt"
 	"path"
 	"regexp"
@@ -22,7 +23,10 @@ import (
 	"strings"
 )
 
-var pullRegexp = regexp.MustCompile(`\d+`)
+var (
+	pullRegexp      = regexp.MustCompile(`\d+`)
+	maxChangedFiles = 500
+)
 
 // Environ returns the metadata as a map of environment variables.
 func (m *Metadata) Environ() map[string]string {
@@ -127,6 +131,15 @@ func (m *Metadata) Environ() map[string]string {
 		params["CI_COMMIT_PULL_REQUEST_LABELS"] = strings.Join(m.Curr.Commit.PullRequestLabels, ",")
 	}
 
+	// Only export changed files if maxChangedFiles is not exceeded
+	if len(m.Curr.Commit.ChangedFiles) == 0 {
+		params["CI_PIPELINE_FILES"] = "[]"
+	} else if len(m.Curr.Commit.ChangedFiles) <= maxChangedFiles {
+		// we have to use json, as other separators like ;, or space are valid filename chars
+		changedFiles, _ := json.Marshal(m.Curr.Commit.ChangedFiles)
+		params["CI_PIPELINE_FILES"] = string(changedFiles)
+	}
+
 	return params
 }
 

pipeline/frontend/metadata_test.go

@@ -74,7 +74,7 @@ func TestMetadataFromStruct(t *testing.T) {
 				"CI_COMMIT_AUTHOR": "", "CI_COMMIT_AUTHOR_AVATAR": "", "CI_COMMIT_AUTHOR_EMAIL": "", "CI_COMMIT_BRANCH": "",
 				"CI_COMMIT_MESSAGE": "", "CI_COMMIT_PULL_REQUEST": "", "CI_COMMIT_PULL_REQUEST_LABELS": "", "CI_COMMIT_REF": "", "CI_COMMIT_REFSPEC": "", "CI_COMMIT_SHA": "", "CI_COMMIT_SOURCE_BRANCH": "",
 				"CI_COMMIT_TAG": "", "CI_COMMIT_TARGET_BRANCH": "", "CI_COMMIT_URL": "", "CI_FORGE_TYPE": "", "CI_FORGE_URL": "",
-				"CI_PIPELINE_CREATED": "0", "CI_PIPELINE_DEPLOY_TARGET": "", "CI_PIPELINE_EVENT": "", "CI_PIPELINE_FINISHED": "0", "CI_PIPELINE_NUMBER": "0",
+				"CI_PIPELINE_CREATED": "0", "CI_PIPELINE_DEPLOY_TARGET": "", "CI_PIPELINE_EVENT": "", "CI_PIPELINE_FINISHED": "0", "CI_PIPELINE_FILES": "[]", "CI_PIPELINE_NUMBER": "0",
 				"CI_PIPELINE_PARENT": "0", "CI_PIPELINE_STARTED": "0", "CI_PIPELINE_STATUS": "", "CI_PIPELINE_URL": "/repos/0/pipeline/0", "CI_PIPELINE_FORGE_URL": "",
 				"CI_PREV_COMMIT_AUTHOR": "", "CI_PREV_COMMIT_AUTHOR_AVATAR": "", "CI_PREV_COMMIT_AUTHOR_EMAIL": "", "CI_PREV_COMMIT_BRANCH": "",
 				"CI_PREV_COMMIT_MESSAGE": "", "CI_PREV_COMMIT_REF": "", "CI_PREV_COMMIT_REFSPEC": "", "CI_PREV_COMMIT_SHA": "", "CI_PREV_COMMIT_URL": "", "CI_PREV_PIPELINE_CREATED": "0",
@@ -89,7 +89,7 @@ func TestMetadataFromStruct(t *testing.T) {
 			name:     "Test with forge",
 			forge:    forge,
 			repo:     &model.Repo{FullName: "testUser/testRepo", ForgeURL: "https://gitea.com/testUser/testRepo", Clone: "https://gitea.com/testUser/testRepo.git", CloneSSH: "git@gitea.com:testUser/testRepo.git", Branch: "main", IsSCMPrivate: true},
-			pipeline: &model.Pipeline{Number: 3},
+			pipeline: &model.Pipeline{Number: 3, ChangedFiles: []string{"test.go", "markdown file.md"}},
 			last:     &model.Pipeline{Number: 2},
 			workflow: &model.Workflow{Name: "hello"},
 			sysURL:   "https://example.com",
@@ -97,7 +97,10 @@ func TestMetadataFromStruct(t *testing.T) {
 				Forge: metadata.Forge{Type: "gitea", URL: "https://gitea.com"},
 				Sys:   metadata.System{Name: "woodpecker", Host: "example.com", URL: "https://example.com"},
 				Repo:  metadata.Repo{Owner: "testUser", Name: "testRepo", ForgeURL: "https://gitea.com/testUser/testRepo", CloneURL: "https://gitea.com/testUser/testRepo.git", CloneSSHURL: "git@gitea.com:testUser/testRepo.git", Branch: "main", Private: true},
-				Curr:     metadata.Pipeline{Number: 3},
+				Curr: metadata.Pipeline{
+					Number: 3,
+					Commit: metadata.Commit{ChangedFiles: []string{"test.go", "markdown file.md"}},
+				},
 				Prev:     metadata.Pipeline{Number: 2},
 				Workflow: metadata.Workflow{Name: "hello"},
 			},
@@ -106,7 +109,7 @@ func TestMetadataFromStruct(t *testing.T) {
 				"CI_COMMIT_AUTHOR": "", "CI_COMMIT_AUTHOR_AVATAR": "", "CI_COMMIT_AUTHOR_EMAIL": "", "CI_COMMIT_BRANCH": "",
 				"CI_COMMIT_MESSAGE": "", "CI_COMMIT_PULL_REQUEST": "", "CI_COMMIT_PULL_REQUEST_LABELS": "", "CI_COMMIT_REF": "", "CI_COMMIT_REFSPEC": "", "CI_COMMIT_SHA": "", "CI_COMMIT_SOURCE_BRANCH": "",
 				"CI_COMMIT_TAG": "", "CI_COMMIT_TARGET_BRANCH": "", "CI_COMMIT_URL": "", "CI_FORGE_TYPE": "gitea", "CI_FORGE_URL": "https://gitea.com",
-				"CI_PIPELINE_CREATED": "0", "CI_PIPELINE_DEPLOY_TARGET": "", "CI_PIPELINE_EVENT": "", "CI_PIPELINE_FINISHED": "0",
+				"CI_PIPELINE_CREATED": "0", "CI_PIPELINE_DEPLOY_TARGET": "", "CI_PIPELINE_EVENT": "", "CI_PIPELINE_FINISHED": "0", "CI_PIPELINE_FILES": `["test.go","markdown file.md"]`,
 				"CI_PIPELINE_NUMBER": "3", "CI_PIPELINE_PARENT": "0", "CI_PIPELINE_STARTED": "0", "CI_PIPELINE_STATUS": "", "CI_PIPELINE_URL": "https://example.com/repos/0/pipeline/3", "CI_PIPELINE_FORGE_URL": "",
 				"CI_PREV_COMMIT_AUTHOR": "", "CI_PREV_COMMIT_AUTHOR_AVATAR": "", "CI_PREV_COMMIT_AUTHOR_EMAIL": "", "CI_PREV_COMMIT_BRANCH": "",
 				"CI_PREV_COMMIT_MESSAGE": "", "CI_PREV_COMMIT_REF": "", "CI_PREV_COMMIT_REFSPEC": "", "CI_PREV_COMMIT_SHA": "", "CI_PREV_COMMIT_URL": "", "CI_PREV_PIPELINE_CREATED": "0",