push uploads each definition file to the revision exactly as it stands on disk. No compiler runs, nothing is
skipped for being unchanged, and an alias the revision does not have yet is created on the way.
It is the write half of the pull/push pair, and it is rarely the command you want for code: a manifest that
binds a Python package expects build to have run first, or
deploy to do both. push is for a document you edited directly.
Synopsis
What it does
- Loads the manifest and resolves its blob and revision. This is a write, so the revision must have status
readyand phasedraftormanaged;commitis refused. - Lists the revision’s definitions in both categories and matches the manifest against them.
- For each entry, reads the
sourcedocument — a missing file isMANIFEST_INVALID, not a silent skip — and uploads it. An alias absent from the revision is created first. - Prints drift, then one line per definition:
--json the payload
carries created, uploaded, planned, dry_run and drift, alongside the envelope’s schema_version.
Creating an absent alias takes two calls
create_definition writes an empty stub — an alias, a category, and for a playground its canonical layout
— and nothing else. upload_definition is then a full replace of that stub’s document. The platform offers no
create-with-content call, so the sequence is two calls, in that order, and push performs both.
The gap between them is why a freshly created definition briefly exists with no content, and why an interrupted
push can leave a stub behind. Re-running push fixes it: the alias now exists, so the second run skips
straight to the upload.
For a playground, the layout handed to create_definition comes from the document being pushed. The platform
canonicalizes it at creation and compares every later upload against it, so the layout you create with is the
layout that definition keeps.
Verbatim means unvalidated
upload_definition validates nothing. The workflow and playground upload schemas are placeholders that accept
any object, so a malformed document — or a playground document uploaded into a workflow definition — is accepted
without complaint and corrupts that definition silently.
Two things stand between you and that. The manifest’s category rule catches the document/category mismatch
locally, because nothing server-side will. And check is what tells you whether
what you uploaded is a workflow the platform can run — push never runs it, unlike deploy.
push also uploads every definition it resolves, changed or not. Only deploy compares against the remote
document first.
--dry-run
Resolves everything and reports the intended calls without making them:
Errors
push has no rollback. It uploads definitions in manifest order, and a failure on the third leaves the first two
uploaded — which is a state, not a corruption: re-running after the fix re-uploads all three.
Every code above, with its remediation, is in Error codes.
See also
blobhub workflow pull— the read half of the pair.blobhub workflow deploy— compile, upload only what changed, and check it.blobhub workflow check— whatpushdeliberately does not run for you.- Create Definition and Upload Definition — the two calls behind a create.
- Playground definition format — where
layoutand grid positions come from.