Custom scripts and web builds

Not every build is a single flutter build. Some projects need a code generator first, pack a ZIP afterwards or call an existing script from the repository. That’s what presets in Eigenes Script (custom script) mode are for.

Creating a script

In the preset editor, choose Eigenes Script at the top. There are then two variants:

• Inline: The script lives in the Shell-Script field directly in the preset.
• File in the repo: Under Script-Pfad (relativ zum Projekt) (script path, relative to the project) enter e.g. tools/build_android.sh. The icon next to it lists the scripts it found; Datei … (file) opens a file picker.

The script runs in the project folder, through the same shell as all builds. After the build, the Station puts an inline script as build.sh next to the artifact in the collection folder, so it’s clear later what ran.

Start every script with set -euo pipefail. Without that line, subsequent lines mask an error and a failed build counts as successful. The editor points this out.

The BS_* variables

Everything set in the preset and in the build dialog reaches the script as an environment variable. In an inline script you can also write them as {{BS_…}} placeholders; the Station replaces them before starting. Under Verfügbare Variablen (available variables) in the editor, they’re ready to click and insert.

Variable	Content
BS_PROJECT_ID	project ID
BS_PROJECT_NAME	display name of the project
BS_PROJECT_PATH	absolute project path
BS_PRESET_ID	preset ID
BS_PLATFORM	android, ios, web, macos or other
BS_BUILD_MODE	release, profile or debug
BS_FLAVOR	flavor, possibly empty
BS_TARGET	entry point, possibly empty
BS_BUILD_NAME	version from the build dialog
BS_BUILD_NUMBER	build number from the build dialog
BS_RUN_ID	ID of this run
BS_TMP_DIR	empty temp directory just for this run
BS_ARTIFACT_DIR	target folder in the collection folder, already exists
BS_GIT_BRANCH	current branch
BS_GIT_COMMIT	short commit hash
BS_DART_DEFINE_<KEY>	each Dart define individually, e.g. BS_DART_DEFINE_API_HOST
BS_DART_DEFINE_ARGS	all Dart defines as a ready-made --dart-define=… chain
BS_FLUTTER	fvm flutter, or flutter without fvm
BS_DART	fvm dart, or dart without fvm

An unknown placeholder is left as is, and the run gets a notice.

Reporting artifacts

So the Station knows what the script built, the script reports its results itself:

echo "BUILDSTATION_ARTIFACT=/absoluter/pfad/zur/datei.zip"

This is the most reliable way and takes precedence over all other sources. Report several results with several lines. Alternatively, enter patterns under artifactGlobs in the preset for the Station to search, such as build/**/*.aab.

If both are missing, the Station won’t detect an artifact, and the editor warns you beforehand. Reported files are copied to the collection folder like with any other build, see Artifacts and upload.

Example: web build as a ZIP

set -euo pipefail
$BS_FLUTTER build web --release --wasm \
  $BS_DART_DEFINE_ARGS \
  --base-href=/kunde-a/
cd build/web
zip -qr "$BS_TMP_DIR/web-$BS_BUILD_NAME+$BS_BUILD_NUMBER.zip" .
echo "BUILDSTATION_ARTIFACT=$BS_TMP_DIR/web-$BS_BUILD_NAME+$BS_BUILD_NUMBER.zip"

$BS_FLUTTER makes sure the right Flutter version from fvm runs. $BS_DART_DEFINE_ARGS passes on the Dart defines from the project, preset and build dialog. The ZIP lands in the run-specific temp folder and is copied from there to the collection folder.

build_web.sh in the project folder

Many web projects already have their own build_web.sh. If a file with exactly this name sits in the project folder, a web preset in Flutter-Befehl (Flutter command) mode runs this script instead of flutter build web.

• The script gets the same BS_* variables as a custom script.
• The preset’s Dart defines, build mode and extra arguments only reach it through these variables, such as $BS_DART_DEFINE_ARGS.
• If the Dart define API_HOST is set, its value is also passed as the first argument: build_web.sh <API_HOST>.
• The preview in the Build tab then shows the script as the command.

Presets in Eigenes Script mode stick with their own script.

Committing the web build

Some deployments pull the web build straight from the repository. For those projects, the project editor has the Web-Build committen (commit web build) switch.

When it’s on, the Station commits the build/web folder to the current branch after a successful web build:

• Only this folder is committed, including files removed from it. Other changes in the working tree are left alone.
• The commit message reads e.g. Web-Build 1.4.2+88 and names the source commit.
• Nothing is pushed. You do that yourself or with Commit & Push in the Build tab.

If build/web is excluded via .gitignore, the repository is on a detached HEAD or a Git hook fails, the build still counts as successful. The reason then appears as a warning on the run.

Scripts run without a sandbox

Important: A custom script runs with the full permissions of your macOS user. It can read, write and delete anything you can.

That’s the point of the feature, but it has a consequence: a preset configuration is executable code. An imported project JSON, a buildstation.json from someone else’s repository or a project passed on to you is exactly as trustworthy as a shell script from a stranger. Look inside before importing.

More on this in Settings and security.