Shopify theme previews

How previews work

For a repository that holds a Shopify theme, Auditor can push each reviewed pull request to an unpublished theme on a store and put the preview link in the walkthrough comment and the description's Preview section. It is off for every repository until you turn it on in that repository's settings, on its Shopify tab: choose a store at the top, then switch on Previews. Later pushes update the same theme, so the link stays the same, and the theme is deleted when the pull request closes.

Content the store keeps

Many theme repositories leave their content to the store: a .shopifyignore keeps JSON templates, section groups, theme settings or locales out of every push. A new theme pushed that way would have no templates, and every page would be a 404. So on each deploy Auditor reads the published theme's copy of the files .shopifyignore leaves out and uploads them with the commit, and the preview says how many it copied. The published theme is only read. If you would rather preview against a theme that already holds its own content, set Deploy to one theme to that unpublished theme's id: every pull request is then pushed to it, .shopifyignore applies as written, and the theme is shared and never deleted.

Reaching a store

There are two ways to reach a store. Under Shopify on the Auditor page's Add-ons tab, sign in to Shopify once by confirming a code; each repository can then search that account's stores. Deploys act as the account that signed in, and Auditor asks for a new sign-in when Shopify ends the session. Or give one repository a Theme Access password for its store: it can only touch themes and is not tied to a person. A store behind the password page also needs its storefront password, which Auditor uses only to load pages.

Once a repository has a store chosen, its reviews also check what each pull request removes (sections, blocks, setting ids, alternate templates) against the merchant content on the store's published theme, and new metafield reads against its definitions. See Merchant content on the store.

To set a repository up from a terminal or a pipeline instead, use auditor preview set with a Theme Access password.

Build setup and deploys

Auditor works out how the repository becomes a theme the first time it deploys one (a plain theme needs nothing; a built one gets its install command, build command and theme directory read from the repository) and stores that as the repository's Build setup, which you can edit. A build runs in an isolated sandbox that reaches package registries only and never holds the store credential. A second sandbox holds the credential, receives only the theme's own folders, and runs nothing from the repository: it uploads them with the Shopify CLI. After a deploy, Auditor loads the pages you list and notes HTTP errors and Liquid errors printed into the page. A deploy Shopify rejects files of is reported as not deployed, with the files and Shopify's reason for each.

Changes made on the store

Merchants and Shopify's AI edit themes on the store, so a branch falls behind it. After a deploy, Auditor compares the branch with the store's published theme and lists the content files that are missing or differ: JSON templates, section groups, config/settings_data.json, the locale files under locales/ that the language editor writes translations to, and files matching the repository's AI-generated files patterns. They are compared by their path inside the theme, wherever the repository keeps them, and files in .shopifyignore are left out. JSON files are compared as data, so key order and Shopify's header comment do not count, and the note says what differs: sections only on the store or only in the branch, sections with different settings, or translation strings only on one side or with different text. The store's themes are only read.

Comment @auditor pull to get the store's copies as a pull request into the branch. Nothing is written to the branch itself: the pull request carries each file as the store holds it, so every change it would make, including anything it would undo, is in its diff for review before the merge. Files the pull request you comment on changes itself are left out, since the store's copy is usually the older one there: a pull request that adds a section to templates/index.json or a string to locales/en.default.json keeps its change, and the answer lists each such file under Left as they are. Add --all (@auditor pull --all) to bring those in too: the store's copy then replaces the pull request's version of each, the pull request Auditor opens says which files that applies to, and the diff shows what is undone. --theme and a theme id pull from another theme, and --branch and a branch name open the pull request into that branch instead, compared with its latest commit; a branch has no pull request of its own, so nothing is left out there and --all changes nothing. Translation strings a pull request adds to the branch are not in the store's copy of the file until a deploy carries them there, so merge a locale pull before publishing, or take the store's strings into your file rather than the file whole.

Forks and limits

Pull requests from forks are skipped unless you turn that off, and a repository holds at most the number of preview themes you set (5 by default). Pages checked after a deploy are /, /collections/all and /cart unless you list others, up to 8. Turn off Delete the theme when the pull request closes to keep preview themes, and Compare with the published theme to skip the store comparison. Previews are never published.