GitHub Theme Sync

Connect a theme to a GitHub repository. Any git push automatically deploys updated theme files to your Cartly store.

Setup

GitHub theme sync requires three environment variables on your Cartly server:

GITHUB_CLIENT_ID=your-oauth-app-id
GITHUB_CLIENT_SECRET=your-oauth-app-secret
GITHUB_WEBHOOK_SECRET=your-webhook-secret

Create a GitHub OAuth App at Settings → Developer Settings → OAuth Apps with callback URL https://your-domain/admin/theme/github/callback. Set the webhook secret in your repo settings pointing to https://your-domain/webhooks/github/{shop_id}.

GET/admin/theme/github/connectadmin-jwt

Returns GitHub OAuth authorization URL. Redirect merchant's browser to this URL to start the OAuth flow.

GET/admin/theme/github/reposadmin-jwt

Lists all repositories accessible to the connected GitHub account.

POST/admin/theme/library/:id/github-connectadmin-jwt

Links a theme install to a GitHub repo+branch. Triggers an initial full sync Temporal workflow (timeout 5 min).

Request Body

json

{
  "auto_deploy": true,
  "branch": "main",
  "repo": "owner/repo-name"
}

Push Webhook

When GitHub sends a push event to POST /webhooks/github/{shopId}, Cartly verifies the HMAC-SHA256 signature, then launches an IncrementalSync Temporal workflow (timeout 2 min) that fetches changed files from the GitHub API and updates theme_files on the ThemeInstall record.

Signature Verification

X-Hub-Signature-256: sha256=HMAC-SHA256(body, GITHUB_WEBHOOK_SECRET)

Workflow

Both sync workflows (GitHubInitialSync and GitHubIncrementalSync) run as Temporal activities and are idempotent — re-running is safe.

Read-Only Guard

While a theme is connected to GitHub, theme file mutations via the code editor are blocked with a 423 Locked response. Disconnect the repo to edit files manually.

GET/admin/theme/library/:id/github-statusadmin-jwt

Returns sync status: repo, branch, last_commit_sha, sync_status (idle/syncing/error), sync_error_log.

Code Examples

bash

# 1. Get OAuth URL
curl -H "Authorization: Bearer $TOKEN" \
  https://cartly.pro/admin/theme/github/connect

# 2. After OAuth: link theme to repo
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo":"acme/my-theme","branch":"main","auto_deploy":true}' \
  https://cartly.pro/admin/theme/library/{themeId}/github-connect