Merge pull request #3759 from markmssd/buildkite-hooks-shell

DrJosh9000 · web-flow · commit 27ca920be9df · 2026-04-13T12:14:22.000+10:00
Support PowerShell 7
diff --git a/agent/agent_configuration.go b/agent/agent_configuration.go
@@ -63,6 +63,7 @@ type AgentConfiguration struct {
 	WriteJobLogsToStdout         bool
 	LogFormat                    string
 	Shell                        string
+	HooksShell                   string
 	Profile                      string
 	RedactedVars                 []string
 	AcquireJob                   string
diff --git a/agent/job_runner.go b/agent/job_runner.go
@@ -442,6 +442,7 @@ BUILDKITE_LOCAL_HOOKS_ENABLED
 BUILDKITE_PLUGINS_ENABLED
 BUILDKITE_REDACTED_VARS
 BUILDKITE_SHELL
+BUILDKITE_HOOKS_SHELL
 BUILDKITE_SIGNAL_GRACE_PERIOD_SECONDS
 BUILDKITE_SSH_KEYSCAN
 BUILDKITE_STRICT_SINGLE_HOOKS
@@ -577,6 +578,7 @@ BUILDKITE_AGENT_JWKS_KEY_ID`
 	setEnv("BUILDKITE_GIT_SUBMODULE_CLONE_CONFIG", strings.Join(r.conf.AgentConfiguration.GitSubmoduleCloneConfig, ","))
 
 	setEnv("BUILDKITE_SHELL", r.conf.AgentConfiguration.Shell)
+	setEnv("BUILDKITE_HOOKS_SHELL", r.conf.AgentConfiguration.HooksShell)
 	setEnv("BUILDKITE_AGENT_EXPERIMENT", strings.Join(experiments.Enabled(ctx), ","))
 	setEnv("BUILDKITE_REDACTED_VARS", strings.Join(r.conf.AgentConfiguration.RedactedVars, ","))
 	setEnv("BUILDKITE_STRICT_SINGLE_HOOKS", fmt.Sprint(r.conf.AgentConfiguration.StrictSingleHooks))
@@ -745,7 +747,7 @@ func (r *JobRunner) executePreBootstrapHook(ctx context.Context, hook string) (b
 	environ.Set("BUILDKITE_AGENT_DEBUG", fmt.Sprint(r.conf.Debug))
 	environ.Set("BUILDKITE_AGENT_DEBUG_HTTP", fmt.Sprint(r.conf.DebugHTTP))
 
-	script, err := sh.Script(hook)
+	script, err := sh.Script(hook, r.conf.AgentConfiguration.HooksShell)
 	if err != nil {
 		r.agentLogger.Error("Finished pre-bootstrap hook %q: script not runnable: %v", hook, err)
 		return false, err
diff --git a/clicommand/agent_start.go b/clicommand/agent_start.go
@@ -134,6 +134,7 @@ type AgentStartConfig struct {
 	PluginsPath          string   `cli:"plugins-path" normalize:"filepath"`
 
 	Shell           string `cli:"shell"`
+	HooksShell      string `cli:"hooks-shell"`
 	BootstrapScript string `cli:"bootstrap-script" normalize:"commandpath"`
 	NoPTY           bool   `cli:"no-pty"`
 
@@ -306,7 +307,7 @@ func (asc AgentStartConfig) Features(ctx context.Context) []string {
 }
 
 func DefaultShell() string {
-	// https://github.com/golang/go/blob/master/src/go/build/syslist.go#L7
+	// https://github.com/golang/go/blob/master/src/internal/syslist/syslist.go#L17
 	switch runtime.GOOS {
 	case "windows":
 		return `C:\Windows\System32\CMD.exe /S /C`
@@ -434,6 +435,11 @@ var AgentStartCommand = cli.Command{
 			Usage:  "The shell command used to interpret build commands, e.g /bin/bash -e -c",
 			EnvVar: "BUILDKITE_SHELL",
 		},
+		cli.StringFlag{
+			Name:   "hooks-shell",
+			Usage:  "The shell command used to interpret hooks commands, e.g pwsh -Command",
+			EnvVar: "BUILDKITE_HOOKS_SHELL",
+		},
 		cli.StringFlag{
 			Name:   "queue",
 			Usage:  "The queue the agent will listen to for jobs. If not set, the agent will use the default queue. Overwrites the queue tag in the agent's tags",
@@ -1071,6 +1077,7 @@ var AgentStartCommand = cli.Command{
 			WriteJobLogsToStdout:         cfg.WriteJobLogsToStdout,
 			LogFormat:                    cfg.LogFormat,
 			Shell:                        cfg.Shell,
+			HooksShell:                   cfg.HooksShell,
 			RedactedVars:                 cfg.RedactedVars,
 			AcquireJob:                   cfg.AcquireJob,
 			TracingBackend:               cfg.TracingBackend,
@@ -1548,7 +1555,7 @@ func agentLifecycleHook(hookName string, log logger.Logger, cfg AgentStartConfig
 
 	// run hooks
 	for _, p = range hooks {
-		script, err := sh.Script(p)
+		script, err := sh.Script(p, cfg.HooksShell)
 		if err != nil {
 			log.Error("%q hook: %v", hookName, err)
 			return err
diff --git a/clicommand/bootstrap.go b/clicommand/bootstrap.go
@@ -97,6 +97,7 @@ type BootstrapConfig struct {
 	LogLevel                     string   `cli:"log-level"`
 	Debug                        bool     `cli:"debug"`
 	Shell                        string   `cli:"shell"`
+	HooksShell                   string   `cli:"hooks-shell"`
 	Experiments                  []string `cli:"experiment" normalize:"list"`
 	Phases                       []string `cli:"phases" normalize:"list"`
 	Profile                      string   `cli:"profile"`
@@ -306,6 +307,11 @@ var BootstrapCommand = cli.Command{
 			EnvVar: "BUILDKITE_SHELL",
 			Value:  DefaultShell(),
 		},
+		cli.StringFlag{
+			Name:   "hooks-shell",
+			Usage:  "The shell to use to interpret hooks commands",
+			EnvVar: "BUILDKITE_HOOKS_SHELL",
+		},
 		cli.StringSliceFlag{
 			Name:   "phases",
 			Usage:  "The specific phases to execute. The order they're defined is irrelevant.",
@@ -460,6 +466,7 @@ var BootstrapCommand = cli.Command{
 			RunInPty:                     runInPty,
 			SSHKeyscan:                   cfg.SSHKeyscan,
 			Shell:                        cfg.Shell,
+			HooksShell:                   cfg.HooksShell,
 			StrictSingleHooks:            cfg.StrictSingleHooks,
 			Tag:                          cfg.Tag,
 			TracingBackend:               cfg.TracingBackend,
diff --git a/env/environment.go b/env/environment.go
@@ -363,6 +363,7 @@ var ProtectedEnv = map[string]struct{}{
 	"BUILDKITE_PLUGINS_ENABLED":          {},
 	"BUILDKITE_PLUGINS_PATH":             {},
 	"BUILDKITE_SHELL":                    {},
+	"BUILDKITE_HOOKS_SHELL":              {},
 	"BUILDKITE_SSH_KEYSCAN":              {},
 }
 
diff --git a/env/environment_test.go b/env/environment_test.go
@@ -303,6 +303,7 @@ func TestProtectedEnv(t *testing.T) {
 		"BUILDKITE_PLUGINS_ENABLED",
 		"BUILDKITE_PLUGINS_PATH",
 		"BUILDKITE_SHELL",
+		"BUILDKITE_HOOKS_SHELL",
 		"BUILDKITE_SSH_KEYSCAN",
 	}
 
diff --git a/internal/job/config.go b/internal/job/config.go
@@ -163,6 +163,9 @@ type ExecutorConfig struct {
 	// The shell used to execute commands
 	Shell string
 
+	// The shell used to execute agent hooks
+	HooksShell string
+
 	// Phases to execute, defaults to all phases
 	Phases []string
 
diff --git a/internal/job/executor.go b/internal/job/executor.go
@@ -549,7 +549,7 @@ func (e *Executor) runWrappedShellScriptHook(ctx context.Context, hookName strin
 		// (which acquires open file descriptors of the parent process) and
 		// writing an executable (the script wrapper).
 		// See https://github.com/golang/go/issues/22315.
-		script, err := e.shell.Script(script.Path())
+		script, err := e.shell.Script(script.Path(), e.HooksShell)
 		if err != nil {
 			r.Break()
 			return err
diff --git a/internal/job/hook/hook.go b/internal/job/hook/hook.go
@@ -22,12 +22,16 @@ func Find(root *os.Root, hookDir, name string) (string, error) {
 
 	// exts is a list of file extensions to check.
 	var exts []string
-	if runtime.GOOS == "windows" {
+	switch runtime.GOOS {
+	case "windows":
 		// check for windows types first
-		exts = []string{".bat", ".cmd", ".ps1", ".exe"}
+		exts = []string{".bat", ".cmd", ".ps1", ".exe", ""}
+
+	default:
+		// always check for an extensionless file
+		// PowerShell 7 is cross-platform
+		exts = []string{"", ".ps1"}
 	}
-	// always check for an extensionless file
-	exts = append(exts, "")
 
 	// Check for a file named name+ext in hookDir.
 	for _, ext := range exts {
diff --git a/internal/job/hook/wrapper_test.go b/internal/job/hook/wrapper_test.go
@@ -78,7 +78,7 @@ echo "hello world"
 
 			sh := shell.NewTestShell(t)
 
-			script, err := sh.Script(wrapper.Path())
+			script, err := sh.Script(wrapper.Path(), "")
 			if err != nil {
 				t.Fatalf("sh.Script(%q) = %v", wrapper.Path(), err)
 			}
@@ -177,7 +177,7 @@ echo hello world
 			err = sh.Chdir(hookWorkingDir)
 			assert.NilError(t, err, "sh.Chdir(%q) = %v", hookWorkingDir, err)
 
-			script, err := sh.Script(wrapper.Path())
+			script, err := sh.Script(wrapper.Path(), "")
 			if err != nil {
 				t.Fatalf("sh.Script(%q) = %v", wrapper.Path(), err)
 			}
diff --git a/internal/job/integration/command_integration_test.go b/internal/job/integration/command_integration_test.go
@@ -37,6 +37,7 @@ func TestMultilineCommandRunUnderBatch(t *testing.T) {
 	env := []string{
 		"BUILDKITE_COMMAND=Setup.cmd\nset LLAMAS=COOL\nBuildProject.cmd",
 		`BUILDKITE_SHELL=C:\Windows\System32\CMD.exe /S /C`,
+		`BUILDKITE_HOOKS_SHELL=C:\Program Files\PowerShell\7\pwsh.exe`,
 	}
 
 	tester.RunAndCheck(t, env...)
diff --git a/internal/shell/shell.go b/internal/shell/shell.go
@@ -299,7 +299,7 @@ func (s *Shell) Command(command string, args ...string) Command {
 // executed directly, or some kind of intepreter is executed in order to
 // interpret it (loosely: powershell.exe for .ps1 files, bash(.exe) for shell
 // scripts without shebang lines).
-func (s *Shell) Script(path string) (Command, error) {
+func (s *Shell) Script(path, commandOverride string) (Command, error) {
 	var command string
 	var args []string
 
@@ -310,6 +310,20 @@ func (s *Shell) Script(path string) (Command, error) {
 	isWindows := runtime.GOOS == "windows"
 	isPwsh := filepath.Ext(path) == ".ps1"
 
+	if commandOverride != "" {
+		// first element is the command, all others are args to which we append path
+		commandParts, err := shellwords.Split(commandOverride)
+		if err != nil {
+			return Command{}, fmt.Errorf("splitting hooks shell %q: %w", commandOverride, err)
+		}
+
+		return Command{
+			shell:   s,
+			command: commandParts[0],
+			args:    append(commandParts[1:], path),
+		}, nil
+	}
+
 	switch {
 	case isWindows && isSh:
 		if s.debug {
@@ -326,11 +340,30 @@ func (s *Shell) Script(path string) (Command, error) {
 
 	case isWindows && isPwsh:
 		if s.debug {
-			s.Commentf("Attempting to run %s with Powershell", path)
+			s.Commentf("Attempting to run %s with PowerShell", path)
 		}
 		command = "powershell.exe"
 		args = []string{"-file", path}
 
+	case !isWindows && isPwsh:
+		// First check the PowerShell script for a shebang line
+		sb, err := shellscript.ShebangLine(path)
+		if err != nil || sb == "" {
+			// No shebang, assume cross-platform PowerShell 7
+			if s.debug {
+				s.Commentf("Attempting to run %s with PowerShell 7", path)
+			}
+			pwshPath, err := s.AbsolutePath("pwsh")
+			if err != nil {
+				return Command{}, fmt.Errorf("error finding pwsh, needed to run .ps1 scripts: %w", err)
+			}
+			command = pwshPath
+			args = []string{"-file", path}
+			break
+		}
+		command = path
+		args = nil
+
 	case !isWindows && isSh:
 		// If the script contains a shebang line, it can be run directly,
 		// with the shebang line choosing the interpreter.

Original file line number	Diff line number	Diff line change
`@@ -363,6 +363,7 @@ var ProtectedEnv = map[string]struct{}{`
`363`	`363`	`"BUILDKITE_PLUGINS_ENABLED": {},`
`364`	`364`	`"BUILDKITE_PLUGINS_PATH": {},`
`365`	`365`	`"BUILDKITE_SHELL": {},`
	`366`	`+ "BUILDKITE_HOOKS_SHELL": {},`
`366`	`367`	`"BUILDKITE_SSH_KEYSCAN": {},`
`367`	`368`	`}`
`368`	`369`
Original file line number	Diff line number	Diff line change
`@@ -303,6 +303,7 @@ func TestProtectedEnv(t *testing.T) {`
`303`	`303`	`"BUILDKITE_PLUGINS_ENABLED",`
`304`	`304`	`"BUILDKITE_PLUGINS_PATH",`
`305`	`305`	`"BUILDKITE_SHELL",`
	`306`	`+ "BUILDKITE_HOOKS_SHELL",`
`306`	`307`	`"BUILDKITE_SSH_KEYSCAN",`
`307`	`308`	`}`
`308`	`309`
Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,7 @@ echo "hello world"`
`78`	`78`
`79`	`79`	`sh := shell.NewTestShell(t)`
`80`	`80`
`81`		`- script, err := sh.Script(wrapper.Path())`
	`81`	`+ script, err := sh.Script(wrapper.Path(), "")`
`82`	`82`	`if err != nil {`
`83`	`83`	`t.Fatalf("sh.Script(%q) = %v", wrapper.Path(), err)`
`84`	`84`	`}`
`@@ -177,7 +177,7 @@ echo hello world`
`177`	`177`	`err = sh.Chdir(hookWorkingDir)`
`178`	`178`	`assert.NilError(t, err, "sh.Chdir(%q) = %v", hookWorkingDir, err)`
`179`	`179`
`180`		`- script, err := sh.Script(wrapper.Path())`
	`180`	`+ script, err := sh.Script(wrapper.Path(), "")`
`181`	`181`	`if err != nil {`
`182`	`182`	`t.Fatalf("sh.Script(%q) = %v", wrapper.Path(), err)`
`183`	`183`	`}`