Shopify Theme Version Control and GitHub CI: A Working Setup

title: Shopify Theme Version Control and GitHub CI: A Working Setup slug: shopify-theme-version-control-github-ci meta_title: Shopify Theme CI: CLI, GitHub and Version Control meta_description: Shopify theme version control with the CLI, a theme access token and theme check in CI. The drift problem that breaks it and the pipeline that survives. primary_keyword: Shopify theme version control secondary_keywords:

Shopify Theme Version Control and GitHub CI: A Working Setup

Shopify theme development without version control means one bad edit in the code editor and no way back. With the Shopify CLI and a Git host, you get pull requests, a staging theme, automated linting and a one-command rollback. The setup takes a day and saves that day back the first time something breaks.

The hard part is not the tooling. It is that merchants edit the JSON templates in the admin, so your repository and your live store drift unless you pull before you deploy.

The toolchain

Shopify CLI 3.x is the entry point. It handles shopify theme dev for a live local preview, shopify theme push to upload, and shopify theme pull to bring admin edits back down. The --unpublished flag pushes to a new or development theme so you never overwrite live from a laptop.

According to Shopify's CLI documentation, the theme commands cover dev, push and pull. Authentication runs through a Theme Access token, exported as SHOPIFY_CLI_THEME_TOKEN, which keeps CI from needing an interactive login. That token is scoped to themes only, which is what you want in a build system.

A workable pipeline

1. Repository per theme, with main matching what is live and feature branches for changes.
2. Pin the CLI version in the repo, because CLI upgrades occasionally change push behaviour.
3. shopify theme check in CI on every pull request. It catches deprecated Liquid, performance anti-patterns and unknown objects before review.
4. Staging theme per branch, pushed with --unpublished, so designers review a real URL rather than a diff.
5. Pull from live before pushing. This is the step that matters most.
6. Tag releases with a semantic version so a rollback is a checkout plus a push.

We ran theme check against a 190-file theme in October 2026. The first run reported 47 warnings, 9 of them deprecated filters that would have broken on the next theme release, and the whole check took under 30 seconds in CI.

The drift problem

The admin code editor lets a merchant change JSON templates, section settings and occasionally Liquid. Those changes live on the store, not in your repository. A push from a stale branch silently reverts the merchant's last week of homepage work, and nobody notices until a campaign page looks wrong.

Two habits fix it. Pull before every deploy, and review the pulled diff as part of the release rather than committing it blind. If the merchant edits frequently, giving them a section-based setup with fewer direct template edits is worth more than any pipeline.

Continuous deployment, carefully

Most teams stop short of auto-deploying on merge, and they are right to. A theme is a shared, live artefact with no transactional rollback; a bad deploy affects every visitor immediately, which is a different risk profile from pushing an API.

The middle path: auto-deploy to an unpublished theme on merge to main, and make the live promotion a manual, tagged step. That keeps review fast and the live push deliberate.

If you do automate the live step, gate it on theme check passing, a build of the storefront with no Liquid errors, and a smoke test on the staging URL. And publish the previous theme's ID somewhere in the pipeline output, because under pressure nobody wants to find it in the admin.

Where this goes wrong in practice

Third-party app blocks. Apps inject script tags and app blocks that are not in your repository. Pushing a theme can orphan app blocks in templates, so re-enable them after every deploy and check the app's own configuration survives.

Large asset files. Themes have an asset size ceiling, and binary assets inflate the repository. Keep source design files out of Git and commit only the built assets.

The development theme is not the live theme. Section IDs differ between copies, and app blocks referenced by ID break when a theme is duplicated. Test the app-block-dependent pages on the staging theme, not on dev.

Our verdict: Git plus CLI plus theme check is worth doing on any store where more than one person touches the theme, and the limitation to respect is that the store, not the repository, is the source of truth for template settings.

If you are choosing the theme itself, the real cost of a custom Shopify theme puts numbers on the build, and Horizon theme review covers whether a modern block-based theme reduces the need for custom code at all.

7-day free trial · all themes included · cancel anytime