Publishing and Versions

What a package contains, the publisher.json manifest, how to publish from the app, a coding agent, the CLI, CI/CD or Git, what Credible does on publish, and how to manage versions with latest, auto-promote, auto-archive and rollback

Publishing turns a draft into a new version of a package, which people and agents then query. Each version is immutable, and one version at a time is the package's latest, the version everyone gets by default.

Packages: The Unit of Publishing

A package is a folder holding a model and everything that ships with it:

  • .malloy files: the data model. The package's index.malloy decides which sources callers can query (see Exports and Field Visibility).
  • Reports (dashboards and notebooks): .malloy files tagged ## artifact { layout=grid } or ## artifact { layout=linear }. See Reports. Legacy .malloynb notebooks still render, but don't write new ones.
  • Data apps: HTML and JavaScript in a public/ directory, which query the package's own models with its access rules applied. See Data Apps.
  • Data files such as CSV or Parquet, read by the model. See Embedded Data.
  • publisher.json: the manifest.

A package is published and versioned as one unit. Model, documentation, access rules, apps and manifest move together, so every version is complete and rolls back as a whole. Each package belongs to one environment.

The Package Manifest

publisher.json sits at the package root and identifies the package:

{
  "name": "ecommerce",
  "version": "1.2.0",
  "description": "Orders, customers and products for the online store"
}
  • name: the package name.
  • version: the version this publish creates. Versions are immutable, so each publish needs a new one. In the app, Credible picks the next version for you.
  • description: one line saying what the package covers. People and agents see it when choosing a package.

An optional materialization block sets how materialized tables are shared across versions and kept fresh:

{
  "name": "ecommerce",
  "version": "1.2.0",
  "description": "Orders, customers and products for the online store",
  "materialization": {
    "scope": "package",
    "freshness": { "window": "24h", "fallback": "live" }
  }
}

scope belongs inside materialization. A scope at the root of the file is deprecated, and two different values in the two places fail the package load. The options are described in Package Manifest on the materialization page.

How to Publish

Every route below creates the same thing: a new version of the package in the active environment.

  • In the Credible App: ask the agent to publish the draft. See Build a Model.

  • With your coding agent: ask the agent to publish. With the modeling skills that cred init or the VS Code extension installs, it checks publisher.json, sets a new version, and runs cred publish. See Local Development.

  • With the CLI, from the package directory:

    npm install -g @credibledata/cred-cli   # first time only
    cred login <organization>              # first time only
    cred set environment <environment>
    cred publish

    cred publish --dry-run lists the files it would upload, without publishing. cred publish --set-latest makes the new version latest immediately, before its indexes and tables are built; without it, auto-promote moves latest when the version is ready. See the CLI reference for every option.

  • From CI/CD: a GitHub Actions workflow publishes changed packages when changes merge to your main branch. See CI/CD.

  • In a git-backed environment: publishing from the app opens a pull request, and merging it publishes. See Git-Backed Environments.

What Happens When You Publish

  1. Check and version. Credible compiles the model. Errors refuse the publish, with the reason. Problems that don't stop the model from serving, such as an annotation that will be ignored, come back as warnings. If the publish succeeds, it creates a new, immutable version.
  2. Build derived copies. Credible builds each #@ persist table, each #@ preaggregate pre-aggregate and each #(index) search index, in dependency order. See Materialization and Performance.
  3. Build the concept index. The exported sources, their fields, #(doc) descriptions and #(index) values are compressed into the concept index that agents search by meaning.
  4. Serve. Access rules (#(authorize), #(access_filter) and secure givens) apply to every query against the version, on every surface.

The package page shows each version's build status: building while indexing and materialization run, then ready, or failed if a build failed.

Package version page showing build status, models, and indexed dimensions

Queries through execute_query and the Data API work as soon as a version is published. The get_context search returns results for the version after its indexing finishes.

Serving and Version Management

Versions work like software releases:

  • One latest version. The version marked as latest is what consumers get when they don't name a version. Moving latest moves every such consumer together, and nothing rebuilds.
  • Earlier versions stay available until they are archived, so you can roll back, compare, or keep a caller on a known version through the APIs.

To make a version latest by hand, use Set as latest in the version's actions on the package page, or the CLI:

cred ls versions <package>                        # list a package's versions
cred update package <package> --version <version> # make a version latest

Two package settings automate the routine parts. Both are on by default for new packages, and both are set in the package's settings (Manage package) or through the Admin API.

Auto-Promote

With auto-promote on, a newly published version becomes latest when it is ready: indexed, with its materialized tables built. Consumers never move to a version that is still building, and a version whose build fails is never promoted.

  • Rollbacks stick. Auto-promote only promotes a version that has never been latest, so after you roll back it won't move latest forward again on its own.
  • No going backward. A ready version older than the current latest is not promoted.

Turn it off to promote by hand, for example to test a version by querying it directly first.

Auto-Archive

With auto-archive on, a version that is no longer latest is archived after it has gone a retention window without being latest. A version that was never latest counts from when it was published. The current latest is never archived. Archiving removes the version from service and drops materialized tables that no remaining version uses (see Storage Reclamation).

Set the retention as a duration such as 24h, 30d or 2w. 0 archives every version except the latest as soon as it is replaced, which keeps storage lowest but leaves no older version to roll back to. Turn auto-archive off to keep every version until you archive it.

To archive or restore a version by hand, use the version's actions on the package page, or cred archive <package> <version> and cred unarchive <package> <version>.

Versioning Best Practices

Number Versions by What Changed

Use semantic versioning in publisher.json:

  • Major (2.0.0): breaking changes, such as a renamed or removed field or view
  • Minor (1.3.0): additions, such as new dimensions, measures or views
  • Patch (1.2.1): fixes and documentation

Publish, Validate, Promote, Roll Back

  1. Publish without promoting. With auto-promote off, publish the new version and leave latest where it is.
  2. Validate. Query the new version directly, or have a few people check it, before anyone else is moved to it.
  3. Make it latest when it checks out.
  4. Roll back if needed by making the previous version latest again. Nothing rebuilds, and every consumer follows. In a git-backed environment, once a package has published from git you can roll back only to a version git published, unless direct uploads are allowed.

With auto-promote on, steps 1 to 3 happen automatically when the version is ready; keep step 4 in mind.

Archive What You No Longer Serve

Archived versions stop costing storage for tables only they use. Let auto-archive do this, or archive old versions by hand.

For how to split environments (by team, by stage such as dev and prod, or both), see Environments and Packages.

Next Steps

On this page