Release Lifecycle

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

​

Workflow object

A workflow is the stable object that releases belong to. It has a slug, such as my-workflow, which is referenced from tilebox.workflow.toml. The workflow object is not the executable code itself; it provides the long-lived name under which releases are published. Create the workflow object once, then keep publishing new releases to it as the code changes. This gives release runners and deployment commands a stable workflow identity while each release remains immutable.

​

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 slug it belongs to. Publishing is idempotent for identical release content and artifact digests. If the same release already exists, Tilebox returns the existing release instead of creating another copy. This is useful in agent-assisted and automated workflows where the same build step may run more than once.

​

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 deploy a compatible fixed release 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