Connecting Your Theme to a GitHub Repository
GitHub Theme Sync
Cartly can automatically keep your theme up to date with a GitHub repository. Whenever you push changes to the connected branch, your storefront theme updates within minutes ā no manual uploads required.
Requirements
- A Cartly Pro or Enterprise plan (GitHub sync is not available on Starter/Growth)
- A GitHub account with access to the repository you want to connect
- The theme must already be installed in your store's theme library
Step 1: Connect Your GitHub Account
Navigate to Online Store ā Themes and click Add Theme ā Connect from GitHub. A popup will open asking you to authorize Cartly to read your repositories. Click Authorize and complete the GitHub login.
Step 2: Choose a Repository and Branch
After authorization, a dialog will show your accessible repositories. Select the repository containing your theme files and choose the branch you want to deploy from (usually main or production). Then choose which theme slot in your library to update.
Step 3: Initial Sync
Click Connect. Cartly downloads all files from the repository and populates your theme. This initial sync may take up to a minute depending on the number of files. A Syncing badge appears on the theme card while the process is running.
Automatic Updates
After setup, any push to the connected branch automatically triggers an update. Changed files are detected and applied within about 2 minutes. A sync status badge on the theme card shows whether the last sync was successful:
- Synced (green) ā last sync completed successfully
- Syncing (blue) ā sync in progress
- Error (red) ā last sync failed; hover for the error message
Read-Only Mode
While a theme is connected to GitHub, theme files cannot be edited manually in the Cartly code editor. An amber banner in the editor reminds you that the repo is the source of truth. To make manual edits, disconnect the repository first.
Disconnecting
Open the theme code editor and click Disconnect from GitHub in the banner, or navigate to Themes, open the theme options, and select Disconnect Repository. After disconnecting, the theme files remain in place and can be edited freely.
Troubleshooting
- Sync not triggering ā Verify the GitHub webhook is set up in your repo's Settings ā Webhooks pointing to your store.
- Missing files ā Check that the repository contains a valid theme structure (layouts/, sections/, templates/).
- Authentication error ā Reconnect your GitHub account from Online Store ā Themes ā Add Theme ā Connect from GitHub.