Ploy Code Sync

Last updated

Connect a GitHub repository to your Ploy Site and collaborate with your dev team directly in code.

This integration is specific to Ploy Site — it syncs the underlying codebase of a single site with a GitHub repository. It is not a workspace-level or account-level integration. Ploy's Agent's edits commit to your repo, and any commits your team pushes flow back into the Ploy sandbox when you click Sync from GitHub in your Site Settings. Each one of your marketing sites lives in code — exactly where your engineers already work.

Code Sync and source code access with ploy site git are available on paid plans only. See the FAQ. If Connect GitHub is unavailable, check your plan under Settings then Billing.

Prefer not to use GitHub? On a paid plan, use ploy site git to clone your site's code and push changes with plain Git.

How the Integration Works

  1. Connect — For each workspace, its Owners and Admins can Authorize Ploy's GitHub App. This enables each Site in the workspace to make available a repo url such as git@github.com:ployspace/your_unique_site_name_slug.git.
  2. Sync — Ploy initiates the repo in your sandbox during site creation.
  3. Collaborate — Ploy's Agent commits changes to branches, opens PRs, and can also pull your team's external updates from the sync'd GitHub repo.

Tip: Every commit Ploy's Agent makes includes a clear message so your team can review changes like any other PR.

Tip: Using git sync is an Advanced feature. If Ploy's site editor and your external code changes conflict in the branch, you can ask Ploy's Agent to resolve the conflicts, but we also advise the usual developer best practices regarding source control collaboration.

Connecting a Repository

  1. Open Workspace Settings, then select Developer. On the Ploy Code Sync row, select Connect and authorize the Ploy GitHub App from the @ployspace org.

Permissions

The Ploy GitHub App requests limited access to:

  • Create branch or tag
  • Push to the repo

Inviting more GitHub users to collaborate

  • Go to Site Settings → Developer
  • Find the Source Control - Collaborators section
  • Type in a literal GitHub username (not email) to invite that user
  • Collaborator access can be removed by admins and owners at any time

Connecting to GitHub third-party integrations

Ploy-managed repositories don't support third-party GitHub integrations for security reasons. If you need to connect one, create a mirror of your repository in your own GitHub account (or another Git host) and set up the integration there. You'll need to set up a sync workflow to keep the mirror in step with your Ploy repo.

Syncing Changes

Pushing from Ploy

When Ploy's Agent edits your site, changes are committed to your connected branch. You can opt to:

  • git pull on your local copy then continue the work
  • Create a new git remote and sync it to your own server then follow your team's code review workflows. Sync back to the github.com/ployspace remote when you want to update the live Ploy preview.

Pulling from GitHub

When your team pushes commits to the repo (hotfixes, design tweaks, new components), sync to bring them into Ploy. Select Sync from GitHub on the site's Developer page, run ploy site code-sync sync, or ask Ploy's Agent to "Sync from GitHub". If Ploy's Agent can't save its edits because GitHub has newer commits, it syncs from GitHub once and tries the save again.

Note: Ploy uses git pull --rebase --autostash so local sandbox edits aren't lost during a sync.

Disconnecting GitHub Integration

To remove git push access to the Ploy site:

  1. You must be an Admin or Owner role in the Workspace
  2. Open Workspace Settings, then select Developer. On the Ploy Code Sync row, select Connected, then choose Disconnect. Confirm Disconnect. Your site's code stays intact, but future edits no longer sync.
  3. Confirm — your site's code stays intact, but future edits no longer sync.
  4. You can reconnect at any time.

Troubleshooting

  • Sandbox is starting — If Sync from GitHub reports that the sandbox is starting, the site environment is still coming online. This is temporary. Wait briefly, then retry the sync.
  • Push rejected — Usually means the remote has new commits. Perform a git pull --rebase --autostash in your local copy, resolve conflicts, then try git push again.
  • Permission denied — Workspace Admins and Owners can try to re-authorize the GitHub App and confirm the GitHub username attempting to pull or push the repo is in the Site → Developer → Source Control → Collaborator list.
  • Merge conflicts — Resolve in GitHub, then ask Ploy's Agent to pull the resolved branch.
  • Publishing paused because storage holds newer changes: this happens when someone pushed commits straight to GitHub. Your edits are safe in the preview. Ask Ploy's Agent to sync the source, then publish again. If the sync reports a conflict, resolve it and sync again.

What's Next?