Proof documentation
Bring your theme, your build, and a preview store. Proof connects them through GitHub Actions.
On this page
Getting started
Stable release. Proof v1.0.0 is available on GitHub Marketplace. Use an authorized preview store and never target a live theme.
Proof builds pull request code in one job, then deploys the resulting theme files in a separate job. The deployment updates a PR comment with storefront and Theme Editor links.
You will need a Shopify theme in a GitHub repository, GitHub Actions enabled, and permission to manage repository environments. Your GitHub plan must support environments for the repository’s visibility.
- Create a Theme Access credential and save it in GitHub.
- Add the reusable workflow to your repository.
- Configure a build, or skip this step for a theme at the repository root that needs no build.
Connect Theme Access
Use a dedicated password from Shopify’s free Theme Access app. This is not your Shopify login password or the storefront password.
- Install Theme Access on your preview store.
- Select Create theme password and enter the recipient’s details. Use a dedicated credential for Proof.
- Open the emailed link and copy the password. It can only be viewed once; the link expires after seven days or after viewing.
-
In your GitHub repository, open
Settings → Environments → New environment. Name
it
theme-preview. - Add the following secret and variable to that environment.
| Name | Type | Value |
|---|---|---|
SHOPIFY_CLI_THEME_TOKEN |
Secret | Your Theme Access password |
SHOPIFY_FLAG_STORE |
Variable | example.myshopify.com |
The store domain is not sensitive. The password is. Never put it in your repository, configuration file, or workflow YAML. Theme Access can modify store themes; treat it as a privileged credential.
Only deployment and cleanup jobs use this environment. Keep the
password environment-scoped and include the named secrets mapping
below to authorize access from the called workflow. Avoid broad
secrets: inherit. Required reviewers can add an
approval step to both deployment and cleanup.
To revoke access, delete the password in Theme Access. To rotate it, create a new password and replace the GitHub environment secret. See Shopify’s Theme Access guide.
Add the GitHub workflow
In your theme repository, select
Add file → Create new file. Name it
.github/workflows/theme-proof.yml, copy the workflow
below, and commit it. The reusable workflow supplies separate
build, deploy, and cleanup jobs. Prefer it to the single-step
Action snippet supplied by Marketplace so builds stay separate
from credentialed deployment.
This example uses the exact v1.0.0 release. You can
use the moving v1 tag to receive compatible v1
updates. Internal Action references remain pinned to reviewed
commits.
name: Theme Proof
on:
pull_request:
types: [opened, synchronize, reopened, closed]
permissions:
contents: read
pull-requests: write
jobs:
preview:
if: github.event.pull_request.head.repo.full_name == github.repository
uses: BillyNoyes/Proof/.github/workflows/preview.yml@v1.0.0
with:
config: theme-proof.config.json
environment: theme-preview
secrets:
SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
The condition skips fork pull requests. Keep it in place. Do not
replace pull_request with
pull_request_target to obtain secrets for untrusted
code.
| Input | Default | Purpose |
|---|---|---|
config |
theme-proof.config.json |
Build config path, relative to the repository root |
environment |
theme-preview |
GitHub environment holding the credential |
target-mode |
development-context |
The only supported target mode |
shopify-cli-version |
4.8.0 |
Pinned CLI version for deployment and cleanup |
The workflow currently uses Node.js 24 on Ubuntu.
pull-requests: write is needed to create and update
the preview comment.
Configure your build
Add theme-proof.config.json to your repository. It is
static JSON, not executable configuration. Optional setup,
install, and build commands run in that order.
No build, including Dawn
If the theme is at the repository root and needs no build, no config file is required. The explicit equivalent is:
{
"version": 1,
"build": {
"themeDirectory": "."
}
}
A theme with a build step
Specify your package manager and commands. Proof does not need to
know whether you use Easel, Vite, or another tool. Point
themeDirectory at the complete deployable theme, not
just a folder of compiled assets.
{
"$schema": "https://raw.githubusercontent.com/BillyNoyes/Proof/main/schema/theme-proof.schema.json",
"version": 1,
"build": {
"workingDirectory": ".",
"setup": "npm install --global pnpm@10.28.0",
"install": "pnpm install --frozen-lockfile",
"command": "pnpm build",
"themeDirectory": "."
}
}
Nested themes and output directories
Both directory paths are relative to the
repository root. For example, a project in
themes/storefront that writes a complete theme to its
dist directory would use:
{
"version": 1,
"build": {
"workingDirectory": "themes/storefront",
"install": "npm ci",
"command": "npm run build",
"themeDirectory": "themes/storefront/dist"
}
}
Directory defaults are .; commands are omitted by
default. Each command has a 15-minute timeout. Absolute paths,
paths outside the workspace, unknown properties, and unsupported
config versions are rejected.
A missing default config uses the no-build defaults. A missing custom config path is an error. Use the JSON Schema for editor validation.
The preview lifecycle
The current implementation uses a Shopify development context derived from the repository ID and PR number. Subsequent commits use the same context, rather than intentionally creating a new theme for each commit.
- Open or update: build, stage, validate, then push with Shopify CLI’s strict validation.
- Review: update one comment with the storefront and Theme Editor links.
- Close or merge: run cleanup and update the comment.
New builds cancel older builds for the same PR. Deployment and cleanup are serialized without canceling running mutations; stale commits and cleanup for reopened PRs are skipped. Development themes are temporary, not permanent staging environments. Context reuse, manual deletion, and repeated cleanup have passed private development-store tests. Protected storefronts still require their password, and the Theme Editor requires an authorized admin login. Natural theme expiration and authenticated UI interactions were not exercised.
Existing-theme selection and new unpublished-theme creation are
not implemented.
Only development-context is accepted. Live themes are
rejected as preview targets.
Build code is not deployment code
The security boundary is the separation between jobs. Filtering environment variables is a precaution, not a sandbox for arbitrary PR code.
- The build job checks out the PR head SHA and runs repository commands with read-only repository access and no Shopify environment.
-
Only theme directories are staged:
assets,blocks,config,layout,locales,sections,snippets, andtemplates. - The deployment job validates the artifact again and does not run repository build scripts.
-
Artifacts must include
layout/theme.liquid. Symlinks and unsupported file types are rejected. - Default limits are 5,000 files, 10 MiB per file, and 100 MiB total.
Store credentials and deployment targets do not belong in PR-controlled build configuration. Protect workflow changes and configure GitHub environment approvals where appropriate. Do not use a persistent self-hosted runner for untrusted builds.
Report suspected vulnerabilities privately through the repository’s security policy.
Troubleshooting
The deployment cannot find the credential
Check the environment name, then confirm
SHOPIFY_CLI_THEME_TOKEN is an environment
secret and SHOPIFY_FLAG_STORE is an
environment variable. Required reviewers and
deployment restrictions can hold or block the job. Fork PRs are
not supported for automatic deployment.
The theme artifact is invalid
Check that themeDirectory contains the full theme,
including layout/theme.liquid. A Vite assets-only
output directory is not a deployable theme. Remove symlinks and
inspect the reported file-size or file-count limit.
The build command cannot be found
Install the required tool in build.setup. The
workflow provides Node.js, but does not infer or install your
project’s package manager or dependencies.
The PR comment cannot be updated
Confirm that the caller grants
pull-requests: write and that repository or
organization policy allows it. Do not work around token
restrictions by exposing a privileged token to the build.
A preview remains after the PR closes
Check the cleanup job for pending environment approval or a failed run. Retry the failed job after resolving the cause. If manual removal is necessary, verify the store and theme identity before deleting anything.
Still stuck? Open an issue with the failing step and sanitized logs. Never include a password or token.
Release status
Proof v1.0.0 is the first stable release on
GitHub Marketplace. It includes build configuration, artifact validation,
development-context deployment, comments, and cleanup.
The preview lifecycle has passed private development-store tests, and internal Action references are pinned to reviewed commits. Read the integration report for coverage and limits. Existing and unpublished theme modes remain future work.
Read the implementation plan, check releases, or contribute on GitHub.