Skip to main content
Themes deploy from a git repository. Once connected, every push to the tracked branch redeploys.

​
Connecting a repository

1

Push the theme

Commit everything under the theme root, including the compiled stylesheet.
2

Connect it in the dashboard

Open My Store, connect the GitHub repository and select the branch. ByteSell reads the tree, locates directories containing theme.json and validates the shape before accepting the connection.
3

Set it live

A connected theme installs as a private theme and is not live. Check the deploy status, then set it live.
Themes connected this way are private to the store and do not appear in the marketplace catalog. They are read-only in the builder, since the repository is the source of truth.

​
Versions

The version is assigned by the server, which takes the highest existing clean semver and bumps its patch, starting at 1.0.0.
version in theme.json is not read at publish. Changing it has no effect. It is read only when the dashboard detects a theme in a connected repository, for display.

​
Schema version

schema in theme.json declares which generation of the section system the theme targets. The gate is one-directional. A deployment newer than the theme is accepted. A theme declaring a version higher than the deployment supports is rejected:

​
Validation

Checks run in this order. Any failure rejects the entire publish.
1

Size and paths

File count, per-file size, total size and path rules. See Limits.
2

Templates parse

Every .slurp must be valid UTF-8 and must parse within a 10 second budget per file.
3

No {fetch} in a block

Any file under blocks/ containing a {fetch} at any depth is rejected.
4

Linked stylesheets exist

Every literal root-relative .css referenced by an href must be in the bundle.
5

Schema version is supported

See above.
6

Defaults and schemas extract

templates/*.json must be valid JSON with a sections array, every entry needs a string type, and ids must be unique within a page.
Bytes are uploaded before the database commit, so a failed commit leaves unreferenced objects rather than a manifest pointing at missing files.

​
Common rejections

​
Propagation

Store configuration is cached, so a published theme reaches buyers within about 60 seconds. The builder preview is uncached and updates immediately. For the first minute after a publish, the preview reflecting a change the live store does not is expected.

​
Deploying a built artifact

A theme built in CI should publish the built artifact rather than have ByteSell pull raw source. The deploy action mints a short-lived OIDC token, so no secret is stored.
.github/workflows/deploy.yml
In a repository already connected by webhook, both paths fire on the same push. The first successful action run switches the theme to artifact mode and the webhook stops deploying it, so only the first push after adding CI can race.