Help Center | GhostClick

Run your GhostClick journeys on a theme preview from your build, and stop a release that breaks your store.

What It Does

The GhostClick theme check tests a theme before it reaches your live store. Your developer gives it the theme's preview link, GhostClick runs the journeys and page checks you chose on that preview, and the check passes or fails with a link to each report. When a shopper can no longer get through, it fails, the same way a failing test would. It never pushes, changes or deletes a theme, so it fits however your team already ships themes: a GitHub Action, or one step in any other build.

It comes with the Growth plan and up. Each journey checked uses one audit from your monthly allowance. Page checks are free.

Before You Start

Your store is on the Growth plan or above.
You have at least one journey saved on the store, so GhostClick knows what to check. No journey yet? Settings, GitHub Action offers Six critical checks: run it once and save it as a journey.

Make a key

In GhostClick: Settings, GitHub Action

Save it in GitHub

As the secret GHOSTCLICK_TOKEN

Add the workflow

Paste it into .github/workflows/ghostclick.yml

Run it on a preview

Paste the theme's preview link and run

1. Make a Key

In GhostClick, open Settings, then GitHub Action.
Pick the store, and tick the journeys and page monitors the check should run.
Leave Report links anyone can open ticked, unless the theme repository is public.
Click Make key and copy it. It starts with gc_ci_ and is only shown once.

Not the one who looks after the code? Right after you make the key, Send it to your developer emails them the key, these steps and the workflow file, and their replies come back to you.

2. Save the Key in GitHub

In the theme repository, open Settings, Secrets and variables, Actions. Under Secrets, add one called GHOSTCLICK_TOKEN and paste the key.

3. Add the Workflow

Create the file .github/workflows/ghostclick.yml with this. Settings gives you a copy with your store already filled in.

name: GhostClick theme check
on:
  workflow_dispatch:
    inputs:
      preview_url:
        description: Theme preview link
        required: true
      journeys:
        description: Journeys to run, by name, comma separated (or all). Empty runs the ones on the key.
        required: false
  pull_request:

permissions:
  contents: read
  pull-requests: write # only for the pull request comment

jobs:
  ghostclick:
    runs-on: ubuntu-latest
    steps:
      - uses: ghostclickhq/theme-check-action@v2
        with:
          ghostclick_token: ${{ secrets.GHOSTCLICK_TOKEN }}
          store: your-store.myshopify.com
          preview_url: ${{ inputs.preview_url || vars.GHOSTCLICK_PREVIEW_URL }}
          # Which journeys run: names as shown in GhostClick, one per line or
          # comma separated, or all. Empty runs the ones picked on the key.
          journeys: ${{ inputs.journeys || vars.GHOSTCLICK_JOURNEYS }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

4. Get the Theme's Preview Link

In Shopify admin, open Online Store, Themes. On the theme you want to check, open the … menu, choose Preview, and copy the address. It looks like https://your-store.myshopify.com/?preview_theme_id=123456789.

The share link (xxxx.shopifypreview.com), a theme editor link or the theme id on its own work too. The theme has to be on the same store as the key.

5. Run It

Whenever you like: in the repository, open Actions, GhostClick theme check, Run workflow, paste the preview link and run.
On every pull request: under Settings, Secrets and variables, Actions, Variables, add GHOSTCLICK_PREVIEW_URL with the preview link of the theme your branch deploys to. Each pull request then checks that theme.

Not on GitHub?

The same check runs as one step in GitLab, Bitbucket, CircleCI or a deploy script (Node 18 or later):

curl -fsSL https://raw.githubusercontent.com/ghostclickhq/theme-check-action/v2/ghostclick-check.mjs -o ghostclick-check.mjs
GHOSTCLICK_TOKEN="$GHOSTCLICK_TOKEN" \
GHOSTCLICK_PREVIEW_URL="https://your-store.myshopify.com/?preview_theme_id=123456789" \
GHOSTCLICK_JOURNEYS="" \
node ghostclick-check.mjs

It exits 0 when every check passed and 1 when one failed, with a line and a report link for each failure.

Info

A GitHub key can only run the journeys and pages you ticked for it, on one store. It cannot start any other audit, read your account or change anything. GhostClick stores only a one-way hash of it, so it is shown once. You can see when each key was last used and revoke it from the same Settings card.

6. Read the Result

The build log and the GitHub job summary list each check: passed or failed, why, and a link to the full report. On GitHub, a pull request also gets one comment, updated on each run. If you left Report links anyone can open ticked when you made the key, your developers can open the reports without a GhostClick login. Turn it off for a public repository.

Your themes, your saved journeys and their history are never touched: a check from GitHub shows up in Audits with a GitHub check label and does not count as a run of the journey.

Tip

Journeys that have run before replay their recorded steps, so a check usually finishes in a couple of minutes. See Journeys & monitoring.

For Developers

The Action is open source at ghostclickhq/theme-check-action. Its README lists every option: a preview link or a theme id (theme_id), a minimum page score, and reporting without failing the build.

Check a theme before it goes live