Release Lifecycle
Understand how workflow releases are built, checked, published, deployed, and used by release runners.
Workflow releases make workflow code reproducible. A release captures the files selected from a Python workflow project, the runtime entrypoint, and the task identifiers discovered from the configured runner. Release runners later use that release to execute compatible tasks on clusters that have the release deployed.
The release lifecycle separates code packaging from cluster rollout. Building and publishing create immutable release content. Deploying a release changes which workflow code release runners on a cluster can execute.
Lifecycle overview
| Stage | What it does | What changes |
|---|---|---|
| Workflow initialization | Creates a local project from the built-in scaffold or a published template. | Writes the files you need to start developing. |
| Local build | Resolves files, creates a deterministic artifact, and checks the configured Python runtime. | Writes local build output and cache entries. |
| Publishing | Builds, checks, and uploads a release. | Creates the workflow on first publication; later publications add releases to it. |
| Deployment | Maps a release to one or more clusters. | Changes which release runners can execute the release. |
| Job execution | Submits tasks that match the release’s task identifiers and compatible versions. | Creates or updates jobs and tasks. |
Workflow object
A workflow groups the releases you publish as your code changes. The CLI remembers which workflow your local project belongs to.
For projects started with tilebox workflow init, including templates, the first publication creates the workflow in Tilebox. If you are continuing an existing workflow from a cloned repository, link your local project first.
Release artifact
The release artifact is the package that release runners download and execute. Tilebox assembles it from the files selected by the [build] section in tilebox.workflow.toml, after include patterns, exclude patterns, and .gitignore handling are applied.
Artifacts should contain source code, lock files, and small configuration. They should not contain downloaded source data, model checkpoints, generated outputs, local virtual environments, or task caches. If a workflow needs large runtime assets, the task code should fetch them at runtime and cache them in the runner environment.
Runtime checks and task discovery
During a build, Tilebox starts the configured Python workflow runtime and imports the runner object or command from tilebox.workflow.toml. This checks that the artifact contains the files needed to start the workflow runtime.
The same step discovers the task identifiers registered by the workflow. Those identifiers become part of the release metadata and determine which submitted tasks a release runner can execute after the release is deployed.
Publishing
Publishing turns checked local release content into a workflow release in Tilebox. The release record points to the artifact, the discovered task registrations, and the workflow it belongs to.
Publishing the same code and configuration to the same workflow reuses the existing release. You do not get duplicate releases when you publish again without changing anything.
Deployment
Publishing a release does not make release runners execute it. A release must be deployed to a cluster before release runners on that cluster load its workflow code and execute compatible tasks from it.
A deployment maps one release to one cluster. Different clusters can run different releases of the same workflow, which makes it possible to test a release in a development cluster before promoting it to production-like clusters.
Compatibility and retries
Release compatibility matters when retrying existing jobs. A failed job can resume from failed tasks after you publish a compatible fixed release to the same workflow and deploy it to the same cluster. The task identifier name, major version, and input schema must remain compatible with the failed task that is being retried.
Use a new major task version and submit a new job when the task input schema or behavior is no longer compatible with tasks submitted before the change. This keeps old jobs reproducible while allowing breaking workflow changes to move forward safely.
Related documentation
Project structure
Structure a Python workflow project for workflow releases and release runners.
Workflow configuration
Configure tilebox.workflow.toml, build inputs, and deployment targets.
Deploy releases to clusters
Map workflow releases to clusters and run them with release runners.
Workflow release concepts
Learn how workflows, releases, artifacts, and cluster deployments fit together.