Publish and deploy

Publish and deploy

Publishing and deploying are two separate decisions. Publishing freezes a draft into a version that may be used outside the editor. Deploying decides which environment that version is allowed to run in.

Before publishing

Check that:

• The PDF preview is correct for the important examples.
• Required fields are clear.
• Optional text behaves as expected.
• The correct theme, fonts, and shared fragments are used.
• Any warnings are understood and accepted.

You can also compare two versions side by side as rendered PDFs with the same example data, when you want to see exactly what changed.

Publishing can be blocked for reasons that have nothing to do with the document itself. Every stencil the template uses must be published first, and if the data contract has changed in a way that breaks existing data, Epistola stops and asks you to publish the contract explicitly before continuing. Compatible contract changes are published together with the version, so those need no extra step.

What publishing freezes

A published version is a snapshot: the document content, the resolved theme, and the fonts it depends on are captured, so the same data produces the same document later. Published versions therefore cannot be edited, and there is no way to unpublish one — to change something, you publish a new version.

Publishing does not put the version to work by itself, but it is not invisible either: a caller that names neither a version nor an environment is served the newest published version. Choosing an environment is what makes it the version that runs in that stage.

Deploy to the right environment

Environments are the stages a document can run in, typically test, acceptance, and production, and each variant has at most one active version per environment. The deployment matrix shows this as a grid — one row per variant, one column per environment — with the active version in each cell. Selecting another version activates it straight away, and clearing the cell removes the deployment. Switching back to an earlier published version is how you roll back; published versions are never edited to repair a deployment.

Deploying a draft publishes it at the same time, because only a published version can be active.

Use test or acceptance first when another system will call the template. Move to production only after the connected workflow has been checked with realistic data.

When to publish again

Publish a new version for changes that users must approve or that affect generated output. Small draft edits are invisible until you publish, since a draft is never selected automatically.

Authoring and publishing are separate permissions: authors work on drafts, while a publisher role publishes, deploys, and archives. Environments are configured by administrators, so authors can prepare work without being able to change what production runs.

Archiving retires a version while keeping it for audit. A version can only be archived when it is not active in any environment, so remove it from its deployments first.