Thoughts on making the default shell configurable?

[jerrod-storm]

I've been setting up Woodpecker for a bash-heavy project and ran into the hardcoded /bin/sh in GenerateContainerConf:

// pipeline/backend/common/script.go
entry = []string{"/bin/sh", "-c", "echo $CI_SCRIPT | base64 -d | /bin/sh -e"}

My project's libraries use bash features throughout (associative arrays, herestrings, pipefail, BASH_SOURCE, etc.), so every step that sources them needs bash. The current workarounds are:

• Wrapping commands in bash -c '...', which squashes everything into one inline string
• Overriding entrypoint to replicate the CI_SCRIPT base64 decode with bash instead of sh, which works but requires reproducing the CI_SCRIPT decode pipeline manually

Neither is a dealbreaker, but it got me wondering: would there be interest in making the shell configurable?

Some arguments for this:

1. Migration friction. Most major CI systems (GitHub Actions, GitLab CI, CircleCI) default to bash for step commands. This can be a friction point for teams migrating to Woodpecker, since pipelines that worked elsewhere break when bash syntax hits /bin/sh. Sometimes it breaks loudly (syntax errors), but sometimes /bin/sh silently behaves differently, which is harder to debug.

2. Bash is widespread in CI scripting. A lot of CI tooling in the wild assumes bash -- build scripts, test harnesses, shared libraries. Requiring each step to wrap its commands in bash -c or overriding the entrypoint for every file adds boilerplate for these use cases without a clear upside.

3. The entrypoint setting is fragile. It works, but it requires users to know about CI_SCRIPT and its base64 encoding. While the base64 encoding is mentioned briefly in the documentation feels a little odd having to decode it manually as an end-user.

One possible approach would be an agent-level environment variable like WOODPECKER_DEFAULT_SHELL, defaulting to /bin/sh for full backwards compatibility. Agent-level seems natural to me since the agent is what executes steps and knows what's available. In a mixed fleet (e.g. Alpine agents vs Ubuntu agents), different agents could set different defaults.

The implementation would be small -- passing a shell parameter into GenerateContainerConf instead of hardcoding it:

func GenerateContainerConf(commands []string, osType, workDir, shell string) (env map[string]string, entry []string) {
    // ...
    env["SHELL"] = shell
    entry = []string{shell, "-c", fmt.Sprintf("echo $CI_SCRIPT | base64 -d | %s -e", shell)}
    // ...
}

But I could also see arguments for a per-step YAML field (or even both), or for keeping things as-is and documenting the entrypoint workaround more explicitly. Curious what others think.

I'm happy to put together a PR if the idea has legs. I'm used to Go and managing docker containers.

[manimovassagh]

This is a well-thought-out proposal. The friction you describe is real -- I have hit the same thing migrating pipelines from GitHub Actions and GitLab CI.

A few thoughts on the design:

Agent-level config makes the most sense as the default

Your WOODPECKER_DEFAULT_SHELL idea is the right starting point. The agent knows what is available on its host images, and different agents in a fleet may have different defaults. This matches how other agent-level config works in Woodpecker.

Per-step override would be valuable too

Some pipelines mix steps that need bash with steps running in minimal Alpine images that only have /bin/sh. A per-step field would handle this cleanly:

steps:
  - name: build
    image: ubuntu:24.04
    shell: /bin/bash
    commands:
      - set -euo pipefail
      - declare -A versions=([go]="1.22" [node]="20")
      - # bash-specific features work naturally

  - name: notify
    image: alpine:3.19
    # uses /bin/sh (the default) -- no bash needed
    commands:
      - wget -qO- https://hooks.example.com/notify

The resolution order would be: step-level shell > agent-level WOODPECKER_DEFAULT_SHELL > /bin/sh (hardcoded fallback).

Implementation notes

Your proposed change to GenerateContainerConf is on the right track. One thing to watch out for: the base64 -d in the decode pipeline is itself not portable (base64 -d on GNU, base64 -D on macOS/BSD). Since this runs inside the container image it is almost always GNU, but if the shell parameter opens the door to more exotic environments, it might be worth using base64 --decode (the long flag) which is more universal.

Also, the -e flag on the inner shell invocation (| /bin/sh -e) should use the configured shell too:

entry = []string{shell, "-c", fmt.Sprintf("echo $CI_SCRIPT | base64 -d | %s -e", shell)}

Which is what you already have -- just calling it out since it is easy to miss the second occurrence.

I would use it

If you open a PR, I think it would get traction. The backwards compatibility story is clean (default stays /bin/sh), the implementation surface is small, and the migration benefit for teams coming from other CI systems is tangible.

[6543]

we have it as entrypoint already -> if we change it for all we make woodpecker just insecure and unpredictable

I am strongly against it!

we could do backend specific args for steps that make it more convinioent but all alterations make e.g. plugins into non plugins and you are on your own :/

[6543]

as for you have to know about $CI_SCRIPT ... I still am not a huge fan ow how internal passing of commands is achived into the container and if there is a better solution I'm looking for doing so... I considder this:

woodpecker/pipeline/backend/common/script.go

Lines 21 to 35 in 9b83916

	func GenerateContainerConf(commands []string, osType, workDir string) (env map[string]string, entry []string) {
	env = make(map[string]string)
	if osType == "windows" {
	env["CI_SCRIPT"] = base64.StdEncoding.EncodeToString([]byte(generateScriptWindows(commands, workDir)))
	env["SHELL"] = "powershell.exe"
	// cspell:disable-next-line
	entry = []string{"powershell", "-noprofile", "-noninteractive", "-command", "[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($Env:CI_SCRIPT)) | iex"}
	} else {
	env["CI_SCRIPT"] = base64.StdEncoding.EncodeToString([]byte(generateScriptPosix(commands, workDir)))
	env["SHELL"] = "/bin/sh"
	entry = []string{"/bin/sh", "-c", "echo $CI_SCRIPT | base64 -d | /bin/sh -e"}
	}
	return env, entry
	}

as workaround for current implementation limitations

[qwerty287]

Allowing to change that on a per-step basis is something I can understand because if you change the entrypoint you always have to write down the actual execution (the base64 decoding etc.). But yes I also wouldn't change that for a whole agent.

[6543]

and the issue is that a custom entrypoint just by default ignore the $CI_SCRIPT, witch should be document and is A. a leaking implementation detail, B. If we add a new config "just to change" the default shell, what abaut using pwsh as defaultshel? now tje asumtion of passing a -c 'echo $...... fails and user just expects it to work and now we have to add the same and more workarounds we have in local backend, just for the sace of user not reading the docs :/

TLDR: i strongly am against addin such options just for the wackamole we get with it

PS: we dont have to imitate stuff from github actions, just because tjey do ...
and have bad workarounds for workarounds...

[6543]

https://woodpecker-ci.org/docs/usage/workflow-syntax#entrypoint

@jerrod-storm as for you, most images do set /bash as bin/sh, if they dont like alpine the entrypoint should do the trick for you, in this case you still have to create a custom image that adds bash, and in this case you also can replace the /bin/sh with bash ...

... if the docs are not good in describing it, could you describe me whats missing :)