Workflow Templates
Workflow Templates (also called tasks) are reusable building blocks that define common operations within a workflow. They encapsulate logic for tasks such as fetching source code, running Python scripts, and submitting distributed machine-learning jobs. By referencing templates from a workflow version, you assemble complex pipelines out of pre-defined, parameterized steps.
A task references a template through its templateRef and supplies values through a flat arguments map (string → string). Argument values may embed ${config.KEY} references, which are resolved at run time from the effective configuration.
Available Templates
| Template | Version | Category | Purpose |
|---|---|---|---|
fetch-git-code | v1.0.0 | Source Code | Clone a Git repository from bmw.ghe.com into the shared workspace |
fetch-git-code-atc | v1.0.0 | Source Code | Clone a Git repository from ATC GitHub (atc-github.azure.cloud.bmw) into the shared workspace |
run-python-code | v1.0.0 | Execution | Run a Python script, optionally installing dependencies |
submit-ray-job | v1.0.0 | Execution | Submit a distributed job to an ephemeral Ray cluster |
Versioning
Task templates follow Semantic Versioning. A templateRef.version accepts exactly three forms:
| Form | Example | Meaning |
|---|---|---|
vMAJOR | v1 | Floating alias — always resolves to the latest vMAJOR.*.* release. |
vMAJOR.MINOR | v1.2 | Floats to the latest patch within that minor. |
vMAJOR.MINOR.PATCH | v1.2.3 | Immutable pin — an exact release, for reproducible runs. |
Every task-template version is v-prefixed; there is no bare form. A bare 1.2.3 (without the v) is rejected.
The Version column above shows v1, the floating alias that resolves to the latest v1.x.x release of each template.
When a template publisher cuts a new version, the bump signals intent:
- MAJOR — a breaking change; consumers must opt in explicitly.
- MINOR — backward-compatible additions (e.g. a new optional argument).
- PATCH — backward-compatible bug fixes.
Source Code Templates
fetch-git-code
For this template to work correctly, the Connected AI Platform GitHub App must be installed on the target repository.
Follow this guide on how to install the GitHub App.
Clones a Git repository from bmw.ghe.com into the shared /workspace volume so that downstream tasks can operate on the source code.
Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
git-url | ✅ | — | SSH URL of the Git repository to clone. |
git-branch | main | Branch to checkout. |
Example Usage
{
"name": "example-fetch-code",
"templateRef": {
"name": "fetch-git-code",
"version": "v1"
},
"arguments": {
"git-url": "git@bmw.ghe.com:example/example-repo.git",
"git-branch": "main"
},
"dependencies": []
}
fetch-git-code-atc
For this template to work correctly, the Connected AI Platform GitHub App must be installed on the target repository.
Follow this guide on how to install the GitHub App.
Identical to fetch-git-code, but authenticates against ATC GitHub (atc-github.azure.cloud.bmw) instead of bmw.ghe.com. Use this variant for repositories that have been migrated to ATC GitHub. It accepts the same parameters.
Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
git-url | ✅ | — | SSH URL of the Git repository to clone. |
git-branch | main | Branch to checkout. |
Example Usage
{
"name": "example-fetch-code-atc",
"templateRef": {
"name": "fetch-git-code-atc",
"version": "v1"
},
"arguments": {
"git-url": "git@atc-github.azure.cloud.bmw:example/example-repo.git",
"git-branch": "main"
},
"dependencies": []
}
Execution Templates
run-python-code
Runs a Python script from the cloned workspace, optionally installing dependencies with pip or uv first. Use this for lightweight, single-node Python execution.
Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
entrypoint | ✅ | — | Python script path relative to project-dir (e.g. src/train.py). Resolved at runtime as /workspace/<project-dir>/<entrypoint>. Must exist inside the mounted workspace. |
project-dir | repo name | Subdirectory inside /workspace that contains the project code. Defaults to the repository name of the preceding fetch-git-code task (must match its output-dir). CWD is set to /workspace/<project-dir> at runtime. | |
package-manager | pip | Dependency installer to use before running the script. Allowed values: pip, uv. Ignored when python-requirements is empty. | |
python-requirements | "" | Path to a requirements file relative to project-dir (e.g. requirements.txt). Leave empty to skip dependency installation. | |
python-version | 3.14 | CPython version to use (e.g. 3.11). Must be available in the container image. | |
log-level | INFO | Python logging level. Allowed values: DEBUG, INFO, WARNING, ERROR, CRITICAL. | |
trace | 0 | Enable shell trace mode (set -x) in the entrypoint. 1 to enable, 0 to disable. | |
environment-variables | {} | Runtime environment variables for the Python job, as a JSON object. |
Example Usage
{
"name": "example-run-python",
"templateRef": {
"name": "run-python-code",
"version": "v1"
},
"arguments": {
"entrypoint": "src/train.py",
"project-dir": "code",
"package-manager": "uv",
"python-requirements": "requirements.txt"
},
"dependencies": [
"example-fetch-code"
]
}
submit-ray-job
Submits a job to an ephemeral Ray cluster provisioned for the run, then tears the cluster down on completion. Use this for distributed training, tuning, and data processing across multiple workers (with optional GPUs).
Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
entrypoint | ✅ | — | Python script entrypoint path, relative to project-dir. |
entrypoint-args | ✅ | — | Arguments passed to the Python entrypoint script. |
worker-replicas | ✅ | — | Number of Ray worker replicas to launch. |
worker-cpu | ✅ | — | CPU allocation per worker replica. |
worker-memory | ✅ | — | Memory allocation per worker replica (e.g. 5Gi). |
worker-gpu | ✅ | — | GPU allocation per worker replica. Set to "" for CPU-only. |
ray-job-timeout-minutes | ✅ | 120 | Maximum time to wait for Ray job completion, in minutes. |
project-dir | repo name | Subdirectory inside /workspace that contains the project code; the entrypoint is resolved relative to it. Same semantics as run-python-code's project-dir. Must match the output-dir of the preceding fetch-git-code task (repository name by default). | |
ray-version | 2.53.0 | Ray cluster version. | |
ray-image | rayproject/ray | Ray cluster container image. | |
ray-image-tag | 2.53.0-py311 | Ray cluster container image tag. | |
head-cpu | 8 | CPU allocation for the Ray head node. | |
head-memory | 32Gi | Memory allocation for the Ray head node. | |
head-gpu | "" | GPU allocation for the Ray head node. Set to "" for CPU-only. | |
environment-variables | {} | Runtime environment variables for the Ray job, as a JSON object. | |
python-package-manager | pip | Package manager used inside the Ray context. Allowed values: pip, uv. | |
python-package-manager-args | "" | Additional arguments passed to the package manager. |
Example Usage
{
"name": "example-ray-submit-task",
"templateRef": {
"name": "submit-ray-job",
"version": "v1"
},
"arguments": {
"entrypoint": "src/example.py",
"entrypoint-args": "",
"worker-replicas": "2",
"worker-cpu": "2",
"worker-memory": "5Gi",
"worker-gpu": "",
"head-memory": "5Gi",
"ray-job-timeout-minutes": "120"
},
"dependencies": [
"example-fetch-code"
]
}
Instead of hard-coding values like worker-replicas or GPU counts, reference a configuration with ${config.KEY} so the same version can run with different resources per stage. All manual inputs should be provided as configuration values or environment variables rather than baked into the version.