What your script is told

Every script receives the build's details as environment variables. The same values, plus a few structured ones, are in a JSON file whose path is in DSL_BUILD_CONTEXT. Examples below use the fictional studio northwind and its project starfall.

Version

Version variables
Variable	Example
`DSL_VERSION`	`1.4.0`, your branch's version
`DSL_BUILD_NUMBER`	`57`, the branch's build counter

Source

Source variables
Variable	Example or meaning
`DSL_COMMIT`	The exact revision being built: a full git SHA, a Perforce changelist or a Diversion commit
`DSL_PUSH_HEAD_COMMIT`	The latest commit of the push that started the build
`DSL_BRANCH`	`main`, or your Perforce stream or depot path
`DSL_REPO_URL`	Your repository's address (never includes credentials)
`DSL_SOURCE_CONTROL`	`git`, `perforce`, `diversion` or `local_dir`
`DSL_WORKSPACE_REUSED`	`true` when files from a previous build are still present (incremental builds)

The build

Build variables
Variable	Example
`DSL_ORG`, `DSL_PROJECT`	Your organization and project, e.g. `northwind`, `starfall`
`DSL_CONFIGURATION`	The build configuration's name, e.g. `win32-release`
`DSL_PLATFORM`, `DSL_FLAVOR`	`win32`, `release`: the build configuration's platform and flavor. Platforms include `win32`, `linux`, `macos`, `ios` and `android`
`DSL_TOOLCHAIN`, `DSL_TOOLCHAIN_VERSION`	`unity`, `6000.0.23f1`
`DSL_AUTO_BUILD`	`true` if a push or schedule started the build, `false` if someone clicked Build
`DSL_BUILD_UUID`, `DSL_JOB_UUID`	Identifiers to quote in support requests

Where things are

Path variables
Variable	Meaning
`DSL_BUILD_HOOK`	Which hook is running, e.g. `pre_build`
`DSL_REPO_DIR`	The repository root
`DSL_PROJECT_DIR`	Your project folder
`DSL_OUTPUT_DIR`	The build output folder, from `post_build` on (Godot, Unity and Unreal; see the note under Examples)
`DSL_ARCHIVE_PATH`	The uploaded zip (`post_archive`, `on_end`)
`DSL_HOST_OS`	`linux`, `darwin` or `win32`

on_end also receives the build's result; those three variables are on Failures, on_end and limits. Secrets are never passed as environment variables; see Secrets in build actions.

Absent, not empty

A variable whose value is not known yet is absent, not empty. For example, DSL_REPO_DIR does not exist in pre_checkout, and DSL_OUTPUT_DIR only appears from post_build on, and only for Godot, Unity and Unreal. Use os.environ.get(...) or process.env.X ?? ... when a script runs in more than one hook.

Python

import os

hook = os.environ["DSL_BUILD_HOOK"]
repo = os.environ.get("DSL_REPO_DIR")  # absent in pre_checkout

The build context file

DSL_BUILD_CONTEXT holds the path to a JSON file with the same values as the environment variables, plus one that only exists there: commits, the list of commits in the push, each with its message, author, time and changed files.

Examples

Add a file to the shipped build

A post_build.js that writes version.json into the output. Because it runs in post_build, the file is signed, zipped and uploaded with the build. This works for Godot, Unity and Unreal; for CMake, MSBuild, SCons and Xcode, DSL_OUTPUT_DIR is not set, so write the file into the repository where your artifact patterns match instead.

post_build.js

const fs = require("fs"), path = require("path");
const out = process.env.DSL_OUTPUT_DIR;
fs.writeFileSync(path.join(out, "version.json"), JSON.stringify({
  version: `${process.env.DSL_VERSION}.${process.env.DSL_BUILD_NUMBER}`,
  commit: process.env.DSL_COMMIT,
}, null, 2));

Do something only on one platform

A pre_build.py that exits straight away unless the configuration targets Android. Exit code 0 counts as success.

pre_build.py

import os, sys
if os.environ["DSL_PLATFORM"] != "android":
    sys.exit(0)
# ... Android-only preparation ...

Something out of date or unclear? Email support@devstreamlabs.com.